Installation

Docker Installation

FediSuite runs entirely via Docker Compose. You need nothing more than Docker, a .env file with your settings — and the repository. Nothing is built locally.

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 and the .env.example — everything you need to get started.

bash 
git clone https://codeberg.org/christinloehner/FediSuite.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, as FediSuite only creates the first admin account on the very first start.

bash 
cp .env.example .env
nano .env

Required fields

FEDISUITE_IMAGE christinloehner/fedisuite:latest

Docker image to use. With latest you always get the most recent version.

APP_URL https://your-domain.com

Full URL of your FediSuite instance including https://.

JWT_SECRET (long random string)

Secret key for JWT tokens. Never share or commit this.

POSTGRES_DB fedisuite

Name of the PostgreSQL database.

POSTGRES_USER fedisuite

Database user.

POSTGRES_PASSWORD secure-password

Database password — choose something secure.

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. Only used on the first start.

ADMIN_PASSWORD secure-admin-password

Password of the first admin account. Without this value, 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 if different from APP_URL.

OUTBOUND_HTTP_USER_AGENT Mozilla/5.0 (compatible; …)

User-Agent header for outgoing HTTP requests (e.g. when fetching Fediverse profiles).

ENABLE_USER_REGISTRATION true

Set to false to disable public registrations. The first admin will still be created.

Important: ADMIN_EMAIL and ADMIN_PASSWORD are only evaluated on the very first start. FediSuite creates the admin account once in the database. If ADMIN_PASSWORD is missing on this first start, there will be no working login — and no way to reset it via the .env afterwards.
SMTP is required: FediSuite sends emails for registration, password reset and import flows after connecting Fediverse accounts. Without SMTP configuration, these features are not available.
3

Start the stack

Start all containers in the background. On the first start, all images will be downloaded. Database initialisation runs automatically — you do not need to run separate migration commands.

bash 
docker compose up -d

The stack consists of four services:

db postgres:15-alpine

PostgreSQL database

app christinloehner/fedisuite:latest

Frontend & API — initialises the database on start

worker1 christinloehner/fedisuite:latest

Background jobs: scheduler, post refresh, reminders, tips

worker2 christinloehner/fedisuite:latest

Background jobs: post refresh, tips

The app runs internally on port 3000. Via Traefik labels in the docker-compose.yml you can make it accessible under your domain — the labels are already prepared as comments.

4

First login

Once all containers have healthy status, the app is reachable. Open your domain 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, wait a moment until the db container passes its health check. Only then does app start and initialise the database. You can track the progress with docker compose logs -f app.

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.

docker compose pull
docker compose up -d

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.

docker compose restart

← Back

Requirements

Next step →

Configuration