Updating Tracecat
Learn how to safely update versions and run data migrations.
Updates and data migrations can be tricky business. We’d love to help on Discord.
If you want to migrate secrets, please make sure to save your database
encryption / decryption Fernet key. You can find this key in your .env
file
assigned to the environment variable: TRACECAT__DB_ENCRYPTION_KEY
.
Docker Compose
Download latest environment variables migration script and template
Fetch the latest environment variables migration script env-migration.sh
and template .env.example
to ensure compatibility with the new Tracecat
version.
curl -o env-migration.sh https://raw.githubusercontent.com/TracecatHQ/tracecat/0.11.2/env-migration.sh
curl -o .env.example https://raw.githubusercontent.com/TracecatHQ/tracecat/0.11.2/.env.example
Execute environment variables migration
Run the environment variables migration script to update your existing
.env
file with any new or changed variables.
chmod +x env-migration.sh && ./env-migration.sh
Update Docker Compose Configuration
Download the latest Docker Compose file.
curl -o docker-compose.yml https://raw.githubusercontent.com/TracecatHQ/tracecat/0.11.2/docker-compose.yml
Restart Tracecat
Run docker compose up
using the new Docker Compose and .env
files.
Terraform Deployments
All of Tracecat’s Cloud deployments (e.g. AWS EC2, AWS ECS) are configured using Terraform.
To update Tracecat, you can download the latest Terraform stack from Tracecat’s GitHub repo and run terraform apply
.
Data Migration
As of version 0.8.x, data migrations are automatically applied when the API service is spun up. Data migrations are, however, non-trivial operations. We recommend backing up your database before running migrations, especially in a production environment.
If the API service fails to spin up due to a data migration error, do not worry! Your data is still intact. Make sure you first backup the core Tracecat database:
- For Docker Compose and AWS EC2 deployments, this would be the
core-db
volume in Tracecat’s Docker stack. - For AWS ECS Fargate deployments, backups are created automatically as part of the RDS postgres service.
Then contact us on Discord or email founders@tracecat.com for live migration support.
We’re releasing a self-serve guide for manual migration in the coming months. For the time being, however, we recommend contacting us for one-on-one help!