Installation

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. The exact process depends on whether you use the latest tag or a pinned version.

Upgrading an existing instance to 2.0.0?

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.

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 downloads the images named in the Compose file. docker compose up -d then recreates the containers whose image has changed. 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/) lives 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 bigger updates, back up the database (with pg_dump), the uploads and the .env. If a migration step 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. Newer versions can adjust health checks, environment variables or the start order of the workers, for example. So also fetch the Compose file from the repository and compare the .env.example with your .env to see whether new variables were added: 

cd fedisuite
git pull
diff .env.example .env   # shows new or removed variables
docker compose config    # validates the combined configuration

If you edited the docker-compose.yml yourself (for example for Traefik), git pull reports a conflict. In future put such changes into a docker-compose.override.yml, which the repository ignores.

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.

Option A: latest tag (default)

If your .env contains the default FEDISUITE_IMAGE=christinloehner/fedisuite:latest, two commands are enough after the git pull:

bash 
# Download the new image
docker compose pull

# Recreate the containers with the new image
docker compose up -d

docker compose pull downloads the current latest image from Docker Hub. If it is already present locally, nothing happens. Then docker compose up -d recreates the containers whose image changed. Because the Compose file sets pull_policy: always, even a plain docker compose up -d (for example after a configuration change) checks for a newer image and can thereby trigger an update. For ARM64 servers the same applies with the tag arm64-latest.

Note: Admins see a notice in the interface when Docker Hub has a newer version than the running one. The check is cached for up to 30 minutes.

Option B: pinned version tag

If you want to control updates deliberately and test them first, pin the image to one version, for example christinloehner/fedisuite:2.0.0. docker compose pull then fetches no newer versions because the tag points to one fixed version. You have to change the tag in the .env yourself. The version numbers in the examples below are placeholders.

1

Find the target version in the changelog

The changelog (opens in new tab) lists which versions exist and what changes. Version numbers have the form MAJOR.MINOR.PATCH, for example 2.0.0.

2

Adjust FEDISUITE_IMAGE in the .env

Open the .env and change the tag to the new version:

Before

FEDISUITE_IMAGE=christinloehner/fedisuite:1.7.3

After

FEDISUITE_IMAGE=christinloehner/fedisuite:2.0.0
3

Download the image and recreate the containers

bash 
# Download the new tag
docker compose pull

# Recreate the containers with the new image
docker compose up -d
latest vs. pinned tag: With latest you are up to date right after docker compose pull, and because pull_policy: always is set, even a plain docker compose up -d can update. With a pinned tag you decide when and to which version you switch. For instances with many users the pinned tag is a good fit because you can test and take a backup 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 (postgres:15-alpine) stays unchanged. The sequence:

1

Old containers are stopped

Docker stops the running app and worker containers in an orderly way. From now on FediSuite is briefly unreachable.

2

A new app container is created

Docker creates the container from the new image, with the same volumes, networks and environment variables.

3

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.

4

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.

Workers are updated too: 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.

With a pinned tag: reset the version in the .env

bash 
# .env: set FEDISUITE_IMAGE back to the old version (example)
# FEDISUITE_IMAGE=christinloehner/fedisuite:1.7.3

# Recreate the containers with the old image
docker compose up -d

With latest: enter an old version tag

With latest the tag points to the new image after the update. To go back you enter the tag of the previous version in the .env. The old tags are on Docker Hub, and docker images christinloehner/fedisuite lists images that exist locally.

bash 
# List the images that exist locally
docker images christinloehner/fedisuite

# Set the desired version tag in the .env and restart
docker compose up -d
Database rollback: If the update ran database migrations, a container rollback alone may not be enough. FediSuite only runs migrations forward, and the new structure is not necessarily compatible with the old app version. Then only a restore of the database from before the update helps, see Backup & restore.

Reverse Proxy

Backup & Restore