Disaster Recovery Guide

How to recover your ACT installation after a server failure

Updated Jan 21, 2026 Edit this page

Disaster Recovery Guide

This guide explains how to restore your ACT installation from a backup after a server failure or when migrating to a new server.

Prerequisites

Before you begin, ensure you have:

  1. A backup of your ACT database (act_db_backup.sql for PostgreSQL or act.db.bak for SQLite)
  2. Your original ACT_MASTER_KEY - This is critical. All SSH keys and secrets are encrypted with this key.
  3. A fresh server with ACT installed

⚠️ CRITICAL: If you lose your ACT_MASTER_KEY, you will not be able to decrypt your SSH keys or service secrets. Store this key securely (password manager, secure vault, etc.) as part of your disaster recovery plan.

Understanding What’s Backed Up

The ACT database backup includes:

  • Organizations, Projects, and Environments
  • Server configurations and encrypted SSH keys
  • Service configurations and encrypted environment variables
  • Deployment history and logs
  • Storage provider and registry credentials
  • Backup configurations and history

The backup does not include:

  • Running container state (containers must be redeployed)
  • Container images (stored in registries)
  • Actual backup files (stored in S3/storage providers)

37: ## Restoration Steps 38: 39: 40: [New Server] ──► [Install ACT] 41: │ 42: ▼ 43: [Stop Service] ──► [Set MASTER_KEY] 44: │ 45: ▼ 46: [Restore Backup DB] ───────► [Start Service] 47: │ 48: ▼ 49: [Verifiy Decryption] 50: │ 51: ▼ 52: [Redeploy Services] 53: 54: 55: ### Step 1: Install ACT on the New Server

curl -fsSL https://raw.githubusercontent.com/drmhse/act2/main/install.sh | bash

Step 2: Stop the ACT Service

sudo systemctl stop act

Step 3: Set the Master Key

The master key must match your original installation:

# Edit the ACT environment file
sudo nano /etc/act/act.env

# Ensure ACT_MASTER_KEY matches your original key
ACT_MASTER_KEY=your-original-master-key-here

Step 4: Restore the Database

For SQLite (Default)

# Replace the database file
sudo cp /path/to/your/act.db.bak /var/lib/act/act.db

For PostgreSQL

# Connect to PostgreSQL and restore
sudo -u postgres psql -c "DROP DATABASE IF EXISTS act;"
sudo -u postgres psql -c "CREATE DATABASE act;"
sudo -u postgres psql act < /path/to/act_db_backup.sql

Step 5: Start ACT

sudo systemctl start act

Step 6: Verify the Restoration

  1. Access the ACT web interface
  2. Check that your organizations, projects, and services appear
  3. Verify server connections are working (the SSH keys should decrypt correctly if the master key is correct)

Step 7: Redeploy Services

After restoration, your services exist in the database but containers may not be running. For each service:

  1. Navigate to the service in the ACT dashboard
  2. Click “Deploy” to redeploy the service

Alternatively, use the API to trigger deployments programmatically.

Automated Off-Site Backups

ACT can automatically upload database backups to your configured S3 storage provider. To enable this:

  1. Configure a Storage Provider in Settings → Storage
  2. Set it as the default storage provider for backups
  3. The daily backup job will automatically upload to S3

Backup Best Practices

  1. Store ACT_MASTER_KEY securely - Use a password manager or secret vault
  2. Enable off-site backups - Configure S3 storage for automatic backup uploads
  3. Test your backups - Periodically restore to a test environment
  4. Document your setup - Keep notes on any custom configurations
  5. Monitor backup jobs - Check that backups are completing successfully

Troubleshooting

“Failed to decrypt SSH key”

This error means the ACT_MASTER_KEY doesn’t match. Ensure you’re using the exact same key from your original installation.

“Server connection failed”

After restoration, SSH connections may fail if:

  • The new ACT server has a different IP address
  • The target server’s firewall doesn’t allow the new IP
  • The SSH key was rotated but backup is old

“Service not found”

If services are missing, the backup may be incomplete or corrupted. Check the backup file integrity.

Emergency Contacts

If you need assistance with disaster recovery: