Focalboard with Tailscale Integration

This project sets up a Focalboard instance with Tailscale VPN integration using Docker Compose.

By default, Focalboard uses SQLite (single container, no separate database). Postgres support is documented below for users who want it.

Quick Start (Tailscale)

1. Copy the example environment file and fill in your values:

   cp .env.example .env
   

2. Edit .env and set:
   • TS_AUTHKEY — your Tailscale auth key
3. Start the stack:

   docker compose up -d
   

4. Complete the setup wizard in your browser (click "create an account" / "register" on the login page — there are no default credentials; the first registered user becomes the admin)
5. Access Focalboard at http://focalboard.<your-tailnet>.ts.net

Headscale

If you're using Headscale instead of Tailscale:

1. Copy the example environment file:

   cp .env.example .env
   

2. Edit .env and set:
   • TS_AUTHKEY — your Headscale auth key
   • TS_LOGIN_SERVER — your Headscale server URL
3. Switch to the Headscale serve config:

   cp tailscale/config/serve.headscale.json tailscale/config/serve.json
   

4. Edit serve.json to use your actual domain. The default in this file uses focalboard.damconsulting.net (Kevin Headscale base domain) - replace it with your own if your setup differs.
5. Start the stack:

   docker compose up -d
   

6. Complete the setup wizard
7. Access Focalboard at http://focalboard.yourdomain.com

Configuration

See .env.example for all available options.

Switching Serve Configs

Environment	File to use	Notes
Tailscale (default)	tailscale/config/serve.json	Supports HTTP + HTTPS with certs
Headscale	tailscale/config/serve.headscale.json	HTTP only

After changing the serve config, restart the sidecar:

docker compose restart focalboard-ts

When the sidecar restarts, restart the focalboard container too so it re-joins the new network namespace:

docker compose restart focalboard

Optional: Direct Host Access

Uncomment the ports section in docker-compose.yml if you need direct access without Tailscale:

ports:
  - 8000:8000

Postgres Mode (optional)

Focalboard supports Postgres for production deployments. Note: Focalboard's image doesn't read DB settings from environment variables — it reads them from /opt/focalboard/config.json inside the container. So enabling Postgres requires two changes:

1. Add a focalboard-db service to docker-compose.yml:

   focalboard-db:
     image: postgres:16
     environment:
       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
       POSTGRES_USER: ${POSTGRES_USER}
       POSTGRES_DB: ${POSTGRES_DB}
     volumes:
       - focalboard-db-data:/var/lib/postgresql/data
     depends_on:
       - focalboard-ts
     network_mode: service:focalboard-ts
     restart: unless-stopped
   
   volumes:
     focalboard-data:
     focalboard-db-data:
   

2. Mount a custom config.json into the focalboard container and add a volume entry:

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

   Then create focalboard/config.json with this content (do NOT commit this file if it contains real credentials):

   {
     "serverRoot": "http://localhost:8000",
     "port": 8000,
     "dbtype": "postgres",
     "dbconfig": "postgres://USER:PASSWORD@127.0.0.1:5432/DBNAME?sslmode=disable",
     "useSSL": false,
     "webpath": "./pack",
     "filespath": "./data/files"
   }
   

   Note 127.0.0.1 — both containers share the sidecar's network namespace, so the DB is on localhost, not focalboard-db. Keep this file out of git (the repo's .gitignore already excludes focalboard/).

Notes

• The mattermost/focalboard image is amd64-only as of the 7.11.4 tag. On arm64 hosts (Apple Silicon), it'll run via emulation. Future versions may add native arm64 support.
• Focalboard's setup wizard lets you create the first workspace + admin account on first visit. There are no default credentials.

Links

• Official site: https://www.focalboard.com/
• Git repository: https://github.com/mattermost/focalboard
• Docker image: https://hub.docker.com/r/mattermost/focalboard