On-Premises Upgrades

Managing system upgrades requires correctly identifying the project name used by Docker Compose. Run the following commands to detect the active project name:

The NGINX container is optional. If it is not running, you can get the project name from the portal or database containers.

echo "NGINX (optional):"
docker inspect $(docker ps -qf "name=tursio-singleportal-nginx") \
  --format '{{ index .Config.Labels "com.docker.compose.project" }}'

echo "PORTAL:"
docker inspect $(docker ps -qf "name=tursio-singleportal-portal") \
  --format '{{ index .Config.Labels "com.docker.compose.project" }}'

echo "DATABASE:"
docker inspect $(docker ps -qf "name=tursio-singleportal-database") \
  --format '{{ index .Config.Labels "com.docker.compose.project" }}'

Ensure all values are the same — this project name is used in all the steps below with the ${project} placeholder.

Backup & Restore

Before running an upgrade, it is advisable to create a consistent backup. This causes brief downtime (~20–40 seconds). The steps are as follows.

First, stop the deployment:

docker compose -p $project stop tursio-singleportal-database

Then, back up the data in internal PostgreSQL:

docker run --rm \
  -v ${project}_tursio-singleportal-database-volume:/data \
  -v $(pwd):/backup \
  busybox tar -czvf /backup/db_backup_$(date +%F).tar.gz -C /data .

Also, back up the files in the portal file storage:

docker run --rm \
  -v ${project}_tursio-data:/data \
  -v $(pwd):/backup \
  busybox tar -czvf /backup/portal_backup_$(date +%F).tar.gz -C /data .

Now restart the services:

docker compose -p $project start tursio-singleportal-database

Finally, verify the backup integrity:

tar -tvf db_backup_*.tar.gz | head
tar -tvf portal_backup_*.tar.gz | head

To restore from a backup:

docker compose -p $project stop

docker run --rm \
  -v ${project}_tursio-singleportal-database-volume:/restore \
  -v $(pwd):/backup \
  busybox tar -xzvf /backup/db_backup_*.tar.gz -C /restore

docker run --rm \
  -v ${project}_tursio-data:/restore \
  -v $(pwd):/backup \
  busybox tar -xzvf /backup/portal_backup_*.tar.gz -C /restore

docker compose -p $project start

Deploy New Image

Tursio provides the link to the image tarball in a file named tursio-<version>-<account-name>-<release-date>.txt. For example, tursio-v0.1.0-myaccount-20251112.tar.gz.

The link is valid for 12 hours. Once the image tarball is downloaded, follow these steps to load and run the new portal image:

docker load -i tursio-v0.1.0-myaccount-20251112.tar.gz

Verify the image is loaded:

docker image ls

Confirm the image appears:

NAME                                TAG
tursio.azurecr.io/tursio            v0.1.0-myaccount-20251112

Open the compose.yaml for the portal and update the image: field for both the init and portal services to: tursio.azurecr.io/tursio:v0.1.0-myaccount-20251112

From the same directory where the compose file is located, run:

docker compose -p $project up -d --no-deps --force-recreate tursio-singleportal-portal-portal

Verify that the image is running:

docker ps

Enable HTTPS

This section is optional and only applies if you have not configured HTTPS previously.

The NGINX service is configured to automatically enable HTTPS when it finds certificate and key files.

First, obtain the certificate and key files (cert.pem and key.pem) for your organization.

Then, set the environment variables to point to these files:

export UI_CERT_FILE=$(test -f <path to cert.pem> && echo "$(pwd)/cert.pem" || echo /dev/null)
export UI_KEY_FILE=$(test -f <path to key.pem> && echo "$(pwd)/key.pem" || echo /dev/null)

Finally, apply the new configuration:

docker compose -p $project up -d

Increase Timeout

The NGINX configuration is generated from a template file at startup. For advanced changes like increasing timeouts, you may need to modify this template.

In the NGINX configuration template, ensure the following timeout values are present inside the location / block:

location / {
    proxy_pass http://tursio-singleportal-portal:8080;
    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 https;

    proxy_connect_timeout 600s;
    proxy_send_timeout 600s;
    proxy_read_timeout 600s;
    send_timeout 600s;
}

Recreate only the NGINX container to apply the changes:

docker compose -p $project up -d --force-recreate tursio-singleportal-nginx

Verify the timeouts are applied:

docker exec -it ${project}-tursio-singleportal-nginx-1 nginx -T | grep timeout