# Focalboard with Tailscale Integration

![Focalboard with Tailscale](https://raw.githubusercontent.com/mattermost/focalboard/main/site/static/img/focalboard-logo.svg "Focalboard")

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:
   ```bash
   cp .env.example .env
   ```
2. Edit `.env` and set:
   - `TS_AUTHKEY` — your Tailscale auth key
3. Start the stack:
   ```bash
   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:
   ```bash
   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:
   ```bash
   cp tailscale/config/serve.headscale.json tailscale/config/serve.json
   ```
4. Edit `serve.json` and replace `{{service}}.yourdomain.com` with your actual domain
5. Start the stack:
   ```bash
   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:
```bash
docker compose restart focalboard-ts
```

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

## Optional: Direct Host Access

Uncomment the ports section in `docker-compose.yml` if you need direct access without Tailscale:
```yaml
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`:

   ```yaml
   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:
   ```yaml
   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):
   ```json
   {
     "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