FediSuite Self-Hosting

---

This repository is for people who want to run FediSuite themselves with Docker Compose.

Project website: https://www.fedisuite.com

You do not need to build anything locally. You only need Docker, Docker Compose, and a .env file with your settings.

What Users Should Use

FediSuite currently has several important public URLs with different purposes.

• Project website / landing page: https://www.fedisuite.com
• Self-hosting repository: https://forge.chrislo.de/FediSuite/FediSuite-Self-Hosting
• FediSuite Plugins: https://forge.chrislo.de/FediSuite/FediSuite-Plugins-Repository
• Source code, bug reports and contributions: https://forge.chrislo.de/FediSuite/FediSuite-Docker-Image
• Published Docker image for self-hosters: https://hub.docker.com/r/christinloehner/fedisuite

In short:

• If you want to learn about FediSuite, start at the website.
• If you want to self-host FediSuite, use this repository with the deployment files.
• If you want to integrate plugins into your FediSuite, clone the plugins repo to ./plugins.
• If you want to report bugs or work on the application itself, use the FediSuite-Docker-Image repository.
• If you want the ready-to-run container image, use Docker Hub.

Bug Reporting and Contribution

If you find a bug or if you want to contribute, please either file a bug report or read the CONTRIBUTING.md here:

---> https://forge.chrislo.de/FediSuite/FediSuite-Docker-Image

---

Quick Start

Existing installations: Do not start the updated Compose file before adding the PostgreSQL compatibility settings from POSTGRES-15-TO-18.md. The stack fails safely when these settings are missing; it never changes the database major release automatically.

git clone https://forge.chrislo.de/FediSuite/FediSuite-Self-Hosting.git fedisuite
cd fedisuite
cp .env.example .env

Edit .env and set at least these values:

• FEDISUITE_IMAGE
• POSTGRES_IMAGE
• POSTGRES_DATA_PATH
• POSTGRES_DATA_TARGET
• APP_URL
• JWT_SECRET
• ACCOUNT_ENCRYPTION_KEY
• DATABASE_URL
• POSTGRES_DB
• POSTGRES_USER
• POSTGRES_PASSWORD
• ADMIN_EMAIL
• ADMIN_PASSWORD
• SMTP_HOST
• SMTP_PORT
• SMTP_USER
• SMTP_PASS
• SMTP_FROM

ADMIN_EMAIL and ADMIN_PASSWORD are required on the first start. FediSuite creates the initial admin user from these values. If ADMIN_PASSWORD is missing, you will not be able to log in to the app afterward.

SMTP is also required. FediSuite sends emails for user registration, password reset, and historical import related flows after Fediverse accounts are connected. Do not leave the SMTP settings empty.

If you want to prevent new user sign-ups, set ENABLE_USER_REGISTRATION=false. The initial admin user from ADMIN_EMAIL and ADMIN_PASSWORD is still created on first start.

Before upgrading to an image that encrypts connected-account credentials, generate a separate key with openssl rand -hex 32 and set ACCOUNT_ENCRYPTION_KEY in .env. Keep this exact key in your secure backup, separate from JWT_SECRET. The startup migration encrypts existing account tokens, refresh tokens, client secrets and in-flight OAuth secrets; it is repeatable and refuses to start if the key is missing, malformed or unable to decrypt stored values. Do not rotate or remove the key without a deliberate re-encryption plan. Old database backups and PostgreSQL WAL may still contain earlier plaintext credentials; protect and retire them according to your backup policy.

Create the writable directories, validate the complete configuration, and then start FediSuite:

install -d -m 0750 -o 1000 -g 1000 uploads plugins logs
./scripts/check-config.sh
docker compose pull --policy always
docker compose up -d

Open APP_URL in your browser after the containers are healthy.

Default Setup

The included docker-compose.yml starts four services:

• db: PostgreSQL database
• app: frontend and API
• worker1: background jobs
• worker2: background jobs

The workers handle scheduled posts, refresh jobs, idle reminders, and tips generation. They start only after the app has finished database initialization and passed its health check. The app and both workers have health checks. These checks cover the Node.js process and database connection; inspect the logs and queue metrics when diagnosing remote refresh problems.

Image Tags

The default .env.example pins this image tag:

• christinloehner/fedisuite:2.1.0

Change it deliberately when updating. Every service uses pull_policy: never, so docker compose up -d never contacts a registry or replaces a cached image. The explicit docker compose pull --policy always step is the only documented update path.

Important Variables

Required:

• FEDISUITE_IMAGE
• DATABASE_URL
• JWT_SECRET
• ACCOUNT_ENCRYPTION_KEY
• APP_URL
• ADMIN_EMAIL
• ADMIN_PASSWORD
• SMTP_HOST
• SMTP_PORT
• SMTP_USER
• SMTP_PASS
• SMTP_FROM
• POSTGRES_DB
• POSTGRES_USER
• POSTGRES_PASSWORD
• POSTGRES_IMAGE
• POSTGRES_DATA_PATH
• POSTGRES_DATA_TARGET

