Flarum is a modern, fast, and extensible forum software that makes online discussion fun. This comprehensive guide will walk you through setting up Flarum on your own server using Docker Compose, covering multiple approaches, configuration options, and best practices.
What is Flarum?
Flarum is a next-generation forum software that focuses on simplicity and speed. It’s built with PHP and uses a modern JavaScript framework for the frontend, providing a mobile-first, responsive design that works beautifully on all devices.
Key Features:
- Fast and lightweight
- Mobile-first responsive design
- Extensible with a rich ecosystem of extensions
- Modern, clean interface
- Built-in support for multiple languages
- SEO-friendly URLs
- Real-time notifications
Server Requirements
Before setting up Flarum with Docker, ensure your server meets these requirements:
- Docker: Version 20.10+ recommended
- Docker Compose: Version 2.0+ recommended
- System Resources: Minimum 1GB RAM, 2GB+ recommended
- Storage: At least 2GB free space for Docker images and data
- Network: Open ports for HTTP/HTTPS access
Flarum Technical Requirements (handled by Docker containers):
- PHP 8.1+ (8.2+ recommended) with extensions: curl, dom, fileinfo, gd, json, mbstring, openssl, pdo_mysql, tokenizer, zip, session
- MySQL 5.6+/8.0.23+ or MariaDB 10.0.5+
- Web server (Nginx or Apache)
Method 1: Simple Setup with Official Flarum Image
This approach uses the official Flarum Docker image for a straightforward setup.
Docker Compose Configuration
Create a directory for your Flarum installation:
1 2 3 4 |
mkdir flarum-docker cd flarum-docker |
Create a docker-compose.yml
file:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 |
version: '3.8' services: flarum: image: flarum/flarum:latest container_name: flarum ports: - "8080:80" environment: - FORUM_URL=http://localhost:8080 - DB_HOST=db - DB_NAME=flarum - DB_USER=flarum - DB_PASS=secure_password_here volumes: - ./flarum_data:/flarum/app depends_on: - db restart: unless-stopped db: image: mariadb:10.11 container_name: flarum_db environment: - MYSQL_ROOT_PASSWORD=root_password_here - MYSQL_DATABASE=flarum - MYSQL_USER=flarum - MYSQL_PASSWORD=secure_password_here volumes: - ./db_data:/var/lib/mysql restart: unless-stopped |
Environment Variables for Basic Setup
Variable |
Description |
Required |
Default |
---|---|---|---|
FORUM_URL |
Full URL where your forum will be accessible |
Yes |
– |
DB_HOST |
Database hostname |
Yes |
– |
DB_NAME |
Database name |
Yes |
– |
DB_USER |
Database username |
Yes |
– |
DB_PASS |
Database password |
Yes |
– |
Method 2: Feature-Rich Setup with mondedie/flarum
The mondedie/flarum image is a popular community-maintained image with additional features and better optimization.
Docker Compose Configuration
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 |
version: '3.8' services: flarum: image: mondedie/flarum:stable container_name: flarum ports: - "80:8888" env_file: - flarum.env volumes: - ./flarum/assets:/flarum/app/public/assets - ./flarum/extensions:/flarum/app/extensions - ./flarum/storage:/flarum/app/storage/logs - ./flarum/nginx:/etc/nginx/flarum depends_on: - mariadb restart: unless-stopped mariadb: image: mariadb:10.11 container_name: flarum_mariadb environment: - MYSQL_ROOT_PASSWORD=super_secure_root_password - MYSQL_DATABASE=flarum - MYSQL_USER=flarum - MYSQL_PASSWORD=secure_flarum_password volumes: - ./mysql/data:/var/lib/mysql restart: unless-stopped # Optional: phpMyAdmin for database management phpmyadmin: image: phpmyadmin:latest container_name: flarum_phpmyadmin ports: - "8081:80" environment: - PMA_HOST=mariadb - PMA_USER=flarum - PMA_PASSWORD=secure_flarum_password depends_on: - mariadb restart: unless-stopped |
Environment File (flarum.env)
Create a flarum.env
file with these variables:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 |
# Debug mode (set to false in production) DEBUG=false # Forum URL - MUST match your domain/port FORUM_URL=https://your-domain.com # Database Configuration DB_HOST=mariadb DB_NAME=flarum DB_USER=flarum DB_PASS=secure_flarum_password DB_PREF=flarum_ DB_PORT=3306 # Admin User (required for first installation) # Password must be at least 8 characters FLARUM_ADMIN_USER=admin FLARUM_ADMIN_PASS=admin_password_here FLARUM_ADMIN_MAIL=admin@your-domain.com FLARUM_TITLE=My Awesome Forum # Performance Settings UPLOAD_MAX_SIZE=50M PHP_MEMORY_LIMIT=256M OPCACHE_MEMORY_LIMIT=128 # Container Settings UID=1000 GID=1000 FLARUM_PORT=8888 # Logging LOG_TO_STDOUT=false # Optional: GitHub token for private extensions # GITHUB_TOKEN_AUTH=your_github_token_here # Optional: Additional PHP extensions # PHP_EXTENSIONS=gmp session brotli |
Complete Environment Variables Reference
Variable | Description | Required | Default |
---|---|---|---|
DEBUG | Enable debug mode | No | false |
FORUM_URL | Full forum URL | Yes | – |
DB_HOST | Database host | No | mariadb |
DB_NAME | Database name | No | flarum |
DB_USER | Database username | No | flarum |
DB_PASS | Database password | Yes | – |
DB_PREF | Table prefix | No | – |
DB_PORT | Database port | No | 3306 |
FLARUM_ADMIN_USER | Admin username | Yes* | – |
FLARUM_ADMIN_PASS | Admin password (min 8 chars) | Yes* | – |
FLARUM_ADMIN_MAIL | Admin email | Yes* | – |
FLARUM_TITLE | Forum title | No | Docker-Flarum |
UID | User ID for file permissions | No | 991 |
GID | Group ID for file permissions | No | 991 |
FLARUM_PORT | Internal container port | No | 8888 |
UPLOAD_MAX_SIZE | Max upload file size | No | 50M |
PHP_MEMORY_LIMIT | PHP memory limit | No | 128M |
OPCACHE_MEMORY_LIMIT | OPCache memory limit | No | 128 |
LOG_TO_STDOUT | Output logs to stdout | No | false |
GITHUB_TOKEN_AUTH | GitHub token for private repos | No | false |
PHP_EXTENSIONS | Additional PHP extensions | No | – |
*Required only for initial installation
Method 3: Production-Ready Setup with tiredofit/docker-flarum
This image includes additional features like automatic updates and extension management. Visit the tiredofit/docker-flarum GitHub repository for more details.
Docker Compose Configuration
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
version: '3.8' services: flarum: image: tiredofit/flarum:latest container_name: flarum ports: - "80:80" environment: - SITE_URL=https://your-domain.com - SITE_TITLE=My Forum - ADMIN_USER=admin - ADMIN_PASS=secure_admin_password - ADMIN_EMAIL=admin@your-domain.com - DB_HOST=flarum-db - DB_NAME=flarum - DB_USER=flarum - DB_PASS=secure_db_password - EXTENSIONS_AUTO_UPDATE=TRUE volumes: - ./flarum-data:/data - ./flarum-logs:/www/logs depends_on: - flarum-db restart: unless-stopped flarum-db: image: mariadb:10.11 container_name: flarum-db environment: - MYSQL_ROOT_PASSWORD=super_secure_root_password - MYSQL_DATABASE=flarum - MYSQL_USER=flarum - MYSQL_PASSWORD=secure_db_password volumes: - ./db-data:/var/lib/mysql restart: unless-stopped |
Installation Steps
Step 1: Prepare Your Server
1 2 3 4 5 6 7 8 9 10 11 12 |
# Update your system sudo apt update && sudo apt upgrade -y # Install Docker and Docker Compose (if not already installed) curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh # Add your user to the docker group sudo usermod -aG docker $USER newgrp docker |
Step 2: Set Up Directory Structure
1 2 3 4 5 6 7 8 9 10 11 12 |
# Create project directory mkdir ~/flarum-setup cd ~/flarum-setup # Create data directories mkdir -p flarum/{assets,extensions,storage,nginx} mkdir -p mysql/data # Set proper permissions sudo chown -R 1000:1000 flarum/ |
Step 3: Configure Environment
- Choose one of the Docker Compose configurations above
- Create your
docker-compose.yml
file - Create your environment file (
flarum.env
if using Method 2) - Important: Replace all placeholder passwords with strong, unique passwords
Step 4: Deploy Flarum
1 2 3 4 5 6 7 8 9 10 11 12 13 |
# Start the database first docker-compose up -d mariadb # Wait for database to initialize (30-60 seconds) sleep 60 # Start Flarum docker-compose up -d flarum # Check logs docker-compose logs -f flarum |
Step 5: Complete Installation
- Open your browser and navigate to your forum URL
- If you see the Flarum installation page, fill in the required information:
- Database Configuration: Use the values from your docker-compose.yml
- Admin Account: Create your administrator account
- Forum Details: Set your forum title and other preferences
Managing Extensions
Using mondedie/flarum Image
Extensions can be managed through CLI commands:
1 2 3 4 5 6 7 8 9 10 11 12 13 |
# Install an extension docker exec -it flarum extension require fof/upload # Remove an extension docker exec -it flarum extension remove fof/upload # List installed extensions docker exec -it flarum extension list # Update all extensions docker exec -it flarum composer update |
Auto-Install Extensions
Create an extension list file for automatic installation:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
# Create extensions directory mkdir -p flarum/extensions # Create extension list cat > flarum/extensions/list << EOF fof/upload fof/pages fof/polls fof/discussion-views flarum/akismet flarum/pusher EOF |
Popular Extensions
- fof/upload: File upload functionality
- fof/pages: Create static pages
- fof/polls: Add polls to discussions
- fof/discussion-views: Track discussion views
- flarum/akismet: Spam protection
- flarum/pusher: Real-time notifications
- flarum/statistics: Forum statistics
- flarum/sticky: Sticky discussions
Find more extensions at Extiverse or the Flagrow Extensions Directory.
Useful Links and Resources
Official Documentation
Docker Images
GitHub Repositories
Community Resources
Tutorials and Guides
Thoughts
This guide walks you through different ways to get Flarum running with Docker Compose, whether you’re just testing things out or building something for real users. Pick whatever works best for what you’re trying to do:
- Method 1: Quick and easy setup if you just want to mess around or do some development
- Method 2: More features and solid community backing
- Method 3: Ready for the real world with all the bells and whistles
Don’t forget the basics though – use decent passwords, get SSL set up if people are actually going to use this thing, and back up your stuff regularly. The cool thing about Flarum is you can tweak it however you want, so it’s pretty great for building the kind of community site you actually have in mind.
If you get stuck, check out the official docs or hop into the Flarum community forums – there are tons of helpful folks there who know their stuff.
FAQ
What is self-hosted forum software?
What are the most popular self-hosted forum software options?
What are the minimum server requirements for self-hosted forums?
How difficult is it to install self-hosted forum software?
What is the biggest challenge with self-hosted forums?
How do I protect my forum from spam and attacks?
Do I need programming skills to run a self-hosted forum?
What hosting do I need for a self-hosted forum?
How do I backup my self-hosted forum?
Can I migrate from one forum software to another?
What are the ongoing maintenance requirements?
How much does it cost to run a self-hosted forum?
Should I choose open-source or commercial forum software?
How do I handle user registration and verification?
What legal considerations should I be aware of?
How do I customize the appearance of my forum?
Can I integrate my forum with my existing website?
What plugins or extensions are essential?
How do I optimize my forum for search engines?
What should I do if my forum gets hacked?