Environment Variables – FediSuite Documentation

What is a .env file?

A .env file is a simple text file with key-value pairs in the format KEY=value. Docker Compose reads it at startup and passes the values to the containers as so-called environment variables — settings that the program receives when it starts.

The advantage: you don't need to touch the docker-compose.yml. All instance-specific values — passwords, domains, secrets — are stored separately in the .env. This makes updates easier, because when updating you only overwrite the docker-compose.yml, not your configuration.

Security: The .env file contains passwords and secrets. It must never be committed to a Git repository. The repository already includes a matching .gitignore entry — still, make sure you don't accidentally publish the file.

The complete template

The repository includes a ready-made template at .env.example. Copy it once to .env and adjust the values.

.env.example

# Database
POSTGRES_DB=fedisuite
POSTGRES_USER=fedisuite
POSTGRES_PASSWORD=change-me
DATABASE_URL=postgresql://fedisuite:change-me@db:5432/fedisuite

# Docker Image
FEDISUITE_IMAGE=christinloehner/fedisuite:latest

# App
JWT_SECRET=replace-with-a-long-random-secret
APP_NAME=FediSuite
APP_URL=https://your-domain.example
PUBLIC_SITE_URL=https://your-domain.example

# Admin account (only evaluated on first start)
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=change-this-admin-password

# Email
SMTP_HOST=smtp.your-provider.example
SMTP_PORT=587
SMTP_USER=your-smtp-user
SMTP_PASS=your-smtp-password
SMTP_FROM=no-reply@your-domain.example

