Upgrade to FediSuite 2.0.0 safely

1. Prepare and choose a maintenance window

Run the commands below in your existing self-hosting directory, where your docker-compose.yml and .env live. Connect to the server using SSH, change into that directory, and use pwd and ls -la to confirm your location. Do not work in a fresh clone: it will not contain your data and settings.

pwd
ls -la .env docker-compose.yml
docker compose ps
uname -m

Record your current image tag and any Compose customizations. x86_64 generally means AMD64; aarch64 means ARM64. Allow for downtime: the app and workers will be recreated, and migration can take a while if you have many connected accounts.

Be careful with latest: The current self-hosting Compose file uses pull_policy: always. Even a later docker compose up -d may fetch a new image. Do not run Compose start commands before the backup. We recommend pinning a version for a controlled upgrade.

If your setup is heavily customized, compare its services, volumes, networks, and reverse-proxy labels with the current Compose template. Do not blindly overwrite your file. If you are skipping versions, read the changelog too.

2. Back up before the first 2.0 start

Copying a live PostgreSQL data directory with cp or tar is not a reliable database backup. Use pg_dump. First stop the app and workers so posts and uploads cannot change during the backup; the database remains available for the dump. The example below stores the backup outside the Git repository in your home directory. set -e stops the sequence if a command fails.

set -e
umask 077
mkdir -p "$HOME/fedisuite-backups"
docker compose stop worker1 worker2 app
docker compose exec -T db sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' \
  > "$HOME/fedisuite-backups/before-2.0.0.dump"
test -s "$HOME/fedisuite-backups/before-2.0.0.dump"
tar -czf "$HOME/fedisuite-backups/before-2.0.0-files.tar.gz" \
  .env docker-compose.yml uploads plugins logs

If any of those directories do not exist in your setup, adjust the tar line. If you use named Docker volumes or external storage instead, back up the actual storage locations as well. Keep another protected copy off the server and ideally test a restore. The dump may still contain plaintext account tokens, and .env contains passwords. Treat both as secrets.

If you abort before the first 2.0 start, you can restart the old containers with docker compose start app worker1 worker2. For more detail, including restore instructions and automation, see Backup & Restore. A database dump is still important if you also take a whole-server snapshot.

3. Create and safeguard a separate key

Generate a random 32-byte key once. OpenSSL prints exactly 64 hexadecimal characters:

openssl rand -hex 32

Open your existing .env in an editor and add one line. Replace the placeholder with the output you just generated. Do not use the example text or reuse your JWT_SECRET:

ACCOUNT_ENCRYPTION_KEY=YOUR_64_HEX_CHARACTERS_HERE

Restrict access with chmod 600 .env. Save another encrypted copy of the key away from the server, for example in your password manager. Never paste it into a ticket, chat, log, or Git. Do not change or regenerate it after migration. Later backups also require the exact key matching that database.

The app and all workers must receive the same value. The current Compose template loads .env for app, worker1, and worker2 using env_file. If you have a custom Compose file, check all three services and any environment overrides. Avoid printing docker compose config without --quiet: its output may expose secrets.

4. Check Compose and file permissions

Update your Compose configuration using the self-hosting repository as a reference. git pull is straightforward only if your tracked files have not been customized. Otherwise, inspect the differences and merge the relevant changes. Keep your existing .env; do not replace it with .env.example.

git status --short
# Only if tracked files have no local changes:
git pull --ff-only

If git status shows changes to docker-compose.yml or git pull --ff-only fails, do not force it. Compare your file to the current template and merge the necessary changes manually. If your installation is not a Git checkout, do not simply overwrite your customized Compose file with the template.

In particular, check env_file: .env on the app and every worker, bind mounts for uploads, plugins, and logs, and the same image variable for app and workers. For AMD64, put FEDISUITE_IMAGE=christinloehner/fedisuite:2.0.0 in .env; for ARM64, use FEDISUITE_IMAGE=christinloehner/fedisuite:arm64-2.0.0.

From 2.0 onward, the image runs without root privileges as UID/GID 1000:1000. The container needs write access to the mounted upload, plugin, and log directories. Check ownership and permissions:

stat -c '%u:%g %a %n' uploads plugins logs
docker compose config --quiet

After the backup, adjust those three directories and their contents to UID 1000 if needed, for example with sudo chown -R 1000:1000 uploads plugins logs. First check whether other services or ACLs share that storage. Do not broadly change ownership of the PostgreSQL data directory or run the FediSuite container as root.

5. Pull, start, and verify version 2.0.0

Only after checking the database dump, files, key, and Compose configuration should you pull the new image and recreate the containers:

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 app

The app runs the database migration on startup and encrypts existing credentials. Wait until app is healthy; its dependent workers start afterward. This can take longer with many accounts. docker compose restart is not enough after changing .env, because it does not reload the container environment.

• Open your instance in a browser and sign in with an existing account.
• Check that previously connected Fediverse accounts appear and still work. If possible, test an action using an existing connection.
• Check uploads and any installed plugins.
• Check docker compose logs --tail=100 worker1 worker2 for startup errors; both workers should be running.
• Watch the instance for errors afterward. Back up the updated .env containing the key again.

A successful login alone does not prove that account encryption works. You need both a successful app start and working previously connected accounts.

If something goes wrong

Older database backups and PostgreSQL WAL files may still contain plaintext tokens. Protect them accordingly: upgrading does not retroactively encrypt existing backups.