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.

Handles all background tasks: publishes scheduled posts on time, fetches updated stats from platforms, sends reminders, and generates tips. You can run more than one worker.

Each additional worker shares the load so stats stay fresh as your instance grows. app.fedisuite.com, for example, runs 5 workers.

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 & ./logs

Three 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. Plugins are managed on the host and accessible to the app and workers.
• •./logs:/app/logs — Application audit logs. FediSuite writes security-relevant events (login, registration, 2FA, etc.) as JSON Lines to monthly-rotating files (audit-YYYY-MM.log). Logs do not appear in container stdout.

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.

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. Plugins are managed on the host and accessible to the app and workers.

Used by: app, worker1, worker2

Application audit logs. FediSuite writes security-relevant events as JSON Lines to monthly-rotating files (audit-YYYY-MM.log). Logs do not appear in container stdout and contain no personal data in plain text (GDPR-compliant).

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.