How to Self-Host Flarum with Docker Compose

The Modern, Lightweight Forum

Flarum is what happens when you strip a forum down to its essentials and rebuild it with a modern frontend. It’s fast, beautiful, and extensible — the opposite of phpBB’s bloated legacy. If Discourse is too heavy for your needs and you don’t need fediverse federation, Flarum hits the sweet spot between simplicity and capability. Official site

Built on PHP (Laravel) with a Mithril.js frontend, Flarum loads quickly and feels responsive. The extension ecosystem covers most needs: SSO, tags, polls, reactions, Markdown, syntax highlighting, and more.

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 512 MB RAM minimum
• 5 GB of free disk space
• A domain name (recommended for production)

Requirement	Minimum	Recommended
CPU	1 core	2 cores
RAM	512 MB	1 GB
Disk	5 GB	10 GB
Email	Optional	SMTP for notifications

Docker Compose Configuration

Flarum doesn’t have an official Docker image, but the community-maintained crazymax/flarum image is well-regarded and actively updated:

services:
  flarum:
    image: crazymax/flarum:1.8.9
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "127.0.0.1:8000:8000"
    volumes:
      - flarum-data:/data
    environment:
      ## Timezone
      TZ: UTC

      ## Memory limit for PHP
      MEMORY_LIMIT: 256M
      UPLOAD_MAX_SIZE: 16M

      ## Opcache settings for performance
      OPCACHE_MEM_SIZE: 128
      REAL_IP_FROM: 0.0.0.0/32
      REAL_IP_HEADER: X-Forwarded-For
      LOG_IP_VAR: http_x_forwarded_for

      ## Flarum settings
      FLARUM_BASE_URL: https://forum.example.com
      FLARUM_FORUM_TITLE: "My Forum"
      FLARUM_API_PATH: api
      FLARUM_ADMIN_PATH: admin

      ## Database connection
      DB_HOST: db
      DB_NAME: flarum
      DB_USER: flarum
      DB_PASSWORD: change_this_password
      DB_PREFIX: flarum_

      ## SMTP (optional)
      # FLARUM_MAIL_DRIVER: smtp
      # FLARUM_MAIL_HOST: smtp.example.com
      # FLARUM_MAIL_PORT: 587
      # FLARUM_MAIL_USERNAME: your_smtp_user
      # FLARUM_MAIL_PASSWORD: your_smtp_password
      # FLARUM_MAIL_ENCRYPTION: tls
    networks:
      - flarum

  db:
    image: mariadb:11.7
    restart: unless-stopped
    volumes:
      - db-data:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: change_this_root_password
      MYSQL_DATABASE: flarum
      MYSQL_USER: flarum
      MYSQL_PASSWORD: change_this_password
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - flarum

networks:
  flarum:

volumes:
  flarum-data:
  db-data:

Start the stack:

docker compose up -d

First boot takes a minute while Flarum runs migrations and installs itself.

Initial Setup

1. Navigate to https://forum.example.com (or http://localhost:8000 for testing)
2. Create your admin account on the install screen
3. Configure basic settings: forum title, description, welcome banner
4. Set up email at Admin → Email (required for user registration if you want email verification)

Default admin panel is at https://forum.example.com/admin.

Configuration

Admin Panel Settings

Section	Key Settings
Basics	Forum title, description, welcome banner, default language
Email	SMTP driver, host, port, encryption, from address
Permissions	Who can view/post/reply, registration settings
Appearance	Custom CSS, logo, favicon, color scheme
Tags	Create topic categories and organize discussions

Extension Installation

Extensions are Flarum’s strength. Install from the container command line:

# Enter the container
docker compose exec flarum sh

# Install extensions via Composer
cd /opt/flarum
composer require flarum/tags
composer require flarum/mentions
composer require flarum/markdown
composer require flarum/bbcode
composer require flarum/likes
composer require flarum/lock
composer require flarum/sticky
composer require fof/polls
composer require fof/user-bio

After installing, enable extensions from the admin panel.

Popular Extensions

Extension	Purpose	Package
Tags	Topic categorization	flarum/tags
Mentions	@user mentions	flarum/mentions
Markdown	Markdown formatting	flarum/markdown
Likes	Like/react to posts	flarum/likes
Polls	Create polls in discussions	fof/polls
SSO	OIDC/OAuth2 login	fof/oauth
Analytics	Visitor analytics	fof/analytics
Night Mode	Dark theme toggle	fof/nightmode

