Installation

Docker Installation

FediSuite runs entirely via Docker Compose. You need Docker, the self-hosting repository and a .env file with your settings. Nothing is built locally, the ready-made image comes from Docker Hub.

1

Clone the repository

Clone the self-hosting repository to your server. It contains the docker-compose.yml, the .env.example and an example for Traefik. Without a target name in the command the folder would be called FediSuite-Self-Hosting, here it is called fedisuite.

bash
git clone https://forge.chrislo.de/FediSuite/FediSuite-Self-Hosting.git fedisuite
cd fedisuite
2

Configure .env

Copy the example configuration and adapt it. All required fields must be set before you start the stack, especially ADMIN_EMAIL and ADMIN_PASSWORD. FediSuite creates the first admin account from them when it starts.

bash
cp .env.example .env
nano .env

Required fields

FEDISUITE_IMAGE christinloehner/fedisuite:2.4.0

Docker image to use. Required, with a fixed version tag, for example {{ $latestVersion }}. The check script rejects the tag latest. On ARM64 servers use the prefix arm64-, i.e. arm64-{{ $latestVersion }}. The Compose file never downloads images on its own; you fetch them with docker compose pull --policy always.

APP_URL https://your-domain.com

Full public URL of your FediSuite instance including https://, without a trailing slash.

JWT_SECRET (long random string)

Secret key for login tokens. Also encrypts stored 2FA secrets. Never share or commit it, and do not change it after the first start.

ACCOUNT_ENCRYPTION_KEY (64 hex characters)

Dedicated key that encrypts the credentials of connected Fediverse accounts (tokens, client secrets). Generate it once with openssl rand -hex 32, do not reuse JWT_SECRET, and back it up separately from the server. FediSuite refuses to start without it, and if it is lost, all connected accounts become unusable.

POSTGRES_DB fedisuite

Name of the PostgreSQL database.

POSTGRES_USER fedisuite

Database user.

POSTGRES_PASSWORD secure-password

Database password. Choose a long, random one.

POSTGRES_IMAGE postgres:18-alpine

PostgreSQL image of the database. New installations use PostgreSQL 18. Do not simply change the major version in the tag later: existing installations with PostgreSQL 15 have their own switching guide.

POSTGRES_DATA_PATH ./postgres

Folder on the server where PostgreSQL stores its data. It is created next to the docker-compose.yml on the first start. Never delete it: it holds all database data.

POSTGRES_DATA_TARGET /var/lib/postgresql

Path inside the container where the folder is mounted. For PostgreSQL 18 this is /var/lib/postgresql (with PostgreSQL 15 it was /var/lib/postgresql/data). Image and path must match; the check script reports mismatches.

DATABASE_URL postgresql://fedisuite:password@db:5432/fedisuite

Full PostgreSQL connection string. Must match the POSTGRES_* values.

ADMIN_EMAIL admin@your-domain.com

Email of the first admin account. The account is created on start if it does not exist yet.

ADMIN_PASSWORD secure-admin-password

Password of the first admin account. Without this value no admin is created and login is not possible.

SMTP_HOST smtp.your-provider.com

SMTP server for outgoing emails.

SMTP_PORT 587

SMTP port (typically 587 for STARTTLS or 465 for SSL).

SMTP_USER your-smtp-user

Username for SMTP authentication.

SMTP_PASS your-smtp-password

Password for SMTP authentication.

SMTP_FROM no-reply@your-domain.com

Sender address for outgoing emails.

Optional fields

APP_NAME FediSuite

Name of the instance, e.g. in emails.

PUBLIC_SITE_URL https://your-domain.com

Public URL of the instance, used for the default user agent and the instance list, if different from APP_URL.

OUTBOUND_HTTP_USER_AGENT Mozilla/5.0 (compatible; …)

User-Agent header for outgoing HTTP requests to Fediverse instances. Default: Mozilla/5.0 (compatible; APP_NAME/1.0; +PUBLIC_SITE_URL).

ENABLE_USER_REGISTRATION true

Set to false to block new registrations. The admin from ADMIN_EMAIL is still created.

TRUST_PROXY 0

