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.
On this page
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.
git clone https://forge.chrislo.de/FediSuite/FediSuite-Self-Hosting.git fedisuite
cd fedisuite
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.
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.
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.
localhost:1025.
Start the stack
uploads, plugins and logs must be writable for that user. Create them like this before the first start:
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.
./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.
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.
https://your-domain.com
Login
Value from ADMIN_EMAIL
Password
Value from ADMIN_PASSWORD
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