# Optional
OUTBOUND_HTTP_USER_AGENT=Mozilla/5.0 (compatible; FediSuite/1.0; +https://your-domain.example)
ENABLE_USER_REGISTRATION=true

Database connection

FediSuite uses PostgreSQL as its database. The following four variables must match each other — if you set a new password in POSTGRES_PASSWORD, the same password must also appear in the DATABASE_URL.

POSTGRES_DB

fedisuite Required

The name of the database that PostgreSQL creates on first start. You can choose any name — fedisuite is a sensible default.

POSTGRES_USER

fedisuite Required

The database user. PostgreSQL automatically creates this user on first start.

POSTGRES_PASSWORD

secure-password Required

The password for the database user. Choose a strong, random password here. Never leave the default value change-me unchanged.

DATABASE_URL

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

The full connection string through which FediSuite reaches the database. The format is postgresql://USER:PASSWORD@HOSTNAME:PORT/DBNAME. The hostname is db — that is the database container's internal name in the Docker network. Change USER, PASSWORD, and DBNAME to match the values in the POSTGRES_* variables.

Example with custom values: If you choose mySecurePassword99 as the password, the DATABASE_URL must read:
postgresql://fedisuite:mySecurePassword99@db:5432/fedisuite

Docker Image

FEDISUITE_IMAGE

christinloehner/fedisuite:latest Required

Specifies which Docker image is used for the app, worker1, and worker2 containers. The value is composed of IMAGENAME:TAG.

christinloehner/fedisuite:latest Always the latest stable version. Recommended for most operators.

christinloehner/fedisuite:1.20.0 Pin a specific version. Useful if you want to control updates deliberately.

Version numbers: FediSuite uses a three-part scheme (e.g. 1.20.13). The first digit denotes a major version, the second new features and critical fixes (stable production releases), and the third pre-release versions for testing.

App Configuration

APP_URL

https://fedisuite.your-domain.com Required

The full public URL of your FediSuite instance — starting with https:// and without a trailing slash. This URL is used in emails, links, and API responses. If it doesn't match the actual domain, many things will not work correctly.

JWT_SECRET

(long random string, at least 64 characters) Required

A secret key with which FediSuite signs login tokens (JSON Web Tokens). Anyone who knows this key can forge valid tokens and impersonate any user. It must therefore be long, random, and kept secret. Generate it once on the server — do not change it afterwards, as all active logins will become invalid.

Generate JWT_SECRET

openssl rand -hex 64

Run this command on your server and copy the output as the value for JWT_SECRET.

APP_NAME

FediSuite Optional

The display name of your instance, e.g. in emails. Optional — if not set, FediSuite is used as the default.

PUBLIC_SITE_URL

https://fedisuite.your-domain.com Optional

An optional alternative public URL if your instance should be accessible at a different address than APP_URL. In most cases you can omit this or set it to the same value as APP_URL.

Admin Account

FediSuite automatically creates an administrator account on the very first start. Exactly these two variables are used for this — and only once. After that, changes to these values in the .env have no effect.

ADMIN_EMAIL

admin@your-domain.com Required

The email address of the first admin account. You use this address to log in for the first time after installation.

ADMIN_PASSWORD

secure-admin-password Required

The password for the first admin account. Choose a strong password. You can change it at any time in the app after the first login.

Critical: If ADMIN_PASSWORD is missing or empty on first start, no working admin account will be created — and there will be no way to log in or reset a password without directly accessing the database. Set this value before the very first docker compose up -d.

Email (SMTP)

FediSuite sends emails for user registration, password reset, and notifications after connecting Fediverse accounts. Without SMTP configuration, these features are completely disabled. SMTP is therefore required for meaningful operation.

SMTP_HOST

smtp.your-provider.com Required

The hostname of your email provider's SMTP server. Examples: smtp.gmail.com, smtp.mailgun.org, mail.privatebox.de.

SMTP_PORT

587 Required

The port of the SMTP server. Common ports: 587 (STARTTLS, recommended), 465 (SSL/TLS), 25 (unencrypted, not recommended). Which port your provider uses can be found in their documentation.

SMTP_USER

no-reply@your-domain.com Required

The username for SMTP authentication — often identical to the sender email address.

SMTP_PASS

your-smtp-password Required

The password for SMTP authentication. With providers like Gmail, this is often an app-specific password, not the regular account password.

SMTP_FROM

no-reply@your-domain.com Required

The sender address shown in outgoing emails. This generally must match the domain of your SMTP account, otherwise receiving servers will reject the emails.

Access & further options

ENABLE_USER_REGISTRATION

true Optional

Controls whether new users can register via the registration page. Default is true (open). If you want to run FediSuite only for yourself or a fixed group, set this to false.

ENABLE_USER_REGISTRATION=true

Public instance — anyone can register.

ENABLE_USER_REGISTRATION=false

Private instance — no registration possible. The initial admin account is still created.

OUTBOUND_HTTP_USER_AGENT Optional

The User-Agent header that FediSuite sends with outgoing HTTP requests — i.e. when the app fetches profile data or posts from Fediverse servers. Many Fediverse instances evaluate this header to identify which software is talking to them.

OUTBOUND_HTTP_USER_AGENT=Mozilla/5.0 (compatible; FediSuite/1.0; +https://your-domain.com)

Replace your-domain.com with your actual domain so that instance operators can get in touch if needed.

Worker Variables (in docker-compose.yml)

These variables do not belong in the .env file — they are set directly in the docker-compose.yml per service and control which background tasks a container handles. They are documented here for completeness.

ENABLE_SCHEDULER

Enables the scheduler that publishes scheduled posts at the right time. Should only be active in a single worker to avoid duplicate posts. In the default setup, only active in worker1.

ENABLE_POSTS_REFRESH

Enables the regular fetching of updated data from Fediverse platforms — e.g. new reactions or comments on already published posts. Can run in multiple workers simultaneously.

ENABLE_IDLE_REMINDER

Sends reminder emails to users who haven't scheduled or published a post for a while. In the default setup, only active in worker1.

ENABLE_TIPS_ENGINE

Enables the tips engine that generates suggestions and optimization hints for users' posts. Can be distributed across multiple workers.

WORKER_ID

A unique identifier for the worker process (e.g. worker-1). Appears in log output and helps with diagnostics when multiple workers are running.

REFRESH_BATCH_SIZE

How many posts the worker processes per refresh cycle. Default is 5. Lower values are gentler on Fediverse server APIs; higher values speed up updates for many users but may cause rate limiting.