How many reverse-proxy hops FediSuite trusts for the client IP. 0 for direct access to port 3000 (template), 1 behind exactly one proxy such as Traefik. If set incorrectly, clients can forge IP addresses that are used for rate limits and audit logs.

Important: Each time the app starts, FediSuite checks whether a user with the address from ADMIN_EMAIL exists. If not, it is created with ADMIN_PASSWORD, otherwise the password stays unchanged. Changing ADMIN_PASSWORD in the .env later therefore does not reset the password. If ADMIN_PASSWORD is missing, no admin is created.
SMTP is required: FediSuite sends email for registration, password reset and the historical import after connecting Fediverse accounts. Do not leave the SMTP settings empty. Without configuration FediSuite tries to reach an SMTP server on localhost:1025.
3

Start the stack

Directory permissions: The image runs without root privileges as UID/GID 1000. The mounted folders uploads, plugins and logs must be writable for that user. Create them like this before the first start:
bash
install -d -m 0750 -o 1000 -g 1000 uploads plugins logs

If you get a permission error, do not work around it by running as root. Fix the ownership of the folders instead.

First check the configuration, then fetch the images and start all containers in the background. The Compose file never downloads images on its own (pull_policy: never), which is why the pull step is needed. Database initialisation runs automatically on start, no separate migration commands are needed.

bash
./scripts/check-config.sh
docker compose pull --policy always
docker compose up -d

The stack consists of four services:

db postgres:18-alpine

PostgreSQL database

app christinloehner/fedisuite:2.4.0

Web interface and API. Initialises the database on start and reports through /api/health whether the app is ready

worker1 christinloehner/fedisuite:2.4.0

Background jobs: scheduler for planned posts, refreshing post numbers, reach, reminders, tips

worker2 christinloehner/fedisuite:2.4.0

Background jobs: refreshing post numbers, reach, tips

The app listens on port 3000, which the Compose file publishes on the host. Via Traefik labels in the docker-compose.yml you can make it accessible under your domain, the labels are already prepared as comments (see Reverse proxy). The workers only start once the health check of the app has passed. How long that can take is explained on the Configuration page.

4

First login

Once db and app have healthy status, the app is reachable. Open your domain (APP_URL) in the browser and log in with the admin credentials set in the .env.

FediSuite is running at
https://your-domain.com

Login

Value from ADMIN_EMAIL

Password

Value from ADMIN_PASSWORD
Tip: After docker compose up -d, db starts first. Once its health check passes, app starts and initialises the database. The workers follow when app is healthy. You can track the progress with docker compose logs -f app. After the first login it is a good idea to set up two-factor authentication for the admin account in the settings.

Status & useful commands

Check the status of all containers

Shows all running containers and their health status.

docker compose ps

Follow logs in real time

Shows live log output for all or individual containers.

docker compose logs -f
docker compose logs -f app      # app only
docker compose logs -f worker1  # worker 1 only

Update to a newer version

Backs up the instance, downloads the new image and restarts affected containers. Update the Compose file with git pull and adjust the tag in .env first, see the Updates page.

docker compose stop app worker1 worker2
./scripts/backup.sh /path/to/backup-storage
docker compose pull --policy always
docker compose up -d

Create a backup

Backs up the database, .env, uploads and plugins into one archive. The archive contains passwords and the ACCOUNT_ENCRYPTION_KEY, so treat it like a secret. More under Backup & restore.

docker compose stop app worker1 worker2
./scripts/backup.sh /path/to/backup-storage
docker compose start app worker1 worker2

Check the health endpoint of the app

Returns JSON with status and db as soon as the app runs and the database is reachable. The Compose file uses the same endpoint for its health check.

curl -s http://127.0.0.1:3000/api/health

Validate configuration before starting

Checks the .env and the Compose file (fixed version tag, PostgreSQL image and matching mount path) and prints no secrets. Do not print docker compose config without --quiet or post it anywhere: its output contains the values from your .env.

./scripts/check-config.sh

Restart the stack

Restarts all containers without recreating them. Changed .env values are not re-read this way. That takes docker compose up -d.

docker compose restart