Optional:

• APP_NAME
• PUBLIC_SITE_URL
• OUTBOUND_HTTP_USER_AGENT
• ENABLE_USER_REGISTRATION

FediSuite 2.0 Configuration

The configuration guide explains every FediSuite 2.0 switch, default, range and container role in English. The website reference covers the remaining settings. Copy .env.example to .env and keep the real secrets out of Git. The feature switches ENABLE_DRAFTS, ENABLE_CONTENT_CALENDAR, ENABLE_CONTENT_LABELS, ENABLE_CONTENT_RECYCLING, ENABLE_CONTENT_INTELLIGENCE and ENABLE_COMMUNITY_INTELLIGENCE are enabled by default; set a switch to false to hide its UI and return 404 from its API routes. ENGAGEMENT_RETENTION_DAYS retains community interaction records for 730 days by default (90–36500 days).

TRUST_PROXY is set to 0 in the example for direct access to port 3000. Set it to 1 behind exactly one trusted proxy such as Traefik; an incorrect setting can let clients forge IP addresses used by rate limits and audit logs. Keep ALLOW_PRIVATE_INSTANCE_URLS=false unless you intentionally connect an instance on your private network.

The Compose services explicitly assign ENABLE_SCHEDULER, ENABLE_POSTS_REFRESH, ENABLE_REACH_REFRESH, ENABLE_IDLE_REMINDER and ENABLE_TIPS_ENGINE by role; these service values override .env. Only worker1 schedules posts and sends idle reminders. Both workers refresh accounts and process the reach queue, while app does neither. REFRESH_BATCH_SIZE is 5 in both workers unless changed in .env. Advanced reach and refresh limits listed in .env.example are passed unchanged to every container through env_file.

Plugins are mounted at /app/plugins in every service. PLUGINS_ENABLED and PLUGIN_SCAN_ON_START default to true; PLUGIN_API_VERSION defaults to 1. These values can be changed in .env. PLUGIN_DIR is obsolete: current images ignore it, so change the volume mount rather than setting that variable.

The app and worker containers run as the non-root node user (UID/GID 1000). Before upgrading an existing installation, ensure that uploads, plugins and logs are readable by UID 1000 and that writable directories are owned by UID 1000. For a new installation, create them with install -d -m 0750 -o 1000 -g 1000 uploads plugins logs on the Docker host. Existing host directories may need an ownership adjustment before the containers start; back them up first. Do not run the app as root to work around a mount permission error.

PostgreSQL tuning and logs

The defaults in docker-compose.yml suit a small installation. On a host with several GiB of RAM, uncomment shm_size and the command block of the db service and adjust the values: shared_buffers to about 25 % of the RAM you can spare for PostgreSQL, effective_cache_size to the RAM available for the file cache, max_wal_size=4GB to reduce checkpoints under heavy refresh load, and wal_compression=on. Recreate only the db container afterwards (docker compose up -d db) and watch docker compose logs db for errors.

db has a one-minute stop_grace_period so that PostgreSQL can finish its shutdown checkpoint instead of being killed. All services rotate their Docker logs at 25 MB with five files each; application audit logs remain in ./logs.

Traefik

If you use Traefik, you have two options:

• uncomment the example labels in docker-compose.yml
• use docker-compose.traefik.example.yml as a reference

Adjust the hostname, cert resolver, and network name to your environment. The bundled docker-compose.yml publishes port 3000 of the app container; the Traefik example removes that port mapping so the app is only reachable through Traefik. Also set TRUST_PROXY=1.

Update

To update to newer image tags:

Update the Compose repository first, read its migration notes, and create a verified backup. Then change FEDISUITE_IMAGE to the exact target release. Do not use latest.

docker compose stop app worker1 worker2
./scripts/backup.sh /path/on/backup-storage
./scripts/check-config.sh
docker compose pull --policy always
docker compose up -d
docker compose ps

FediSuite uses major.feature.test: operators normally update when the middle number changes. Security releases may require an earlier update; follow the release notes rather than relying on the version number alone.

Backup, restore, and PostgreSQL upgrades

• Backup and restore
• PostgreSQL 15 to 18 upgrade

New installations use PostgreSQL 18. Existing PostgreSQL 15 installations stay on 15 until an operator completes the documented dump-and-restore migration. PostgreSQL 18 also uses a different container mount, so changing only the image tag is unsupported.

Verify

To check that your configuration is valid before starting:

cp .env.example .env
./scripts/check-config.sh

License

FediSuite is licensed under the GNU GPL v3.0. See LICENSE.