Backups and export

Back up your agent's PostgreSQL database and the configuration and data folders on your agent's machine. If you configured a separate database server, take the database backup there.

What to back up

The configuration folder holds one.env and three keys created on the first start: core.id (the deployment's id), session.key (signs admin app logins) and vault.key (encrypts the keys of unlocked credentials). The data folder holds the keyring and every space's files.

Losing vault.key locks every credential until an admin of each scope logs in and unlocks them again. Losing session.key logs everyone out. Losing core.id changes the deployment's identity.

Make a consistent backup

Let active work finish, then stop Optakt One before taking the database dump and copying its folders. Stopping it keeps the database and files at the same point in time. Keep PostgreSQL running while you dump it.

On Linux, with the default database Optakt installed:

backup="optakt-backup-$(date +%Y%m%d-%H%M%S)"
mkdir "$backup" &&
sudo systemctl stop optakt-one &&
sudo -u postgres pg_dump -Fc optakt > "$backup/database.dump" &&
sudo tar -czf "$backup/files.tar.gz" /etc/optakt /var/lib/optakt &&
sudo systemctl start optakt-one

If a step fails, the chain stops and the service stays stopped. Resolve the error and finish the backup before starting it again.

On a Mac, stop the LaunchAgent from the installing user's session:

launchctl bootout "gui/$(id -u)" "$HOME/Library/LaunchAgents/io.optakt.one.plist"

Use PostgreSQL 18's pg_dump -Fc against the database named by DATABASE_DSN in your configuration, and copy both folders in the table above. That applies to a custom or remote database too: the default Linux command is not its connection string. Keep passwords out of shell history and chat.

After the dump and copies finish, start the Mac service again:

launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/io.optakt.one.plist"

Keep the dump and folder copies together, encrypted and off the machine. Check that pg_restore --list can read the dump and that the saved configuration includes all three keys. A readable dump is not proof of recovery: test a restore on a separate machine before relying on the backup.

Recovery

Recover into an empty PostgreSQL database with the required extensions installed, using the same Optakt One version as the backup. Keep the service stopped throughout:

1. Restore the database with PostgreSQL's pg_restore, using the database owner and connection for the recovering installation.
2. Restore the configuration and data folders, preserving their permissions and ownership. On Linux the service runs as optakt; on a Mac it runs as the installing user.
3. Keep the saved core.id, session.key and vault.key. Do not substitute keys from a fresh installation. Set DATABASE_DSN to the restored database if its address changed.
4. Start the service and check its logs, then open the admin app and check the scopes, spaces and credentials. Only upgrade after this recovery works.

A licence is tied to a machine. If recovering onto a different machine, write to max@optakt.io to release or replace the old activation.

Do not overwrite a working database to test a backup. For a custom database or a changed operating system, confirm the restore procedure with the person managing that server first.

Taking everything with you

Your data is a standard PostgreSQL database and ordinary files. A coordinated dump and the folders above contain the stored records and files, readable by a system that can take them in. The credentials remain encrypted; exporting them does not make their values readable without the matching keys and passwords.