Flarum: Simple Discussion Platform

Introduction

If Discourse is the feature-packed powerhouse of modern forums, Flarum is the elegant minimalist alternative. Built with simplicity and speed in mind, Flarum delivers a beautiful discussion platform without the complexity or resource requirements of larger forum software. It’s perfect for small communities, project discussions, or anyone who values clean design and fast performance.

What you’ll learn:

Deploy Flarum with Docker Compose
Configure MySQL/MariaDB for data storage
Set up email notifications with SMTP
Install and configure extensions
Customize appearance and themes
Implement moderation tools
Optimize performance for speed
Manage backups and updates

Prerequisites:

Docker and Docker Compose installed
Domain name with DNS configured
Reverse proxy (Caddy, Nginx, or Traefik) with SSL
512MB+ RAM, 1+ CPU core
SMTP email service for notifications
Basic understanding of Docker and command line

Why Flarum?

The Simplicity Philosophy

Flarum was created with a clear vision: discussions should be simple, fast, and beautiful. Unlike bloated forum software, Flarum focuses on essentials.

Flarum Design Principles:

Mobile-first responsive design
Single-page application for instant interactions
Minimalist interface with no clutter
Extensible through clean API
Fast performance even on modest hardware

Comparison with Alternatives

Feature	Flarum	Discourse	phpBB
Resource Usage	Very light (512MB RAM)	Heavy (2GB+ RAM)	Medium (1GB RAM)
Setup Complexity	Simple	Moderate	Complex
Mobile Experience	Excellent	Excellent	Poor
Customization	Extensions	Plugins	Mods
Performance	Very fast	Fast	Slow
Learning Curve	Easy	Moderate	Steep
Best For	Small communities	Large forums	Traditional forums

Key Features

User Experience:

Clean, modern interface inspired by mobile apps
Infinite scroll with real-time updates
Inline discussions with drag-and-drop post reordering
Full Markdown and BBCode support
Fast search across all content
User mentions and notifications
Tag-based organization instead of traditional categories

Performance:

Lightweight PHP backend with Laravel framework
Responsive frontend built with Mithril.js
Minimal JavaScript bundle size
Efficient database queries
CDN-ready asset delivery

Extensibility:

Over 200 community extensions available
Easy extension installation via Composer
API-first architecture
Custom theme support
Integration with external services

Architecture Overview

Flarum uses a simple three-tier architecture:

Internet → Reverse Proxy (HTTPS) → Flarum PHP-FPM → MariaDB
              ↓                          ↓              ↓
         Nginx/Caddy               Session Cache    User Data
                                        ↓
                                   SMTP Server

Components:

Flarum Application: PHP-FPM running Laravel framework
Web Server: Nginx serving static files and proxying PHP
MariaDB/MySQL: Database for all forum data
Redis (Optional): Cache for sessions and data
SMTP: Email delivery for notifications

Installation with Docker Compose

We’ll use the official community Docker image for easy deployment.

Step 1: Prepare Environment

# Create project directory
mkdir -p ~/flarum && cd ~/flarum

# Create directories for persistent data
mkdir -p data config extensions

# Create environment file
cat > .env <<EOF
# Database settings
MYSQL_ROOT_PASSWORD=secure_root_password_here
MYSQL_DATABASE=flarum
MYSQL_USER=flarum
MYSQL_PASSWORD=secure_flarum_password_here

# Flarum settings
FLARUM_URL=https://forum.yourdomain.com
FLARUM_ADMIN_USER=admin
FLARUM_ADMIN_PASSWORD=secure_admin_password
[email protected]

# Email settings
[email protected]
MAIL_HOST=smtp.sendgrid.net
MAIL_PORT=587
MAIL_USERNAME=apikey
MAIL_PASSWORD=YOUR_SENDGRID_API_KEY
MAIL_ENCRYPTION=tls

# Optional: Site info
FLARUM_TITLE=My Community Forum
EOF

# Secure the environment file
chmod 600 .env

Step 2: Create Docker Compose Configuration

Create docker-compose.yml:

version: '3.8'

