Upgrade and rollback

Back up, rehearse, upgrade and verify a Frontdoor installation, and roll back if something goes wrong.

On this page

Frontdoor applies database schema changes on its own at startup. A safe upgrade is still a five-step routine: back up, rehearse, upgrade, verify and, if needed, roll back.

1. Back up

In Customize → Maintenance, open the backup page and download a backup. It is a .tar.gz file with database rows and schema, app icons, logo, avatars and plugin files, plus the Frontdoor version and commit that produced it. See Backup and restore.

Tick Leave out access and audit logs for a smaller file.
Set a passphrase to encrypt it. Keep the passphrase safe: it cannot be recovered.

For an exact copy of the database file, also use Download database file (.db) under Advanced options, which works while Frontdoor is running. With the container stopped (docker compose stop), also copy the SQLite file from the volume, including frontdoor.db-wal if present:

docker compose stop
docker cp <container>:/data/frontdoor.db ./frontdoor.db.bak

To decrypt an encrypted backup (.enc) from the command line:

FRONTDOOR_BACKUP_PASSPHRASE=... npm run backup:decrypt -- <file.enc>

2. Rehearse (recommended)

From a checkout of the new version, run:

npm run backup:rehearse -- <backup or .db file>

Set FRONTDOOR_BACKUP_PASSPHRASE for .enc files. The command rebuilds the source database in a temporary folder, runs the new version's migrations and prints schema changes, row counts and integrity checks. It exits with a non-zero code if rows would be lost or the database is damaged.

Backups made before 1.3.1 carry no schema: for those, it rehearses a restore into the new schema instead.

You can also start the new image locally against a copy of the database and check the [startup] log lines.

3. Upgrade

Pull or build the new image and start it on the same /data volume:

docker compose up --build

Migrations run at startup. Table rebuilds run inside a transaction, so an interrupted upgrade never leaves a table missing or half-copied.

Newer versions of docker-compose.yml pass the whole .env file to the container (env_file, Docker Compose 2.24 or later). Variables such as CORS_ALLOWED_ORIGINS, TIMEZONE or BACKUP_MAX_UPLOAD_MB set in .env now take effect. The values listed under environment keep their precedence. Review .env for variables you did not mean to apply. With a customized compose file, add the same env_file block or keep listing the variables explicitly.

4. Verify

5. Roll back if needed

Start the previous image and restore the backup taken in step 1.

About the database

Frontdoor uses a SQLite database in WAL mode with foreign keys enforced. On the first startup with an empty database, example apps are seeded automatically.