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.

On this page

  1. 1. Clone the repository
  2. 2. Configure .env
  3. 3. Start the stack
  4. 4. First login
  5. Status & useful commands
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:latest

Docker image to use. latest is the current version for amd64, on ARM64 servers use arm64-latest. You can pin a tag such as 2.0.0.

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.

POSTGRES_DB fedisuite

Name of the PostgreSQL database.

POSTGRES_USER fedisuite

Database user.

POSTGRES_PASSWORD secure-password

Database password. Choose a long, random one.

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.

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

Start all containers in the background. On the first start the images are downloaded. Database initialisation runs automatically, no separate migration commands are needed.

bash 
docker compose up -d

The stack consists of four services:

db postgres:15-alpine

PostgreSQL database

app christinloehner/fedisuite:latest

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

worker1 christinloehner/fedisuite:latest

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

worker2 christinloehner/fedisuite:latest

Background jobs: refreshing post numbers, 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

Downloads new images and restarts affected containers. Update the Compose file with git pull first, see the Updates page.

docker compose pull
docker compose up -d

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

Validates the docker-compose.yml and shows the resolved configuration including .env values.

docker compose config

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

Requirements

Configuration