services:
  # MariaDB Database
  database:
    image: mariadb:11
    container_name: flarum-db
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
      - MYSQL_DATABASE=${MYSQL_DATABASE}
      - MYSQL_USER=${MYSQL_USER}
      - MYSQL_PASSWORD=${MYSQL_PASSWORD}
    volumes:
      - database_data:/var/lib/mysql
    networks:
      - flarum-net
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 5

  # Flarum Application
  flarum:
    image: mondedie/flarum:latest
    container_name: flarum-app
    restart: unless-stopped
    depends_on:
      database:
        condition: service_healthy
    ports:
      - "8080:8080"
    environment:
      - FORUM_URL=${FLARUM_URL}
      - DB_HOST=database
      - DB_NAME=${MYSQL_DATABASE}
      - DB_USER=${MYSQL_USER}
      - DB_PASS=${MYSQL_PASSWORD}
      - DB_PORT=3306
      - DB_PREFIX=flarum_
      - FLARUM_ADMIN_USER=${FLARUM_ADMIN_USER}
      - FLARUM_ADMIN_PASS=${FLARUM_ADMIN_PASSWORD}
      - FLARUM_ADMIN_MAIL=${FLARUM_ADMIN_EMAIL}
      - FLARUM_TITLE=${FLARUM_TITLE}
      # Email configuration
      - MAIL_FROM=${MAIL_FROM}
      - MAIL_HOST=${MAIL_HOST}
      - MAIL_PORT=${MAIL_PORT}
      - MAIL_USERNAME=${MAIL_USERNAME}
      - MAIL_PASSWORD=${MAIL_PASSWORD}
      - MAIL_ENCRYPTION=${MAIL_ENCRYPTION}
      # Performance settings
      - PHP_MEMORY_LIMIT=256M
      - UPLOAD_MAX_SIZE=50M
      - OPCACHE_MEMORY_LIMIT=128M
      # Timezone
      - TZ=America/New_York
    volumes:
      - flarum_data:/flarum/app/public/assets
      - flarum_extensions:/flarum/app/extensions
      - flarum_storage:/flarum/app/storage
    networks:
      - flarum-net

volumes:
  database_data:
    driver: local
  flarum_data:
    driver: local
  flarum_extensions:
    driver: local
  flarum_storage:
    driver: local

networks:
  flarum-net:
    driver: bridge

Step 3: Launch Flarum

# Start all services
docker-compose up -d

# Watch initialization logs
docker-compose logs -f flarum

# Wait for "Flarum is ready" message (1-2 minutes)
# Press Ctrl+C to exit logs

# Check running containers
docker-compose ps

Step 4: Configure Reverse Proxy

Example Nginx Configuration:

server {
    listen 80;
    server_name forum.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name forum.yourdomain.com;

    ssl_certificate /etc/ssl/certs/forum.crt;
    ssl_certificate_key /etc/ssl/private/forum.key;

    client_max_body_size 50M;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
    }
}

Example Caddy Configuration:

forum.yourdomain.com {
    reverse_proxy localhost:8080
    encode gzip
}

Step 5: Access and Complete Setup

Visit https://forum.yourdomain.com

You should see the Flarum welcome page! Log in with your admin credentials.

Email Configuration

Email is essential for user registration and notifications.

SMTP Provider Setup

SendGrid (Recommended):

[email protected]
MAIL_HOST=smtp.sendgrid.net
MAIL_PORT=587
MAIL_USERNAME=apikey
MAIL_PASSWORD=YOUR_SENDGRID_API_KEY
MAIL_ENCRYPTION=tls

Mailgun:

[email protected]
MAIL_HOST=smtp.mailgun.org
MAIL_PORT=587
[email protected]
MAIL_PASSWORD=YOUR_MAILGUN_PASSWORD
MAIL_ENCRYPTION=tls

Gmail (Testing only):

[email protected]
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
[email protected]
MAIL_PASSWORD=YOUR_APP_PASSWORD
MAIL_ENCRYPTION=tls

Self-Hosted Mail Server:

[email protected]
MAIL_HOST=mail.yourdomain.com
MAIL_PORT=587
[email protected]
MAIL_PASSWORD=YOUR_PASSWORD
MAIL_ENCRYPTION=tls

Testing Email

# Access Flarum container
docker exec -it flarum-app sh

# Test email from PHP
php artisan flarum:test-email [email protected]

# Check logs for errors
tail -f /flarum/app/storage/logs/flarum.log

# Exit container
exit

If email doesn’t work:

Check SMTP credentials are correct
Verify firewall allows outbound port 587
Check spam folder
Review Flarum logs for detailed errors

Extensions

