About

Docker image for Flarum, the next-generation forum software that makes online discussion fun.

Tip

Want to be notified of new releases? Check out 🔔 Diun (Docker Image Update Notifier) project!

---

• Features
• Build locally
• Image
• Environment variables
  • General
  • Flarum
  • Sidecar cron
  • Database
• Volumes
• Ports
• Usage
  • Docker Compose
  • Command line
• Upgrade
• Notes
  • First launch
  • Scheduler
  • Manage extensions
  • Sending mails with SMTP
• Contributing
• License

Features

• Run as non-root user
• Multi-platform image
• Cron tasks to run the Flarum scheduler as a "sidecar" container
• s6-overlay as process supervisor
• msmtpd SMTP relay image to send emails
• Traefik as reverse proxy and creation/renewal of Let's Encrypt certificates (see this template)

Build locally

git clone https://github.com/crazy-max/docker-flarum.git
cd docker-flarum

# Build image and output to docker (default)
docker buildx bake

# Build multi-platform image
docker buildx bake image-all

Image

Registry	Image
Docker Hub	crazymax/flarum
GitHub Container Registry	ghcr.io/crazy-max/flarum

Following platforms for this image are available:

$ docker buildx imagetools inspect crazymax/flarum --format "{{json .Manifest}}" | \
  jq -r '.manifests[] | select(.platform.os != null and .platform.os != "unknown") | .platform | "\(.os)/\(.architecture)\(if .variant then "/" + .variant else "" end)"'

linux/amd64
linux/arm/v6
linux/arm/v7
linux/arm64

Environment variables

General

• TZ: The timezone assigned to the container (default UTC)
• PUID: Flarum user id (default 1000)
• PGID: Flarum group id (default 1000)
• MEMORY_LIMIT: PHP memory limit (default 256M)
• UPLOAD_MAX_SIZE: Upload max size (default 16M)
• CLEAR_ENV: Clear environment in FPM workers (default yes)
• OPCACHE_MEM_SIZE: PHP OpCache memory consumption (default 128)
• LISTEN_IPV6: Enable IPv6 for Nginx (default true)
• REAL_IP_FROM: Trusted addresses that are known to send correct replacement addresses (default 0.0.0.0/32)
• REAL_IP_HEADER: Request header field whose value will be used to replace the client address (default X-Forwarded-For)
• LOG_IP_VAR: Use another variable to retrieve the remote IP address for access log_format on Nginx. (default remote_addr)

Flarum

• FLARUM_DEBUG: Enables or disables debug mode, used to troubleshoot issues (default false)
• FLARUM_BASE_URL: The URL to your Flarum installation required
• FLARUM_FORUM_TITLE: Flarum forum title, only used during first installation (default Flarum Dockerized)
• FLARUM_API_PATH: Flarum api path (default api)
• FLARUM_ADMIN_PATH: Flarum admin path (default admin)
• FLARUM_POWEREDBY_HEADER: Set Flarum's X-Powered-By header (default true)
• FLARUM_REFERRER_POLICY: Referrer policy (default same-origin)
• FLARUM_COOKIE_SAMESITE: Set SameSite attribute of Set-Cookie (default lax)
• FLARUM_ANNOUNCEMENTS_DISABLED: Disable Flarum announcements on the admin dashboard (default false)

Sidecar cron

The following environment variables are only used if you run the container as "sidecar" cron mode:

• SIDECAR_CRON: Set to 1 to enable sidecar cron mode (default 0)
• CRON_SCHEDULE: Periodically execute Flarum scheduler (default * * * * *)

Database

• DB_HOST: MySQL database hostname / IP address required
• DB_PORT: MySQL database port (default 3306)
• DB_NAME: MySQL database name (default flarum)
• DB_USER: MySQL user (default flarum)
• DB_PASSWORD: MySQL password
• DB_PREFIX: MySQL database prefix (default flarum_)
• DB_NOPREFIX: Enforce no prefix for the MySQL database (default false)
• DB_TIMEOUT: Time in seconds after which we stop trying to reach the MySQL server (useful for clusters, default 60)

Note

DB_USER_FILE and DB_PASSWORD_FILE can be used to fill in the value from a file, especially for Docker's secrets feature.

Volumes

• /data: Contains assets, extensions and storage

Warning

Note that the volume should be owned by the user/group with the specified PUID and PGID. If you don't give the volume correct permissions, the container may not start.

Ports

• 8000: HTTP port

Usage

Docker Compose

Docker compose is the recommended way to run this image. You can use the following docker compose template, then run the container:

docker compose up -d
docker compose logs -f

Command line

You can also use the following minimal command:

docker run -d -p 8000:8000 --name flarum \
  -v $(pwd)/data:/data \
  -e "DB_HOST=db" \
  -e "FLARUM_BASE_URL=http://127.0.0.1:8000" \
  crazymax/flarum:latest

Warning

db must be a running MySQL instance

Upgrade

You can upgrade Flarum automatically through the UI, it works well. But I recommend to recreate the container whenever I push an update:

docker compose pull
docker compose up -d

Notes

First launch

On first launch, an initial administrator user will be created:

Login	Password
flarum	flarum

Scheduler

Flarum scheduled tasks can be run with a "sidecar" container like in the compose file. The sidecar uses the same image, database environment, and /data volume as the main flarum service, but only runs cron:

docker run -d --name flarum_cron \
  -v $(pwd)/data:/data \
  -e "DB_HOST=db" \
  -e "DB_NAME=flarum" \
  -e "DB_USER=flarum" \
  -e "DB_PASSWORD=flarum" \
  -e "FLARUM_BASE_URL=http://127.0.0.1:8000" \
  -e "SIDECAR_CRON=1" \
  crazymax/flarum:latest

Run only one cron sidecar per Flarum installation. The default CRON_SCHEDULE runs php flarum schedule:run every minute.

Manage extensions

This image does not persist /opt/flarum/composer.json, composer.lock, or vendor. Instead, additional direct Composer requirements are persisted in /data/extensions/list and reinstalled when the container starts.

Extensions installed or removed through Flarum's Extension Manager are synchronized to /data/extensions/list automatically. You can also manage Flarum extensions from the command line using the helper script included with this image:

docker compose exec flarum extension require <package> [<package> ...]

If no version constraint is provided, the helper requires <package>:*, which matches Flarum's recommendation for extensions that should track the latest version compatible with the installed Flarum core.

To remove one or more extensions:

docker compose exec flarum extension remove <package> [<package> ...]

If you run Composer manually with scripts disabled, synchronize the persisted extension list afterwards:

docker compose exec flarum extension sync

To list all extensions:

docker compose exec flarum extension list

Example with fof/upload extension:

$ docker compose exec flarum extension require fof/upload
$ docker compose exec flarum extension list
fof/upload:*

Sending mails with SMTP

You can use our SMTP relay msmtpd service published on port 2500 and declared in our compose.yml:

Contributing

Want to contribute? Awesome! The most basic way to show your support is to star the project, or to raise issues. You can also support this project by becoming a sponsor on GitHub or by making a PayPal donation to ensure this journey continues indefinitely!

Thanks again for your support, it is much appreciated! 🙏

License

MIT. See LICENSE for more details.