Updates & Upgrades
Since FediSuite is fully Docker-based, an update consists of the updated Compose file, a new image and recreated containers. Database migrations run automatically when the app starts. You enter the images with a fixed version tag and download them deliberately.
This is not a routine update: you need a database backup and a permanent ACCOUNT_ENCRYPTION_KEY before the first start. Follow the step-by-step upgrade guide for 2.0.0, not just the general commands below.
New installations use PostgreSQL 18. You switch existing instances with a backup and a restore; simply changing the tag is not enough. Follow the step-by-step guide to switch from PostgreSQL 15 to 18.
On this page
How updates work with Docker
FediSuite is published as a ready-made Docker image on Docker Hub. There is no source code on your server that you would have to touch: you swap the image.
docker compose pull --policy always downloads the images listed in the Compose file. docker compose up -d then recreates the containers whose image has changed. The Compose file never downloads images on its own (pull_policy: never); an update therefore only happens when you trigger it. The Compose file itself comes from the FediSuite-Self-Hosting repository and is updated with git pull.
Your data (database in ./postgres/, uploads in ./uploads/, plugins in ./plugins/, logs in ./logs/) sits in bind mounts outside the containers and is kept during updates.
Before the update
1. Read the changelog
Have a look at the changelog before every update. When jumping over several versions or to a new major version (most recently 2.0.0 with a reworked navigation, drafts, content calendar, labels and campaigns) it is worth reading all entries in between. New features can be switched off with switches, see the Environment variables page.
View the changelog on Forgejo (opens in new tab)2. Create a backup
Before every update, back up the database, the uploads, the plugins and the .env. The bundled script scripts/backup.sh does that in one step, best with the app and the workers stopped. With a migration step that changes the database, going back is only possible through the backup. A detailed guide is on the Backup & restore page.
3. Update the Compose file
A new image does not change the docker-compose.yml. New versions can, for example, adjust health checks, environment variables, the PostgreSQL image or the start order of the workers. So also fetch the Compose file and the scripts from the repository and compare the .env.example with your .env to see whether new variables have been added:
cd fedisuite
git pull --ff-only
diff .env.example .env # shows new or removed variables
./scripts/check-config.sh # checks tags, PostgreSQL image and mount path
diff always shows differences in your own values as well; only look for variable names that are missing in your .env. If you edited the docker-compose.yml yourself (for example for Traefik), git pull reports a conflict. Put such customisations into a docker-compose.override.yml, which the repository ignores. Do not print docker compose config without adding --quiet and do not post its output anywhere: it contains the values from your .env.
4. Plan for a short downtime
While docker compose up -d recreates the containers and the app runs the database migrations, FediSuite is not reachable. That usually takes seconds to a few minutes. The health check of the app allows up to ten minutes of start time (start_period) for long migrations.
Perform the update (fixed version tag)
The current self-hosting template uses fixed version tags only and never downloads images on its own (pull_policy: never). An update is therefore always a deliberate sequence of four steps. The version numbers in the examples are placeholders.
Find the target version in the changelog
The changelog (opens in a new tab) lists which versions exist and what changes. Version numbers have the form MAJOR.MINOR.PATCH, for example 2.1.0.
Adjust FEDISUITE_IMAGE in the .env
Open the .env and change the tag to the new version. On ARM64 servers keep the arm64- prefix.
Before
FEDISUITE_IMAGE=christinloehner/fedisuite:2.0.3
After
FEDISUITE_IMAGE=christinloehner/fedisuite:2.1.0
Stop, back up and check
Stop the app and the workers, create a backup and check the configuration. The check script reports Configuration is valid. if tag, PostgreSQL image and mount path fit together. More on backups: Backup & restore.
# Stop the app and workers (the database keeps running)
docker compose stop app worker1 worker2
# Backup with database, .env, uploads and plugins
./scripts/backup.sh /path/to/backup-storage
# Check the configuration
./scripts/check-config.sh
Download the image and recreate the containers
docker compose pull --policy always downloads the images of all services again. That includes the PostgreSQL image: if there is a newer minor-version image within PostgreSQL 18, the db container is recreated as well. This is possible without a data migration, and your data is kept. If you only want to update FediSuite, use docker compose pull --policy always app: the workers use the same image.
# Download the new image
docker compose pull --policy always
# Recreate containers with the new image
docker compose up -d
latest. Find the version you are running with docker compose exec -T app printenv VITE_APP_VERSION and enter it as FEDISUITE_IMAGE=christinloehner/fedisuite:<version> before you update the Compose file. The new Compose file also needs the settings POSTGRES_IMAGE, POSTGRES_DATA_PATH and POSTGRES_DATA_TARGET in the .env. For an existing installation with PostgreSQL 15 follow the guide Upgrade PostgreSQL 15 to 18; it also describes how to switch the Compose file over safely first.
What happens during the update
docker compose up -d detects that one or more services have a new image and recreates those containers. The database stays unchanged as long as its image does not change. The sequence:
Old containers are stopped
Docker stops the running app and worker containers in an orderly way. From now on FediSuite is briefly unreachable.
A new app container is created
Docker creates the container from the new image, with the same volumes, networks and environment variables.
Database migrations run automatically
On start the app runs init-db.js. The script is idempotent: it creates missing tables and columns and brings the schema up to date, existing data is kept. If a step fails, the server does not start. You do not run any migration commands yourself.
The app becomes healthy, workers start
As soon as /api/health answers, the app counts as healthy. Only then do the workers start. FediSuite is reachable again.
docker compose up -d updates all services with a new image, including worker1 and worker2. You do not need to trigger anything separately.
Verify the update
After the update, check that all containers started cleanly:
Check the status of all containers
All containers should show running, db and app additionally healthy. The workers only start once the app is healthy.
docker compose ps
Check the startup logs of the app
Here you can see whether the database initialisation was successful (Database initialized successfully) and the server started (Server running on port 3000).
docker compose logs app --tail=50
Check the health endpoint
Returns JSON with status: ok and db: connected once the app and the database are ready.
curl -s http://127.0.0.1:3000/api/health
Check the worker logs
On start the workers log which jobs they take over (for example [PostsRefresh], [ReachRefresh] Enabled).
docker compose logs worker1 --tail=30
Which image is running right now?
Shows repository, tag and image ID of the containers.
docker compose images
Rollback
If something is wrong after an update, you can switch back to the previous version. That applies to the containers. Whether the database fits depends on whether the update changed the schema.
Reset the version in the .env
Enter the tag of the previous version in the .env. The Compose file downloads nothing on its own: if the old image is still available locally (check with docker images christinloehner/fedisuite), docker compose up -d is enough. If it is missing, fetch it first with docker compose pull --policy always app.
# List locally available images
docker images christinloehner/fedisuite
# .env: set FEDISUITE_IMAGE back to the old version (example)
# FEDISUITE_IMAGE=christinloehner/fedisuite:2.0.3
# Recreate containers with the old image
docker compose up -d