Extensions are Flarum’s superpower. They add functionality without bloating the core.

Installing Extensions

Method 1: Via Composer (Recommended)

# Enter container
docker exec -it flarum-app sh

# Install extension
composer require flarum/tags

# Update Flarum
php flarum migrate
php flarum cache:clear

# Exit
exit

# Restart container
docker-compose restart flarum

Method 2: Via Admin Panel

Some extensions can be installed through the web interface:

Admin → Extensions → Browse
Search for extension
Click Install
Enable after installation

Popular Extensions

Essential Extensions:

1. Tags (Bundled): Organize discussions with tags instead of categories

# Already included, just enable in Admin → Extensions

2. Mentions: Tag users with @ mentions

docker exec -it flarum-app sh
composer require flarum/mentions
php flarum migrate && php flarum cache:clear
exit

3. Suspend: Suspend problematic users

docker exec -it flarum-app sh
composer require flarum/suspend
php flarum migrate && php flarum cache:clear
exit

4. Approval: Require admin approval for new posts

docker exec -it flarum-app sh
composer require flarum/approval
php flarum migrate && php flarum cache:clear
exit

5. Lock: Lock discussions to prevent new replies

docker exec -it flarum-app sh
composer require flarum/lock
php flarum migrate && php flarum cache:clear
exit

Community Extensions:

FriendsOfFlarum (FoF) Extensions:

# Upload extension - allow file uploads
composer require fof/upload

# User Directory - browse all users
composer require fof/user-directory

# Best Answer - mark solutions (great for support forums)
composer require fof/best-answer

# Polls - create polls in discussions
composer require fof/polls

# Formatting - additional text formatting
composer require fof/formatting

# Pages - create static pages
composer require fof/pages

# Drafts - auto-save post drafts
composer require fof/drafts

# Run after each
php flarum migrate && php flarum cache:clear

Other Useful Extensions:

# Markdown editor
composer require s9e/flarum-ext-fancy-markdown

# Math rendering
composer require therealsujitk/flarum-ext-katex

# Custom footer
composer require askvortsov/flarum-custom-footer

# SEO optimization
composer require v17development/flarum-seo

# Run migrations
php flarum migrate && php flarum cache:clear

Managing Extensions

List Installed Extensions:

docker exec -it flarum-app sh
composer show --installed | grep flarum
exit

Update Extensions:

docker exec -it flarum-app sh
composer update
php flarum migrate
php flarum cache:clear
exit
docker-compose restart flarum

Remove Extension:

docker exec -it flarum-app sh
composer remove vendor/extension-name
php flarum cache:clear
exit

Customization

Appearance Settings

Navigate to Admin → Appearance

Basic Customization:

Forum Title: Change in Admin → Basics
Description: Tagline shown on homepage
Welcome Banner: Show/hide welcome hero section
Default Route: Choose homepage (Discussions, Tags, or custom)

Colors: Admin → Appearance → Colors

Primary Color: Main brand color
Secondary Color: Accents and highlights
Header Color: Header background
Custom CSS: Add custom styles

Logo Upload: Admin → Appearance → Upload Logo

Recommended size: 200x50 pixels
Formats: PNG, SVG, JPG

Custom CSS

Add custom styling in Admin → Appearance → Custom Styles:

