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.
Warning
The deployment template now uses RustFS instead of MinIO. Updating a MinIO-based deployment with this template does not migrate its stored artifacts or storage credentials. The RustFS initialization and rerun instructions below apply to fresh RustFS deployments and subsequent updates to those deployments.
Prerequisites#
Prepare Your Deployment - An initialized Dioptra deployment
Python 3.11+ virtual environment with the
cruftpackage 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.ymlNo 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).
Run initialization as the user who owns the deployment files.
The script preserves existing credentials and automatically repairs their permissions to owner-only access (0600).
If it reports an incomplete or empty credential set, follow Recover Deployment Credentials before restarting services.
RustFS initialization can be rerun: it preserves the existing bucket and skips policy attachments that are already present.
Use the --skip-rustfs-setup option when you do not need to reconcile storage accounts and policies:
./init-deployment.sh --branch <branch-name> --skip-rustfs-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-rustfs-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#
Deployment Commands Reference - Quick reference for start, stop, logs, and restart commands
init-deployment.sh Script Reference - Complete init-deployment.sh options
Use Docker Compose Override Files - Working with override files
Deployment Template Reference - Template variable descriptions