Docker Compose

Install Governor on one Linux server with Docker Compose, using your own PostgreSQL database for Governor’s data.

To try the platform on your own machine first, use the demo instead. It includes its own databases and sample data.

Before you start

A Linux server that meets the baseline, with Docker and Docker Compose v2 or later, or Podman with Podman Compose.
An empty PostgreSQL 13 or later database for Governor, and the user name and password for it.
The production bundle, governor-compose-prod.zip. Contact Synthesized to get it. It contains the docker-compose.yml for Governor’s containers.
Your Synthesized license key.
A DNS name for Governor and a TLS certificate for it.

1. Unpack the bundle

Unzip the bundle into a folder on the server, and run the commands on this page in that folder.

unzip governor-compose-prod.zip -d governor
cd governor

The settings on this page go in docker-compose.yml, on the backend service unless stated otherwise.

2. Connect Governor to its database

Set the database URL and credentials:

services:
  backend:
    environment:
      - SPRING_DATASOURCE_URL=jdbc:postgresql://host.docker.internal:5432/governor (1)
      - SPRING_DATASOURCE_USERNAME=apiuser (2)
      - SPRING_DATASOURCE_PASSWORD=apipassword (3)

1	The JDBC URL of Governor’s database. If PostgreSQL runs on the same server as Docker, use `host.docker.internal` as the host name.
2	The database user.
3	Its password.

3. Generate the secrets

Generate three secrets, and keep a copy of each in your secret store:

Linux and macOS
Windows (PowerShell 7.2 or later)

openssl rand -base64 256 | tr -d '\n'   # JWT_SECRET
openssl rand -base64 32                 # CREDENTIALS_ENCRYPTION_KEY
openssl rand -hex 20                    # ADMIN_DEFAULT_PASSWORD

[Convert]::ToBase64String([Security.Cryptography.RandomNumberGenerator]::GetBytes(256))  # JWT_SECRET
[Convert]::ToBase64String([Security.Cryptography.RandomNumberGenerator]::GetBytes(32))   # CREDENTIALS_ENCRYPTION_KEY
[Convert]::ToHexString([Security.Cryptography.RandomNumberGenerator]::GetBytes(20))      # ADMIN_DEFAULT_PASSWORD

Windows PowerShell 5.1 doesn’t support these commands.

Then set them, with the first administrator’s email address:

Variable What it’s for

Variable	What it’s for
`JWT_SECRET`	Signs sign-in tokens. Replace `[your jwt secret]`. If it changes later, every user is signed out.
`CREDENTIALS_ENCRYPTION_KEY`	Encrypts the data source passwords Governor stores, with AES and this 256-bit key. Set your own key in every production installation; add the line if your file doesn’t have it. If the key is lost, the stored passwords can’t be recovered.
`ADMIN_EMAIL`, `ADMIN_DEFAULT_PASSWORD`	The first administrator account. Replace `[your admin email]` and `[your default admin password]`. Change the password after the first sign-in.

JWT_SECRET

Signs sign-in tokens. Replace [your jwt secret]. If it changes later, every user is signed out.

CREDENTIALS_ENCRYPTION_KEY

Encrypts the data source passwords Governor stores, with AES and this 256-bit key. Set your own key in every production installation; add the line if your file doesn’t have it. If the key is lost, the stored passwords can’t be recovered.

ADMIN_EMAIL, ADMIN_DEFAULT_PASSWORD

The first administrator account. Replace [your admin email] and [your default admin password]. Change the password after the first sign-in.

To rotate the encryption key later, set CREDENTIALS_ENCRYPTION_KEY to the new key and the old one, separated by a semicolon: <new-key>;<old-key>. At the next restart, Governor re-encrypts the stored passwords with the new key. You can then remove the old key.

4. Add the license key

Replace [your synthesized key] in SYNTHESIZED_KEY with your license key. The key is checked offline: Governor doesn’t need internet access for it.

While the placeholder is there, Governor runs in free mode: Oracle, SQL Server, Db2, Snowflake, SAP (SAP HANA, S/4HANA and OData V2) and CSV data sources are blocked, and PostgreSQL, MySQL and MariaDB data sources are limited to 20 tables and 100,000 rows per table. See License.

5. Keep storage and logs on the host

Keep the platform’s working storage and its logs on the server’s file system rather than inside the containers. In docker-compose.yml, uncomment the volumes lines, and replace [your path to storage] and [your path to logs] with folders on the server, for example:

    volumes:
      - /data/governor/storage:/app/storage
      - /data/governor/logs:/app/logs

The backend container runs as user 1001 and group 0, so give that user the folders:

sudo chown -R 1001:0 /data/governor/storage /data/governor/logs

Allow at least 100 GB of free space for them. See Storage.

6. Start Governor

docker compose up --detach
docker compose ps

docker compose ps should show the backend and frontend services running and healthy. On the server, Governor’s web UI is at http://localhost:80. Sign in with ADMIN_EMAIL and ADMIN_DEFAULT_PASSWORD.

With Podman, run podman-compose up -d and podman-compose ps instead.

Red Hat Enterprise Linux with SELinux

Allow the frontend to listen on port 80. Port 80 is usually already labelled http_port_t, so modify the label with -m:

sudo semanage port -m -t http_port_t -p tcp 80
echo "net.ipv4.ip_unprivileged_port_start=80" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

7. Set up TLS termination

Governor must be served over HTTPS from any address other than localhost. Put a reverse proxy with your certificate in front of it. With nginx:

Install nginx.

Create a file named after your domain in /etc/nginx/sites-available:

server {
    listen 443 ssl;
    server_name [domain name];

    ssl_certificate [path-to-your-certificate]/fullchain.pem;
    ssl_certificate_key [path-to-your-certificate]/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    location / {
        proxy_pass http://localhost:80;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

[domain name] is Governor’s DNS name, for example governor.example.com, and [path-to-your-certificate] is the folder that holds its certificate and key.

Link the file into /etc/nginx/sites-enabled, and reload nginx with nginx -s reload.

To renew certificates automatically, you can use Certbot.

Check that it works

Open https://[domain name] and sign in as the first administrator.
Change the administrator’s password.
Add a data source and test its connection.

Troubleshooting

Problem What to do

Problem	What to do
`backend` isn’t `healthy`	Usually the database connection. Check `SPRING_DATASOURCE_URL`, the user name and the password, and read `docker compose logs backend`.
Sign-in fails on the DNS name	Serve Governor over HTTPS. Plain HTTP works only on `localhost`.
Port 80 is already in use	Stop the service using it, or change the frontend’s host port in `docker-compose.yml`, for example to `- "8080:80"`, and point the reverse proxy at it.
A data source is "not supported in the free version"	Set `SYNTHESIZED_KEY`, then run `docker compose up --detach` again.

backend isn’t healthy

Usually the database connection. Check SPRING_DATASOURCE_URL, the user name and the password, and read docker compose logs backend.

Sign-in fails on the DNS name

Serve Governor over HTTPS. Plain HTTP works only on localhost.

Port 80 is already in use

Stop the service using it, or change the frontend’s host port in docker-compose.yml, for example to - "8080:80", and point the reverse proxy at it.

A data source is "not supported in the free version"

Set SYNTHESIZED_KEY, then run docker compose up --detach again.

For more, see Troubleshooting.

Next steps

Connect workers in other networks: Synthesized Workers, and secure them with Worker–Governor mTLS.
Set up single sign-on or LDAP.
Plan backups and monitoring.
When a new release comes out: Update Docker Compose.