Update Your Deployment#

This guide shows you how to apply configuration changes to your Dioptra deployment, whether from upstream template updates or local override file modifications.

Prerequisites#

  • Prepare Your Deployment - An initialized Dioptra deployment

  • Python 3.11+ virtual environment with the cruft package installed (pip install cruft)

  • Terminal access to the deployment directory

See also

For basic commands (start, stop, logs, restart), see Deployment Commands Reference.

Overview#

Choose the appropriate option based on what you need to update:

Option A: Apply Template Updates - Use this when:

  • A new version of the Dioptra deployment template is available

  • You need to change template variables (e.g., number of workers, datasets directory)

  • You want to pull in upstream fixes or improvements

Option B: Apply Override File Changes - Use this when:

  • You only modified docker-compose.override.yml

  • No template updates are needed

  • You’re making local customizations (data mounts, GPU settings, custom containers)

Option A: Apply Template Updates#

Use this workflow when you need to fetch updates from the upstream Dioptra template or change template variables.

Step A1: Stop the Running Services#

Before updating, stop your running Dioptra services:

docker compose down

Step A2: Fetch Template Updates#

Use cruft update to fetch the latest changes from the Dioptra deployment template:

cruft update --checkout <branch-name>

This compares your local deployment against the upstream template and applies any updates.

To update specific template variables at the same time:

cruft update --checkout <branch-name> \
  --variables-to-update '{ "datasets_directory": "/path/to/dioptra/data" }'

Note

Replace <branch-name> with the Dioptra branch that matches your container images (e.g., main for releases, dev for development builds).

Note

If there are conflicts between your local changes and template updates, cruft will prompt you to resolve them.

Step A3: Rerun the Initialization Script#

After updating the template, rerun init-deployment.sh to apply the changes:

./init-deployment.sh --branch <branch-name>

Note

Replace <branch-name> with the Dioptra branch that matches your container images (e.g., main for releases, dev for development builds).

When rerunning the script on an already-initialized deployment, it will freeze during the Minio setup step because those configurations have already been applied. Use the --skip-minio-setup option to skip this step:

./init-deployment.sh --branch <branch-name> --skip-minio-setup

Important

If you previously enabled SSL/TLS, include those flags again:

./init-deployment.sh --branch <branch-name> --enable-nginx-ssl --enable-postgres-ssl --skip-minio-setup

Step A4: Restart the Services#

Start the services to apply the updates:

docker compose up -d

Verify all services are running:

docker compose ps

Option B: Apply Override File Changes#

Use this simpler workflow when you only modified the docker-compose.override.yml file and don’t need to run cruft update.

Step B1: Stop the Running Services#

Stop the current deployment:

docker compose down

Step B2: Restart the Services#

Start the services again to pick up the new configuration:

docker compose up -d

Docker Compose automatically merges your override file with the main docker-compose.yml on startup.

Note

Some changes (like adding new volumes or changing environment variables) require a full stop/start cycle. A simple docker compose restart may not pick up all changes.

See Also#