Skip to Content

Docker deployment

Use the Docker deployment when Docker Desktop is approved for the target workstation. The Compose stack runs PostgreSQL, the API, web application, and Yjs collaboration service locally.

See Installation for shared prerequisites, endpoint defaults, backup guidance, and the Community security boundary.

Requirements

  • A Windows workstation that meets Docker Desktop’s Windows requirements . Docker Desktop is not supported on Windows Server.
  • Docker Desktop  installed and running.
  • Docker Desktop using Linux containers, matching the release images.
  • docker compose version 2 available on PATH.
  • Administrator permissions for the Windows installer, or for running the installation helper from a protected installation folder.
  • A complete release package containing all four runtime image archives.

Release package contents

The package contains a Compose directory with docker-compose.yml, .env.example, PowerShell helpers, and an images folder containing exactly these four runtime image archives:

images\api.tar images\web.tar images\yjs.tar images\postgres.tar

postgres.tar must contain postgres:17. The three application images must share the release’s repository and version tag. Setup validates the complete bundle even if images are already cached locally. Installation loads the archives without building images or pulling them from a registry. PostgreSQL is kept on the internal Compose network and has no published host port.

Configure the package

The Windows installer runs install.ps1 for you. For a first installation, let that helper create .env: it copies .env.example and generates the database password and JWT key. If preserved configuration exists in %ProgramData%\SESModeler\docker.env, it restores that configuration instead. An existing .env is kept; do not overwrite it with the template during a reinstall or update.

If you manage .env manually, set valid values for:

POSTGRES_PASSWORD=<strong database password> JWT_KEY=<random value with at least 32 characters>

The deployment helper rejects a blank or template database password and a JWT key shorter than 32 characters. The JWT-key check is a helper configuration requirement; Community authentication uses guest cookies and shared model access, not enterprise login.

Application ports

Host ports default to:

WEB_PORT=3000 API_PORT=5150 YJS_PORT=1234

If you use the Docker installer, the Application ports page proposes these values, checks whether they are available, and lets you accept another available port or enter a different value between 1024 and 65535. Web, API, and Yjs must use different ports. Upgrades keep the ports already stored in .env.

If you run install.ps1 without Setup, set the same values in .env or pass -WebPort, -ApiPort, and -YjsPort.

The installer supplies the selected API and Yjs URLs to the web server at runtime, so changing WEB_PORT, API_PORT, or YJS_PORT does not require rebuilding the web image. The NEXT_PUBLIC_* values in .env.example are build-time fallbacks only.

PostgreSQL uses port 5432 inside the Compose network. There is no PostgreSQL host-port setting in the current template.

Install and start

With the Windows installer, select the application ports and complete Setup; it runs the installation helper and offers to open the browser after successful startup.

If using the extracted Compose package instead, open PowerShell in the directory containing install.ps1 (as administrator when the folder requires it), then run:

.\install.ps1 -OpenBrowser

The script:

  1. Checks Docker, the Docker daemon, and Compose v2.
  2. Validates all four archives and their image tags before changing the installation.
  3. Keeps the existing .env, restores preserved configuration, or creates .env with generated secrets on a first installation, then validates the deployment secrets.
  4. Stops this Compose project’s previous containers, checks the selected host ports, loads the four archives, and selects their application repository and version in .env.
  5. Starts PostgreSQL, reconciles the application role’s password for a preserved database, and starts the remaining Compose services with image building and registry pulls disabled.
  6. Waits for the API readiness endpoint on the selected API port.

An incomplete bundle is rejected before the existing stack is stopped, even if a missing image is already cached. Obtain the complete release package rather than trying to build from source on the installation machine. Installation diagnostics are retained in logs\setup-docker.log inside the package folder.

Verify the deployment

The examples below use the default ports. Substitute the ports selected during Setup when they differ:

Invoke-WebRequest http://localhost:5150/health/ready -UseBasicParsing Start-Process http://localhost:3000

The readiness endpoint confirms that the API can reach PostgreSQL and that the standard libraries have loaded. On the first start, allow extra time for database migrations and standard-library initialization.

Persistence

The Compose deployment creates named volumes for:

  • PostgreSQL data;
  • API data-protection keys; and
  • rich-text attachments.

Yjs collaboration state is held in process memory. PostgreSQL remains the durable source of truth for model and diagram state; restarting Yjs does not provide an independent durable copy of a collaboration document.

Stopping the stack does not remove its data volumes. Deleting the API data-protection volume invalidates existing Community guest cookies.

Start, stop, and logs

The package includes helpers for normal operations:

.\stop.ps1 .\start.ps1 .\logs.ps1 .\logs.ps1 api

You can also use the Compose commands directly:

docker compose ps docker compose logs --tail 100 api

Backup and restore

The current Docker backup helper creates a PostgreSQL SQL dump and an attachment-volume archive. It temporarily stops API writers while the snapshot is created:

.\backup-db.ps1

Restore a matching backup with:

.\restore-db.ps1 -InFile .\backups\backup-YYYYMMDD-HHMMSS.sql

Keep the matching -attachments.tar.gz file beside the SQL dump when attachments must be restored. Test restores on a copy before relying on them for operational recovery. The current helper is not a replacement for an organization-managed, encrypted, off-host backup process.

Updating

The update helper requires a directory containing all four archives listed above, including postgres.tar:

.\update.ps1 -ImagesDirectory C:\Path\To\NewImages

It validates the bundle, creates a database and attachment backup, loads all four archives, saves the previous configuration as .env.previous, and selects the new image repository and version in .env and the preserved configuration. It then recreates the services and waits for API readiness. Keep the previous release archives and backups until the new version has been verified. Restoring .env.previous alone does not undo database migrations; the helper does not provide a complete automatic rollback.

Uninstalling

The Docker uninstall helper stops and removes the project’s containers and attempts to remove its application images. It intentionally preserves the PostgreSQL, attachment, and data-protection volumes, along with the saved configuration in %ProgramData%\SESModeler\docker.env for reinstallation.

To remove all data as well, first confirm the Compose project name in .env, then remove its volumes explicitly. For the default project name:

docker volume rm systemmodel-studio_postgres_data docker volume rm systemmodel-studio_api_attachments docker volume rm systemmodel-studio_api_data_protection

Do not run these commands if the models or attachments must be preserved.

Troubleshooting

The API is not ready

Inspect the API logs and confirm that PostgreSQL is healthy:

docker compose ps docker compose logs --tail 100 api

The first API start may need time to apply migrations and load standard libraries.

The browser cannot connect to the API

Confirm that the API readiness endpoint responds on the selected API port. The web server receives the selected API and Yjs URLs at runtime; you do not need to rebuild the web image after changing host ports.

Docker is unavailable

Start Docker Desktop and wait until the daemon is ready. Confirm both commands work before rerunning the installer:

docker info docker compose version

A port is already in use

The default host ports are 3000, 5150, and 1234. If Setup reports that a port is already in use, review the suggested available port and click Next again. After installation, rerun Setup, or edit WEB_PORT, API_PORT, and YJS_PORT in .env and run install.ps1 again. PostgreSQL is not published on a host port.

Next step

Once the application opens and the API is ready, build your first model. You can begin with an empty Model Repository.