Updates & Upgrades
Since FediSuite is fully Docker-based, an update consists of exactly two steps: pull the new image, restart the containers. Database migrations run automatically. The exact process depends on whether you use the latest tag or a pinned version.
On this page
How Docker updates work
FediSuite is published as a ready-made Docker image on Docker Hub. You never have source code on your server that you'd need to touch — you simply swap the image.
docker compose pull downloads the latest version of the image. docker compose up -d then restarts the containers — Docker automatically detects that a new image is available and replaces the running containers.
Your data (database in ./postgres/, uploads in ./uploads/) are in bind mounts outside the containers — they are not affected by updates.
Before the update
1. Read the changelog
Before every update, check the changelog to know what's changing. Especially when jumping across multiple versions, there may be breaking changes.
View changelog on Codeberg ↗2. Create a backup
Before major updates, create a backup of the ./postgres/ directory. In case of a failed update, you can use it to restore the previous state. A detailed guide is available on the Backup & Restore page.
3. Plan for brief downtime
While docker compose up -d recreates the containers and runs database migrations, FediSuite will be unavailable for a few seconds to a few minutes. Plan the update accordingly.
Option A: latest tag (default)
If your .env has the default FEDISUITE_IMAGE=christinloehner/fedisuite:latest, two commands are all you need for a complete update:
# Pull the new image
docker compose pull
# Restart containers with the new image
docker compose up -d
docker compose pull downloads the current latest image from Docker Hub. If the latest version is already present locally, nothing happens. Then docker compose up -d recreates the changed containers.
docker compose pull outputs whether a new image was downloaded or whether everything is already up to date.
Option B: Pinned version tag
Those who want to deliberately control and test updates before they go live pin the image to a specific version — for example christinloehner/fedisuite:1.20.0. In this case, docker compose pull won't fetch newer versions because the tag immutably points to a concrete version. You must manually update the tag in the .env.
Find the target version in the changelog
Check the changelog ↗ to determine the desired target version. Version numbers follow the scheme MAJOR.FEATURE.PATCH, e.g. 1.20.0.
Update FEDISUITE_IMAGE in .env
Open the .env and change the tag to the new version:
Before
FEDISUITE_IMAGE=christinloehner/fedisuite:1.19.0After
FEDISUITE_IMAGE=christinloehner/fedisuite:1.20.0Pull the image and restart containers
# Pull the new tag (only the new image, not latest)
docker compose pull
# Restart containers with the new image
docker compose up -dlatest you're always automatically up to date — updates are applied as soon as you run docker compose pull. With a pinned tag you have full control over when and to which version you update. For production instances with many users, a pinned tag is often recommended so you can test before updating.
What happens during an update
docker compose up -d detects that one or more services have a new image and automatically performs the following steps:
Old container is stopped
Docker gracefully stops the running container. From this point, FediSuite is briefly unavailable.
New container is created
Docker creates a new container based on the new image, with the same volumes, networks, and environment variables.
Database migrations run automatically
The app container runs init-db.js on startup. This script is idempotent — it creates new tables and columns if needed, leaving existing data untouched. You don't need to run any migration commands manually.
App is available again
Once the db container's health check passes and init-db.js has completed, the server starts. FediSuite is available again.
docker compose up -d updates all services that have a new image — including worker1 and worker2. You don't need to do anything separately.
Verify the update
After the update, check that all containers started cleanly:
Check status of all containers
All containers should show status running and — if a health check is defined — healthy.
docker compose psCheck startup logs of the app container
Here you can see whether database migrations ran successfully and whether the server started cleanly.
docker compose logs app --tail=50Which image is currently running?
Shows the image ID and tag of the currently running container.
docker compose imagesRollback
If something isn't right after an update, you can switch back to the previous version. Since Docker caches old image layers locally, this is often possible without re-downloading.
With a pinned tag: revert the version in .env
# .env: set FEDISUITE_IMAGE back to the old version
# FEDISUITE_IMAGE=christinloehner/fedisuite:1.19.0
# Restart containers with the old image (no pull needed, image is still local)
docker compose up -dWith the latest tag: use a specific image ID
If you're using latest, the old version is no longer directly reachable via the tag — latest now points to the new image. However, you can use the concrete image ID of the previous container:
# List locally available images (look for the older version)
docker images christinloehner/fedisuite
# Set the found IMAGE ID or an available version tag in .env:
# FEDISUITE_IMAGE=christinloehner/fedisuite:1.19.0
docker compose up -d./postgres/ directory from before the update is necessary.