Configuration

The database. Permanently stores all users, posts, account links, settings, and history data.

The core. Provides the web interface and API through which users operate FediSuite. Automatically initializes the database on first start.

Background jobs: executes scheduled posts, updates analytics data, sends reminders, and generates tips.

Additional worker for post refresh and the tips engine. Offloads worker1 when many users are active simultaneously.

image: postgres:15-alpine

The official PostgreSQL image in version 15, based on Alpine Linux — a particularly lightweight Linux variant. FediSuite uses PostgreSQL as its database; MySQL or other systems are not supported.

env_file: .env

The database container reads POSTGRES_DB, POSTGRES_USER, and POSTGRES_PASSWORD directly from your .env file. You don't need to enter these values twice.

restart: unless-stopped

If the container crashes or the server restarts, Docker automatically brings it back up — unless you deliberately stopped it with docker compose stop. This ensures FediSuite keeps running reliably after a reboot without any manual intervention.

volumes: ./postgres:/var/lib/postgresql/data

Something important happens here: the ./postgres folder on your server is linked to the /var/lib/postgresql/data folder inside the container. This is called a Bind Mount.

Without this volume, all database data would be lost as soon as the container is deleted or recreated — for example, during an update. With the bind mount, the data remains on your server regardless of what happens to the container.

healthcheck

Docker checks every 5 seconds whether PostgreSQL is actually ready to accept connections — not just whether the container is running. Only once this check passes (after at most 5 attempts) does the app container start. This prevents the app from trying to access a database that hasn't finished starting up yet.

image: ${FEDISUITE_IMAGE:-christinloehner/fedisuite:latest}

Uses the image you set in FEDISUITE_IMAGE in your .env. The part after :- is the default value if the variable is empty — in this case christinloehner/fedisuite:latest.

pull_policy: always

Docker checks on every start whether a newer version of the image is available on Docker Hub and downloads it if needed. This ensures that after a docker compose up -d you're always running the latest version — as long as you use the latest tag.

environment: ENABLE_*=false

In full operation, the app container has all background jobs disabled — the workers handle those tasks. The difference between env_file and environment:

• •env_file loads all variables from the .env file into the container.
• •environment sets individual variables directly in docker-compose.yml — and overrides values from the .env. This is intentional: the workers should handle the jobs, not the app.

depends_on: db: condition: service_healthy

The app waits to start until the db container passes its health check — meaning PostgreSQL is actually accepting connections. Without this dependency, the app could try to initialize the database before it's ready, causing startup errors.

ports: "3000:3000"

The FediSuite app runs internally on port 3000. The mapping 3000:3000 makes this port accessible on the host system — the server itself. If you use Traefik as a reverse proxy, Traefik can reach the app through this port, and you access FediSuite at your domain via HTTPS.

volumes: ./uploads & ./plugins

Two bind mounts:

• •./uploads:/app/uploads — FediSuite stores files uploaded by users here (e.g. media for posts). These are preserved across updates.
• •./plugins:/app/plugins — The plugins folder, mounted as read-only (:ro). The app can read plugins but not write to them. Plugins are managed on the host.

command: node server/init-db.js && node server/index.js

When the container starts, two steps run in sequence: first, init-db.js initializes the database structure — creates tables, sets up the first admin account from ADMIN_EMAIL/ADMIN_PASSWORD. Then index.js starts the actual app. You don't need to trigger this initialization manually.

Ensures that scheduled posts are published at the right time. Should only run in one worker, as running it in multiple workers could cause posts to be sent twice.

Regularly fetches updated data from Fediverse platforms — e.g. new reactions on already published posts. Can run in multiple workers; REFRESH_BATCH_SIZE controls how many posts are processed per cycle.

Sends reminders to users who haven't posted for a while. Running in one worker is sufficient.

Generates tips and suggestions for users. Can be distributed across multiple workers.

A unique ID for the worker — helps with log tracing when multiple workers are running.

How many posts the worker processes per refresh cycle. Lower values are gentler on Fediverse APIs; higher values speed up updates when many users are active.

Used by: db

All database data: user accounts, posts, settings, Fediverse account links. The most important part of the entire setup.

Used by: app, worker1, worker2

Files uploaded by users, e.g. images for posts. Must be shared between the app and workers.

Used by: app, worker1, worker2

Installed plugins. Mounted as read-only — the app can read plugins but not modify them.

Why do worker1 and worker2 use the same image as app?

FediSuite is a single Node.js application that takes on different roles depending on environment variables. The app image can start as both a web server and a background processor. The role a container takes on is determined by the combination of ENABLE_* variables and the command entry.

What does depends_on with service_healthy mean?

Without this condition, Docker would start all containers simultaneously. The app could then try to access the database before PostgreSQL is even ready — leading to startup errors. With condition: service_healthy, each dependent container waits until the db health check has passed successfully.

Networking: how do containers communicate?

Docker Compose automatically creates an internal network in which all containers in the stack can reach each other by their service name. The app talks to the database simply using the hostname db — that's why the DATABASE_URL reads postgresql://...@db:5432/.... The database is not accessible from the outside.

Traefik labels in the docker-compose.yml

In the app service you'll find commented-out Traefik labels. These tell Traefik which domain the app should be accessible at and which cert resolver to use for TLS. How to set up Traefik and customize these labels is covered on the next pages.