Advanced Configuration

Custom CSS

The admin panel includes a CSS editor. Add custom styles at Admin → Appearance → Custom CSS:

/* Dark header */
.Header {
    background: #1a1a2e;
}

/* Wider content area */
.container {
    max-width: 1200px;
}

SSO Integration

Install the FoF OAuth extension for Google, GitHub, Discord, or custom OAuth2 login:

docker compose exec flarum sh -c "cd /opt/flarum && composer require fof/oauth"

Configure providers in Admin → FoF OAuth with your client ID and secret.

Reverse Proxy

Flarum listens on port 8000. Place it behind a reverse proxy for HTTPS.

Caddy:

forum.example.com {
    reverse_proxy localhost:8000
}

Set FLARUM_BASE_URL=https://forum.example.com in your Docker Compose environment. See our Reverse Proxy Setup guide.

Backup

# Database backup
docker compose exec db mariadb-dump -u root -p flarum > flarum_backup_$(date +%F).sql

# Application data (uploads, avatars, config)
docker run --rm -v flarum_flarum-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/flarum_data_$(date +%F).tar.gz -C /data .

Back up both the database and the data volume. See our Backup Strategy guide.

Troubleshooting

500 Error on First Load

Symptom: Internal server error when accessing the forum. Fix: Check docker compose logs flarum. Common causes: wrong database credentials, MariaDB not ready yet (wait 30 seconds and reload), or missing FLARUM_BASE_URL. Ensure the database password matches in both the Flarum and MariaDB services.

Extensions Not Installing

Symptom: Composer command fails inside the container. Fix: Increase PHP memory limit with MEMORY_LIMIT: 512M in the environment. Some extensions have specific PHP extension requirements — check the extension’s README.

Email Not Sending

Symptom: Users can’t verify email addresses, password resets fail. Fix: Configure SMTP in Admin → Email. Test with the “Send Test Email” button. If using Gmail, enable “App Passwords” — regular passwords won’t work with 2FA enabled.

Slow Performance

Symptom: Pages take 2+ seconds to load. Fix: Enable OPcache (already set in the Docker image). Check MariaDB performance — add innodb_buffer_pool_size=256M to MariaDB config for larger forums. Ensure the data volume is on SSD storage.

Resource Requirements

Resource	Small Forum (<100 users)	Medium Forum (100-1000 users)
RAM	256-512 MB	1-2 GB
CPU	1 core	2 cores
Disk	2-5 GB	10-20 GB
Bandwidth	5 GB/month	20 GB/month

Flarum is lightweight. It runs comfortably on the cheapest VPS tier available. MariaDB is the heaviest component.

Verdict

Flarum is the best lightweight forum software available. It loads fast, looks modern out of the box, and the extension ecosystem covers most feature needs. It’s dramatically easier to run than Discourse — no 2 GB RAM requirement, no custom launcher, just a standard Docker Compose setup.

Choose Flarum if you want a simple, modern forum without the resource overhead of Discourse. Great for hobby communities, project forums, and small team discussions.

Look elsewhere if you need advanced features like built-in chat, extensive moderation tools, or plugin API maturity. Discourse has a deeper feature set and larger ecosystem. If you need fediverse federation, use Lemmy instead.

FAQ

Is Flarum v2.0 stable?

Flarum v2.0 is in beta as of early 2026. The stable production version is v1.8.x. Stick with v1.8.x for production deployments until v2.0 reaches stable release.

Can I migrate from phpBB or other forums?

Flarum has community-built migration extensions for phpBB, MyBB, vBulletin, and other platforms. Results vary — test migrations on a staging instance first.

How does Flarum compare to Discourse?

Flarum is lighter (512 MB vs 2 GB RAM), simpler to deploy, and faster to load. Discourse has more features, a larger community, built-in chat, and better moderation tools. See our detailed comparison.

Does Flarum support dark mode?

Not by default. Install the fof/nightmode extension for a user-toggleable dark mode.

Related

• Discourse vs Flarum
• How to Self-Host Discourse
• Best Self-Hosted Social Networks
• Replace Reddit
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy