How do I back up CertMate, and what is the restore procedure on a fresh host?

[fabriziosalmi]

I want to make sure I can recover from a host failure: lost disk, accidental rm -rf data, ransomware, anything. What exactly do I need to back up, how does CertMate's own automatic backup work, and how do I restore everything on a new host with a clean image?

[fabriziosalmi]

Two backup paths exist: the automatic unified backup that CertMate writes itself, and the manual snapshot of the data directory that you should also take. They overlap; the manual one is your insurance against the automatic one being broken.

What CertMate stores (the entire surface).

data/
├── settings.json                       # The single source of configuration truth
├── settings.json.before-revert.bak     # Auto-saved before the last destructive write
├── certs/                              # All issued certificates (local filesystem backend only)
│   └── <domain>/
│       ├── cert.pem
│       ├── chain.pem
│       ├── fullchain.pem
│       └── privkey.pem
├── scheduler_jobs.sqlite               # APScheduler job state (renewal schedules)
├── scheduler_jobs.sqlite-wal
├── scheduler_jobs.sqlite-shm
└── backups/
    └── unified/
        └── backup_YYYY-MM-DD_HHMMSS.zip

Backing up the entire data/ directory captures all of it.

Automatic backups. CertMate writes a unified backup zip to data/backups/unified/ on every settings change. The zip contains settings.json and metadata that lets the restore-on-start path pull a valid config back if settings.json is missing or empty (modules/core/settings.py:272-291). The five most recent zips are kept and tried in order; older ones are pruned. Certificates are NOT in the unified backup — only configuration is. If you only have the unified zip and lose data/certs/, you have your settings back but the certs themselves are gone and need to be re-issued (the renewal job will pick them up on the next tick if they are still in settings.json).

Manual backup (recommended cadence: before any upgrade, and on a periodic schedule). A whole-directory snapshot:

docker exec <container-name> tar czf /tmp/certmate.tar.gz /app/data
docker cp <container-name>:/tmp/certmate.tar.gz ./certmate-$(date +%Y%m%d).tar.gz

Or, if you mounted ./data:/app/data on the host (Q2), just tar the host directory directly. Encrypt the resulting archive — it contains your private keys and your DNS provider credentials.

Restore on a fresh host.

1. Install Docker, write the same docker-compose.yml as the original host. Same image tag is ideal; a newer image is fine (forward-compatible migrations). A strictly older image will refuse to start due to the downgrade-detection guard (Authentication issues after upgrade. #158).

2. Restore the data directory before starting the container.

   mkdir -p ./data
   tar xzf certmate-YYYYMMDD.tar.gz -C ./data --strip-components=2
   # adjust --strip-components depending on how you tarred
   chown -R 1000:1000 ./data

3. Start the container.

   docker compose up -d
   docker compose logs -f --tail 50

   Look for Settings restored successfully (good) — not recreating settings with defaults (bad, means the restore did not land where CertMate expects).

4. Verify. Hit /health, open the dashboard, check Settings → DNS shows your providers, check the certificate list, check the audit log for the last renewal entry. If a renewal is overdue (because the host was down for a while) the scheduler tick within the next hour will catch it up. To not wait, click Renew on each cert manually.

Restore from the unified zip only (settings, no certs). If the certs directory is gone but you still have a backup zip, drop the zip into data/backups/unified/ on the new host and start the container. The settings restore-on-start path will pick it up automatically (modules/core/settings.py:285). Then re-issue each cert.

What you cannot recover from a backup.

• The cleartext bearer token. Stored as a hash. If you lost both the cleartext and the host, generate a new one (Settings → Authentication → Rotate; or use the scripts/reset_admin_password.py in-container reset, see help page).
• Cloud storage backend secrets that live in the backend (Azure KV / Vault / etc.). The backup contains the configuration (which Vault, which path) but the cert contents themselves are in the cloud store. Restore there is a separate cloud-vendor concern.

Tested? Test the restore once, on a throwaway host, before you need it. The most common reason a restore fails in anger is that the operator never ran one in calm — the volume mount was off by one path component, the file ownership was wrong, the compose file had drifted from the original. Twenty minutes once is much cheaper than two hours under pressure.