How to install SysON?

This section delves into the detailed step-by-step instructions for installing SysON. Detailed explanations walk you through each step.

1. Get SysON

1.1. Installing SysON with Docker Compose

The easiest and most straightforward method to install SysON using Docker Compose, which automatically installs Java and PostgreSQL.

Before you proceed with the installation, please ensure you have the following prerequisites:

Docker installed.

SysON is distributed as a docker container. To install SysON, just download the docker-compose file and run the following docker command in the same folder as the one where is the docker-compose.yml file:

docker compose up

This method installs SysON (matching the version tagged in this documentation) along with a PostgreSQL database, all within a Docker container.

To install a specific version vYYYY.MM.0, edit the docker-compose.yml file and replace the tagged version with your desired version. For example, update the following line in the docker-compose.yml: app: image: "${IMAGE_TAG:-eclipsesyson/syson:*vYYYY.MM.0*}"

All accessible versions of SysON as Docker containers are listed in the SysON Docker registry.

Once your Docker up, please go directly to the Open your web browser section!

1.2. Installing SysON Manually

Detailed instructions for manually setting up SysON, including PostgreSQL installation with Docker, downloading the JAR application, and starting it manually.

Before you proceed with the installation, please ensure you have the following prerequisites:

Java supported version
Docker installed, or an existing supported database installation with a user that has administrator privileges.

SysON is distributed as a single executable Java Archive JAR which contains the complete SysON application along with all its dependencies. This distribution simplifies the setup process, enabling convenient exploration of SysON’s features.

Stable versions

Only YEAR.MONTH.0 versions are stable and suitable for production deployments. Other versions, such as intermediate releases, are intended solely for testing purposes. They’re not recommended for production use due to their potential for further changes and instability. Always use the stable .0 releases for any production environments to ensure reliability and support. For more details see SysON development cycle.

To download the latest pre-built JAR for SysON, follow these steps:

Before you begin the installation process, navigate to the download page for org.eclipse.syson.syson-application-YYYY.M.X.jar to access all versions.
Identify the SysON latest available version for download.
Click the latest version to open its specific page.
In the Assets section, locate the JAR file named org.eclipse.syson.syson-application-YYYY.M.X.jar.
Click the JAR file to start the download to your local machine.

This process ensures that you get the most recent version of the SysON application in the form of a pre-built JAR file.

1.2.1. Start the database instance

SysON uses PostgreSQL as its database.

For development or local testing, the simplest approach is to initiate a PostgreSQL instance using Docker.

docker run -p 5434:5432 --name syson-postgres \
                            -e POSTGRES_USER=dbuser \
                            -e POSTGRES_PASSWORD=dbpwd \
                            -e POSTGRES_DB=syson-db \
                            -d postgres

For Windows users, here is the same command on one line:

docker run -p 5434:5432 --name syson-postgres -e POSTGRES_USER=dbuser -e POSTGRES_PASSWORD=dbpwd -e POSTGRES_DB=syson-db -d postgres

This may take a while the first time you run this as Docker will first pull the PostgreSQL image.

If you don’t have Docker or prefer to use an existing PostgreSQL installation, modify the following command-line parameters and ensure the POSTGRES_USER possesses administrative rights on the database. These rights are necessary for the automatic creation of the database schema.

1.2.2. Start the application

To run the application, you’ll need to use the Java Runtime Environment (JRE) to execute the pre-build JAR (org.eclipse.syson.syson-application-YYYY.M.X.jar) you downloaded earlier.

Go to the folder containing the org.eclipse.syson.syson-application-YYYY.M.X.jar and run the command:"

java -jar path\to\your\syson-application-YEAR.MONTH.0.jar \
          --spring.datasource.url=jdbc:postgresql://localhost:5434/syson-db \
          --spring.datasource.username=dbuser \
          --spring.datasource.password=dbpwd

1.3. Open your web browser

Navigate to http://localhost:8080 to experience SysON.

To end your local testing session, ensure you stop the running PostgreSQL Docker container using the command docker kill syson-postgres. Please note that this will erase all the data you have generated during testing.

If you encounter any issues during the installation process, please refer to the troubleshooting guide for detailed solutions.

1.4. Other resources

Configuring HTTPS for local server deployment of SysON for testing purposes