Updating DFIRe

Overview

DFIRe is distributed as Docker images on Docker Hub, with a :latest tag pointing at the current stable release. There are two supported update paths:

• Installation script (default, recommended). Re-run install.sh with the upgrade option. The script detects your existing installation, pulls new images, regenerates the Docker Compose files so new services and configuration changes land correctly, and restarts everything. This is the path most users should take — it protects you from drift between your on-disk compose files and the shape DFIRe expects.
• Manual path. docker compose pull plus docker compose up -d. Appropriate if you have intentionally customized docker-compose.prod.yml or docker-compose.external-db.yml and want to control exactly what changes. You are responsible for merging any upstream compose changes yourself.

Before You Update

1. Back Up Your Data

Before any update, ensure you have recent backups of:

• Your PostgreSQL database
• Your file storage (local volumes, S3, or SMB)
• Your .env configuration file

Use the backup methods best suited to your deployment model — VM snapshots of the host, your platform's managed PostgreSQL backups (RDS automated snapshots, DigitalOcean / Supabase managed backups, etc.), scheduled pg_dump against a direct database connection, container volume snapshots, and object-storage versioning/replication for attachments. Rely on the infrastructure-level backups your platform already provides; do not treat DFIRe's integrated backup as a replacement for them. Treat this pre-update backup as your rollback path if the update goes badly — it should be one you know how to restore from.

See Backup & Recovery for DFIRe's integrated backup feature (a second-tier convenience tool) and the broader discussion of platform-level backups.

2. Check for Breaking Changes

Review the release notes for any breaking changes or migration steps that may be required. Release notes are published on the DFIRe website and in the application's changelog.

3. Plan for Downtime

The update process requires stopping DFIRe briefly. Plan updates during maintenance windows when users are not actively working on cases.

Recommended: Update Using the Installation Script

The recommended way to update DFIRe is to download the latest installation script and run the upgrade option. This ensures your Docker Compose configuration is regenerated to include any new services or configuration changes introduced in the update.

1. Download the latest installation script

   cd /opt/dfire
   curl -fsSL https://dfire.fi/install.sh -o install.sh
   chmod +x install.sh

2. Run the script

   sudo ./install.sh

   The script will detect your existing installation and present upgrade options.

3. Select option 1: Upgrade in place

   This option:

   • Reads your existing .env configuration
   • Stops and removes existing containers (volumes are preserved)
   • Regenerates the Docker Compose files to pick up any new services or changes
   • Pulls the latest Docker images
   • Starts all services and waits for the health check to pass
4. Verify the update

   The script will show the container status after startup. You can also check manually:

   docker compose -f docker-compose.prod.yml ps

Manual Update (Customized Compose Files)

If you have customized docker-compose.prod.yml or use the docker-compose.external-db.yml overlay and do not want the installer to regenerate them, you can update manually:

1. Pull the latest images

   For a standard setup:

   cd /opt/dfire
   docker compose -f docker-compose.prod.yml pull

   Or, if you run with the external-DB overlay:

   docker compose -f docker-compose.prod.yml -f docker-compose.external-db.yml pull

2. Restart services

   docker compose -f docker-compose.prod.yml up -d

   (Add -f docker-compose.external-db.yml on both sides if you use the overlay.)

3. Watch the backend come up

   Migrations run on first backend start. The first run after an update may take a minute or two:

   docker compose -f docker-compose.prod.yml logs -f backend

   Look for the migrations-complete message and a healthy status before directing users back to the application.

Air-Gapped / Offline Updates

For environments without internet access, updates must be applied manually by transferring new Docker images.

1. On a connected system, pull and save the latest images

   docker pull dfireadmin/dfire-backend:latest
   docker pull dfireadmin/dfire-frontend:latest
   
   docker save dfireadmin/dfire-backend:latest -o dfire-backend.tar
   docker save dfireadmin/dfire-frontend:latest -o dfire-frontend.tar

2. Transfer the tar files to the air-gapped system

   Use approved media to transfer the image files to the isolated environment.

3. Load the new images

   docker load -i dfire-backend.tar
   docker load -i dfire-frontend.tar

4. Restart services

   cd /opt/dfire
   docker compose -f docker-compose.prod.yml down
   docker compose -f docker-compose.prod.yml up -d

5. Verify the update

   docker compose -f docker-compose.prod.yml ps
   docker compose -f docker-compose.prod.yml logs -f backend

Database Migrations

DFIRe automatically runs database migrations when the application starts. After updating, the first startup may take slightly longer as migrations are applied.

You can monitor the migration progress in the logs:

docker compose -f docker-compose.prod.yml logs -f backend

Look for messages indicating migrations have completed successfully before accessing the application.

Checking Your Version

After updating, you can verify which version is running:

• The version number is displayed in the application footer
• Administrators can see version details in Settings > Tenant > Identity

Rolling Back

If you encounter issues after updating, you can roll back to a previous version:

1. Stop the Current Containers

docker compose -f docker-compose.prod.yml down

2. Restore Your Database Backup

Restore your database from the backup you made before updating. Follow your database provider's restore procedure.

3. Pull a Specific Version

If you need a specific version, you can modify your .env to use a tagged version instead of :latest:

DFIRE_BACKEND_IMAGE=dfireadmin/dfire-backend:1.2.0
DFIRE_FRONTEND_IMAGE=dfireadmin/dfire-frontend:1.2.0

Contact support for available version tags.

4. Start the Previous Version

docker compose -f docker-compose.prod.yml up -d

Troubleshooting

Containers Won't Start

Check the logs for error messages:

docker compose -f docker-compose.prod.yml logs

Common issues include:

• Database connection errors — Ensure your PostgreSQL server is running and accessible
• Port conflicts — Check if another service is using the same ports
• Missing environment variables — Verify your .env file is complete

Application Errors After Update

If the application starts but shows errors:

1. Clear your browser cache and cookies for the DFIRe domain
2. Check that migrations completed successfully in the logs
3. Verify your license is still valid

Getting Help

If you encounter issues during updates, contact contact@dfire.fi with:

• The version you were updating from
• Any error messages from the logs
• Your deployment environment details