# Backup and Restore

A Psono backup consists of the server configuration and a dump of the PostgreSQL database. If you use the Psono Fileserver, also back up its configuration and all files stored in its shards. This applies to both the Community Edition and the Enterprise Edition.

# What To Back Up

Component	Required backup
Psono server	The server's `settings.yaml` and any configuration values supplied separately, for example through environment variables or Docker secrets.
PostgreSQL	A dump of the Psono database.
Psono Fileserver, if used	Each Fileserver's `settings.yaml` and the complete contents of every shard's storage location.

# Server Configuration And Keys

The simplest approach is to back up the complete server settings.yaml. In the installation guides, this file is located at /opt/docker/psono/settings.yaml on the host.

At a minimum, preserve the original values generated during installation and placed at the top of that file:

SECRET_KEY
ACTIVATION_LINK_SECRET
DB_SECRET
EMAIL_SECRET_SALT
PRIVATE_KEY
PUBLIC_KEY
ADMIN_RECOVERY_PUBLIC_KEY, if configured

The remaining configuration can be recreated, but keeping the whole file makes restoration easier. A database dump alone is not sufficient: the original keys and secrets are needed to use the restored data. Restore these values rather than generating replacement keys.

If you supplied values through environment variables, Docker secrets, or an external secret store, preserve those values as well; copying settings.yaml does not include them. Continue to keep the ADMIN_RECOVERY_PRIVATE_KEY separately offline as described in the installation guide. It does not belong in settings.yaml.

# Fileserver Configuration And Shards

The Fileserver installation guide uses these host paths:

/opt/docker/psonofileserver/settings.yaml for the Fileserver configuration.
/opt/psono-shard/ for local shard storage, with a subdirectory for each shard.

Back up the actual storage locations configured under SHARDS, including all files and subdirectories. For Docker, copy the persistent storage on the host or in the mounted volume. If you use an object-storage backend instead of local folders, back up the corresponding bucket or storage location and preserve the credentials or identity configuration needed to access it.

The database contains the metadata linking uploaded file chunks to shards; the chunks themselves are stored in the shard storage. You need both to restore uploaded files. With multiple Fileservers or shards, include every configuration and every shard's complete data.

# Create A Backup

The examples below use the paths and the psono-database container from the installation guides. Adjust them to match your deployment and run the commands with an account that can read the configuration and shard files.

# 1. Prepare A Consistent Backup

pg_dump produces a consistent database dump while PostgreSQL is running. When also backing up Fileserver data, keep the database and shard storage consistent with each other: the simplest approach is to stop all Psono server and Fileserver instances and pause any scheduled jobs that modify the database or shard storage for the duration of the backup. Leave PostgreSQL running.

Create a new backup directory:

umask 077
BACKUP_DIR="$HOME/psono-backups/$(date +%Y-%m-%d-%H%M%S)"
mkdir -p "$BACKUP_DIR"

# 2. Copy The Server Configuration And Dump The Database

cp /opt/docker/psono/settings.yaml "$BACKUP_DIR/server-settings.yaml"
docker exec psono-database pg_dump \
    --username=psono --dbname=psono --format=custom \
    > "$BACKUP_DIR/psono.dump"

Check that the commands complete successfully. The dump is written to the host's backup directory, not inside the database container. Do not add -t to docker exec when writing a database dump.

For a database installed directly on a host or provided as a managed service, use pg_dump with that database's connection details and authentication instead. Use a PostgreSQL client version compatible with your database server.

# 3. Include Fileserver Data, If Used

On the Fileserver host, copy its configuration and archive the local shard folder into the same backup set:

cp /opt/docker/psonofileserver/settings.yaml "$BACKUP_DIR/fileserver-settings.yaml"
tar -czf "$BACKUP_DIR/fileserver-shards.tar.gz" -C /opt psono-shard

If the Fileserver runs on another host, create a backup directory there and collect its backup alongside the matching database dump. Repeat for additional Fileservers and storage locations, using distinct filenames. For non-local storage, use the storage backend's backup mechanism instead of the tar command.

Once the backup has completed successfully, resume the services and scheduled jobs you stopped. Keep the configuration, database dump, and shard data together as one backup set, and record the Psono and PostgreSQL versions used.

Store backup copies separately from the running installation and protect access to them, since the configuration contains secrets. Also retaining your deployment configuration, client config.json, and reverse-proxy configuration makes it easier to recreate the installation.

# Restore A Backup

Prepare PostgreSQL and the Psono services, keeping the Psono server, Fileservers, and scheduled jobs stopped during the restore. Start with the Psono version used for the backup and a compatible PostgreSQL version.
Restore server-settings.yaml to the server's settings.yaml location and restore any separately supplied secrets. Keep the original cryptographic values. Adjust connection details and paths if the replacement infrastructure differs.
Create an empty Psono database and its database user, following the PostgreSQL installation guide, then restore the dump. For the Docker setup, with BACKUP_DIR pointing to the chosen backup directory:
```
docker exec -i psono-database pg_restore \
    --username=psono --dbname=psono --no-owner --no-acl --exit-on-error \
    < "$BACKUP_DIR/psono.dump"
```
Use an empty database, not one already initialized with Psono tables. A database dump does not create PostgreSQL roles; the database user must already exist and have the required permissions.
If you use the Fileserver, restore its settings.yaml and all shard files from the same backup set to their configured storage locations. For the local-storage example, extracting the archive with tar -xzf fileserver-shards.tar.gz -C /opt recreates /opt/psono-shard/. Restore the directory permissions needed by the Fileserver and retain the original shard IDs in its configuration.
Start the Psono services and resume scheduled jobs. If you subsequently upgrade Psono, follow the normal update guide, including its database migration step.
Verify that users can log in and read existing entries. If you use the Fileserver, also download an existing file to verify that the database, configuration, and shard data work together.

Periodically test the restore procedure in a separate environment so that you know your backup set is complete.

← Group Management Tenants and Delegated Administration →