How to Self-Host Focalboard with Docker Compose

Important: Maintenance Status

Focalboard’s standalone version is no longer actively maintained by Mattermost. The last release (v8.0.0) was June 2024. Mattermost has shifted Focalboard’s functionality into the Mattermost plugin system as “Mattermost Boards.” The standalone Docker image still works, but it won’t receive security patches or new features.

If you’re starting fresh, consider Vikunja (similar flexibility, actively maintained) or Planka (simpler Kanban). If you’re already running Mattermost, use the built-in Boards plugin instead of the standalone version.

If you want to run Focalboard despite the maintenance status — it still works and does what it claims — here’s how.

What Is Focalboard?

Focalboard is a Notion-style project management tool from Mattermost. Unlike traditional Kanban boards with fixed columns, Focalboard uses database-style boards where you define custom properties (status, priority, date, person, select, multi-select) and then view the same data as a Kanban board, table, calendar, or gallery. This flexibility makes it useful for task management, CRM, content calendars, and other structured data. (focalboard.com)

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 256 MB of free RAM
• 500 MB of free disk space

Docker Compose Configuration

Focalboard runs as a single container with an embedded SQLite database. No external services required.

services:
  focalboard:
    image: mattermost/focalboard:8.0.0
    container_name: focalboard
    ports:
      - "8000:8000"
    volumes:
      - focalboard-data:/opt/focalboard/data
    restart: unless-stopped

volumes:
  focalboard-data:

Start the container:

docker compose up -d

Access Focalboard at http://your-server:8000.

Initial Setup

1. Open http://your-server:8000 in your browser
2. Click “Create an account” to set up the first user
3. The first registered user becomes the admin
4. Create your first board — choose from templates (Project Tasks, Meeting Notes, Content Calendar, etc.) or start with a blank board

How It Works

Focalboard organizes data differently from traditional Kanban boards:

Boards and Views

A board is a database. Each card in the board has properties you define — text fields, select dropdowns, dates, checkboxes, people, URLs. The same board can be displayed in multiple views:

• Board view (Kanban) — cards grouped by a select property (typically “Status”), arranged in columns
• Table view — spreadsheet-like view showing all properties in columns
• Calendar view — cards placed on a calendar by their date property
• Gallery view — card thumbnails in a grid

You can create multiple views of the same board, each filtered and sorted differently. A “Sprint Board” might have a Kanban view for daily standups, a table view for sprint planning, and a calendar view for deadline tracking.

Card Templates

Define templates for common card structures. A bug report template might include properties for severity, affected component, reproduction steps, and assignee. New cards created from the template get the structure pre-filled.

Configuration

Custom Configuration File

For advanced settings, create a config.json:

{
  "serverRoot": "http://localhost:8000",
  "port": 8000,
  "dbtype": "sqlite3",
  "dbconfig": "/opt/focalboard/data/focalboard.db",
  "useSSL": false,
  "webPath": "./pack",
  "filesDriver": "local",
  "filesPath": "/opt/focalboard/data/files",
  "telemetry": false,
  "enablePublicSharedBoards": false
}

Mount it in Docker Compose:

volumes:
  - ./config.json:/opt/focalboard/config.json:ro
  - focalboard-data:/opt/focalboard/data

PostgreSQL Backend

For larger deployments, switch from SQLite to PostgreSQL:

services:
  focalboard:
    image: mattermost/focalboard:8.0.0
    container_name: focalboard
    ports:
      - "8000:8000"
    volumes:
      - ./config.json:/opt/focalboard/config.json:ro
      - focalboard-data:/opt/focalboard/data
    depends_on:
      - focalboard-db
    restart: unless-stopped

  focalboard-db:
    image: postgres:16-alpine
    container_name: focalboard-db
    environment:
      - POSTGRES_USER=focalboard
      - POSTGRES_PASSWORD=focalboard_secret   # Change this
      - POSTGRES_DB=focalboard
    volumes:
      - focalboard-pgdata:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  focalboard-data:
  focalboard-pgdata:

Update config.json for PostgreSQL:

{
  "dbtype": "postgres",
  "dbconfig": "postgres://focalboard:focalboard_secret@focalboard-db/focalboard?sslmode=disable"
}

Reverse Proxy

For Nginx Proxy Manager or Caddy, point the proxy to http://focalboard:8000. Set serverRoot in config.json to your public URL:

{
  "serverRoot": "https://focalboard.yourdomain.com"
}

WebSocket connections are needed for real-time updates. Ensure your reverse proxy passes WebSocket headers.

Reverse Proxy Setup

Backup

Back up the data volume:

# SQLite backup
docker cp focalboard:/opt/focalboard/data/focalboard.db ./focalboard-backup-$(date +%Y%m%d).db

# Full data directory (includes uploaded files)
docker run --rm -v focalboard-data:/data -v $(pwd):/backup alpine tar czf /backup/focalboard-data-$(date +%Y%m%d).tar.gz /data

Backup Strategy

Troubleshooting

Board appears empty after restart

Symptom: Created boards disappear after container restart. Fix: Verify the data volume is properly mounted. Check that focalboard-data is a named volume, not an anonymous volume. Run docker volume inspect focalboard-data to confirm data persistence.

”Unable to register” error

Symptom: Registration form shows an error. Fix: The standalone version limits registration by default. Check that enableLocalMode is not set to true in your config, which restricts access to single-user mode.

Slow performance with large boards

Symptom: Boards with 500+ cards become sluggish. Fix: Switch from SQLite to PostgreSQL. SQLite handles small to medium boards well, but PostgreSQL performs significantly better with large datasets and concurrent users.

Resource Requirements

• RAM: ~50 MB idle (SQLite), ~120 MB with PostgreSQL
• CPU: Low — minimal background processing
• Disk: ~200 MB for the application, plus storage for uploaded files

Verdict

Focalboard’s Notion-style database approach to task management is genuinely useful — defining custom properties and switching between views is more flexible than fixed Kanban boards. However, the unmaintained status of the standalone version is a deal-breaker for new deployments.

If you’re already running Focalboard and it works for you, it’s fine to keep using it. The v8.0.0 image is stable and functional. But don’t start new projects on unmaintained software.

For new deployments, use Vikunja for a similar multi-view experience (list, Kanban, Gantt, table) with active development, or Planka for straightforward Kanban boards. If you specifically want Focalboard’s database-style boards, the closest maintained alternative is running the full Mattermost server with the Boards plugin enabled.

Related

• Best Self-Hosted Project Management Tools
• Vikunja vs Focalboard
• WeKan vs Focalboard
• Focalboard vs Planka
• How to Self-Host Vikunja
• How to Self-Host Planka
• How to Self-Host Mattermost
• Docker Compose Basics
• Reverse Proxy Setup