/* Custom header styling */
.App-header {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

/* Tag badges */
.TagLabel {
    font-weight: 600;
    border-radius: 12px;
    padding: 4px 10px;
}

/* Discussion list hover effect */
.DiscussionListItem:hover {
    background-color: #f8f9fa;
    transition: background-color 0.2s ease;
}

/* Custom button styles */
.Button--primary {
    background-color: #667eea;
    border-radius: 20px;
}

.Button--primary:hover {
    background-color: #5568d3;
}

/* Mobile responsive tweaks */
@media (max-width: 768px) {
    .App-header-title {
        font-size: 18px;
    }
}

Themes

Install community themes:

docker exec -it flarum-app sh

# Dark theme
composer require flarum/theme-dark

# Minimal theme
composer require ianm/flarum-ext-theme-minimal

# Clear cache
php flarum cache:clear
exit

Enable theme in Admin → Appearance → Theme

Tags and Organization

Flarum uses tags instead of traditional forum categories.

Creating Tags

Admin → Tags
Click “Create Tag”
Configure:
- Tag Name: “General Discussion”
- Slug: “general” (auto-generated)
- Description: “General topics and chat”
- Color: Choose from palette
- Icon: Select FontAwesome icon

Tag Types:

Primary Tags (Parent Tags): Like traditional categories

General Discussion
Support
Announcements

Secondary Tags (Child Tags): Subcategories or topic refinements

Bug Report (under Support)
Feature Request (under Support)

Example Tag Structure:

📢 Announcements (Primary)
💬 General Discussion (Primary)
  └── 👋 Introductions (Secondary)
  └── 💡 Ideas (Secondary)
🛠️ Support (Primary)
  └── 🐛 Bug Reports (Secondary)
  └── ❓ Questions (Secondary)
📚 Resources (Primary)
  └── 📖 Documentation (Secondary)
  └── 🎓 Tutorials (Secondary)

Tag Permissions

Control who can use and see tags:

Edit Tag → Permissions
Configure:
- View discussions: Who can see this tag
- Start discussions: Who can create posts
- Reply to discussions: Who can comment

User Management

User Groups

Create and manage user groups:

Admin → Users → Groups

Default Groups:

Admin: Full permissions
Moderators: Can moderate content
Members: Regular users
Guests: Not logged in

Creating Custom Groups:

Click “New Group”
Set name and color
Configure permissions
Assign users

Example Custom Groups:

VIP Members (special badge, extra permissions)
Supporters (donors, custom color)
Beta Testers (access to beta tag)

Permissions

Fine-grained permission control:

Admin → Permissions

Global Permissions:

View discussions
Start discussions
Reply to discussions
Edit posts
Delete posts

Per-Tag Permissions:

Restrict certain tags to specific groups
Allow moderators full access
Limit guest access to read-only

Moderation Tools

Discussion Moderation

As Moderator/Admin:

Rename discussion
Lock discussion (prevent replies)
Sticky discussion (pin to top)
Move tags
Hide/delete discussion

Bulk Actions: Select multiple discussions:

Apply tag
Lock/unlock
Hide/restore

User Moderation

Suspend Users: Requires suspend extension

docker exec -it flarum-app sh
composer require flarum/suspend
php flarum migrate && php flarum cache:clear
exit

Then in Admin → Users → User → Suspend

User Actions:

Edit user details
Change group membership
Delete user and posts
View user activity log

Anti-Spam

Enable Akismet:

docker exec -it flarum-app sh
composer require fof/stopforumspam
php flarum migrate && php flarum cache:clear
exit

Configure in Admin → Extensions → StopForumSpam

reCAPTCHA:

docker exec -it flarum-app sh
composer require askvortsov/flarum-recaptcha
php flarum migrate && php flarum cache:clear
exit

Add reCAPTCHA keys in Admin → Extensions → reCAPTCHA

Performance Optimization

PHP Optimization

The Docker image includes OPcache. Tune settings in docker-compose.yml:

flarum:
  environment:
    - PHP_MEMORY_LIMIT=512M
    - OPCACHE_MEMORY_LIMIT=256M
    - OPCACHE_MAX_FILES=10000
    - OPCACHE_VALIDATE_TIMESTAMPS=0

Database Optimization

# Enter database container
docker exec -it flarum-db mysql -u flarum -p${MYSQL_PASSWORD} flarum

# Optimize tables
OPTIMIZE TABLE flarum_discussions;
OPTIMIZE TABLE flarum_posts;
OPTIMIZE TABLE flarum_users;

# Exit
exit

Redis Caching

Add Redis for session and cache storage:

# Add to docker-compose.yml
services:
  redis:
    image: redis:7-alpine
    container_name: flarum-redis
    restart: unless-stopped
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data
    networks:
      - flarum-net

volumes:
  redis_data:

Configure Flarum to use Redis:

docker exec -it flarum-app sh
composer require flarum/cache-redis
php flarum migrate && php flarum cache:clear
exit

Update environment:

flarum:
  environment:
    - CACHE_DRIVER=redis
    - SESSION_DRIVER=redis
    - REDIS_HOST=redis
    - REDIS_PORT=6379

Restart services:

docker-compose up -d

Backup and Recovery

Automatic Backup Script

Create a backup script:

cat > ~/flarum/backup.sh <<'EOF'
#!/bin/bash
BACKUP_DIR="/backups/flarum"
DATE=$(date +%Y%m%d_%H%M%S)
PROJECT_DIR="/root/flarum"

# Create backup directory
mkdir -p ${BACKUP_DIR}

# Backup database
docker exec flarum-db mysqldump -u flarum -p${MYSQL_PASSWORD} flarum | gzip > ${BACKUP_DIR}/db-${DATE}.sql.gz

# Backup volumes
docker run --rm   -v flarum_flarum_data:/data   -v ${BACKUP_DIR}:/backup   alpine tar czf /backup/data-${DATE}.tar.gz -C /data .

docker run --rm   -v flarum_flarum_extensions:/extensions   -v ${BACKUP_DIR}:/backup   alpine tar czf /backup/extensions-${DATE}.tar.gz -C /extensions .

# Backup configuration
cp ${PROJECT_DIR}/.env ${BACKUP_DIR}/env-${DATE}.bak
cp ${PROJECT_DIR}/docker-compose.yml ${BACKUP_DIR}/compose-${DATE}.yml

# Remove backups older than 30 days
find ${BACKUP_DIR} -name "*.gz" -mtime +30 -delete
find ${BACKUP_DIR} -name "*.bak" -mtime +30 -delete

echo "Backup completed: ${DATE}"
EOF

chmod +x ~/flarum/backup.sh

# Schedule daily backups
crontab -e
# Add: 0 3 * * * /root/flarum/backup.sh

Manual Backup

# Export database
docker exec flarum-db mysqldump -u flarum -p flarum > backup.sql

# Backup assets
docker cp flarum-app:/flarum/app/public/assets ./assets-backup

Restore from Backup

# Stop containers
docker-compose down

# Restore database
docker-compose up -d database
docker exec -i flarum-db mysql -u flarum -p${MYSQL_PASSWORD} flarum < backup.sql

# Restore volumes
docker run --rm   -v flarum_flarum_data:/data   -v $(pwd)/backups:/backup   alpine sh -c "cd /data && tar xzf /backup/data-TIMESTAMP.tar.gz"

# Start all services
docker-compose up -d

Troubleshooting

Common Issues

Issue: 500 Internal Server Error

# Check Flarum logs
docker-compose logs flarum

# Check PHP errors
docker exec -it flarum-app tail -f /flarum/app/storage/logs/flarum.log

# Clear cache
docker exec -it flarum-app php flarum cache:clear

Issue: Database connection failed

# Verify database is running
docker-compose ps

# Check database logs
docker-compose logs database

# Test connection
docker exec -it flarum-app ping database

Issue: Email not sending

# Test SMTP settings
docker exec -it flarum-app php artisan flarum:test-email [email protected]

# Check logs
docker exec -it flarum-app tail -f /flarum/app/storage/logs/flarum.log

Issue: Extensions not loading

# Clear cache
docker exec -it flarum-app php flarum cache:clear

# Rebuild assets
docker exec -it flarum-app php flarum assets:publish

# Check permissions
docker exec -it flarum-app ls -la /flarum/app/extensions

Issue: Slow performance

# Enable OPcache (check it's enabled)
docker exec -it flarum-app php -i | grep opcache

# Add Redis caching (see Performance section)

# Optimize database
docker exec -it flarum-db mysql -u flarum -p${MYSQL_PASSWORD} flarum -e "OPTIMIZE TABLE flarum_discussions, flarum_posts;"

Updating Flarum

Update Process

# Backup first!
./backup.sh

# Pull latest images
docker-compose pull

# Enter container
docker exec -it flarum-app sh

# Update Flarum core
composer update --prefer-dist --no-dev -a --with-all-dependencies

# Update extensions
composer update

# Run migrations
php flarum migrate

# Clear cache
php flarum cache:clear

# Exit
exit

# Restart containers
docker-compose restart

Version Pinning

To pin specific version, edit docker-compose.yml:

flarum:
  image: mondedie/flarum:1.8.5  # Specific version instead of :latest

Conclusion

You now have a fully functional Flarum forum with:

Secure HTTPS access
Working email notifications
Extended functionality through extensions
Customized appearance
Moderation tools configured
Optimized performance
Automated backups

Next Steps

Install essential extensions for your use case
Customize theme and colors to match your brand
Create tag structure for organizing discussions
Set up user groups with appropriate permissions
Test email notifications thoroughly
Configure anti-spam measures
Set up monitoring for uptime and performance

Resources

Your lightweight, elegant discussion platform is ready to foster meaningful conversations!