diff --git a/.gitignore b/.gitignore index 2462b3c..abe2d02 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,5 @@ tskey-* authkey* tailscale/tailscale-data/ +focalboard/config.json + diff --git a/README.md b/README.md index 159395b..b9d6549 100644 --- a/README.md +++ b/README.md @@ -1,108 +1,132 @@ -# {{Service}} with Tailscale Integration +# Focalboard with Tailscale Integration -![{{Service}} with Tailscale](https://damconsulting.llc/images/logo_yellow.svg "{{Service}}") +![Focalboard with Tailscale](https://raw.githubusercontent.com/mattermost/focalboard/main/site/static/img/focalboard-logo.svg "Focalboard") -This project sets up a {{Service}} instance with Tailscale VPN integration using Docker Compose. It creates a secure, private network connection for your {{Service}} instance using Tailscale. +This project sets up a Focalboard instance with Tailscale VPN integration using Docker Compose. -## Prerequisites +By default, Focalboard uses SQLite (single container, no separate database). Postgres support is documented below for users who want it. -- Docker and Docker Compose installed on your system -- A Tailscale account and auth key (get one from https://login.tailscale.com/admin/authkeys) -- Basic understanding of Docker and networking concepts +## Quick Start (Tailscale) -## Project Structure -``` -ts-{{service}}/ -├── docker-compose.yml -├── tailscale/ -│ ├── tailscale-data/ # Persistent Tailscale state -│ └── config/ # Tailscale configuration files -└── {{service}}/ - └── config/ # {{Service}} configuration files -``` - -## Setup Instructions - -1. **Clone the Repository** +1. Copy the example environment file and fill in your values: ```bash - git clone https://gitea.damconsulting.llc/DAM/ts-{{service}} - cd ts-{{service}} + cp .env.example .env ``` -2. Create Required Directories - ```bash - mkdir -p tailscale/tailscale-data - ``` -3. Configure Tailscale - - Make sure `TS_AUTHKEY` and `TS_LOGIN_SERVER` are set in your environment (or a local .env file) before running docker compose. - - Optionally, update the file in `tailscale/config/serve.json` if you need specific Tailscale serve configurations - - CAUTION: Changing `"${TS_CERT_DOMAIN}:443": false` to `true` will expose the service to the internet +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..ts.net` -4. Configure {{Service}} - - See the [documentation]({{service_docs}}) for configuration options +## Headscale -5. Start the Services - ```bash - docker compose up -d - ``` +If you're using Headscale instead of Tailscale: -6. Wait for Certificate to propagate [~2m] +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` -7. Login - - After starting the services your service should be available via tailnet at https://{{service}}.{{YOUR_TAILNET_DOMAIN}}.ts.net ie https://{{service}}.tail12345.ts.net/ +## Configuration -## Services +See `.env.example` for all available options. -### {{service}}-ts (Tailscale) +### Switching Serve Configs -- Runs Tailscale VPN client -- Image: tailscale/tailscale:latest -- Container name: {{service}}-ts -- Hostname: {{service}} -- Requires NET_ADMIN and SYS_MODULE capabilities -- Persists state in ./tailscale/tailscale-data -- Uses configuration from ./tailscale/config +| Environment | File to use | Notes | +|-------------------|--------------------------------------|-------| +| Tailscale (default) | `tailscale/config/serve.json` | Supports HTTP + HTTPS with certs | +| Headscale | `tailscale/config/serve.headscale.json` | HTTP only | -### {{service}} +After changing the serve config, restart the sidecar: +```bash +docker compose restart focalboard-ts +``` -- Depends on {{service}}-ts service +When the sidecar restarts, restart the focalboard container too so it re-joins the new network namespace: +```bash +docker compose restart focalboard +``` -## Usage +## Optional: Direct Host Access -- After starting the services your service should be available via tailnet at `https://{{service}}.{{YOUR_TAILNET_DOMAIN}}.ts.net` ie `https://{{service}}.tail12345.ts.net/` -- To manually get the Tailscale IP/hostname of your container: - ```bash - docker logs {{service}}-ts - ``` - Look for the Tailscale IP address in the logs. +Uncomment the ports section in `docker-compose.yml` if you need direct access without Tailscale: +```yaml +ports: + - 8000:8000 +``` -## Optional Features +## Postgres Mode (optional) -- Uncomment and adjust the ports mapping if you need direct access (without Tailscale): - ```yaml - ports: - - 3000:3000 - ``` -- Stopping the Services - ```bash - docker compose down - ``` +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: -## Troubleshooting -- Check container logs: - ```bash - docker logs {{service}}-ts - docker logs {{service}} - ``` -- Ensure your Tailscale auth key is valid and not expired -- Verify the configuration files have proper permissions -- Make sure required directories exist before starting +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 {{Service}} service uses the Tailscale service's network stack via `network_mode: service:{{service}}-ts` -- Direct port mapping is disabled by default as Tailscale handles the networking -- Services restart automatically unless explicitly stopped -- For more information: - - Tailscale documentation: https://tailscale.com/kb/ - - {{Service}} [documentation]({{service_docs}}) - - {{Service}} [repository]({{service_repo}}) - - {{Service}} [linuxserve.io]({{service_lcsr}}) \ No newline at end of file + +- 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 diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..7e9845c --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,37 @@ +# Security Notes for ts-focalboard + +This repository contains the configuration for deploying Focalboard behind a Tailscale sidecar. + +## What's committed + +- `docker-compose.yml` — service definitions, image versions, env var references +- `.env.example` — template showing required env vars (no real secrets) +- `tailscale/config/serve.json` — Tailscale serve config (committed generic form) +- `tailscale/config/serve.headscale.json` — Headscale variant for testing +- `README.md` — setup instructions + +## What is NOT committed + +- `.env` — contains real authkeys, database passwords +- `tailscale/tailscale-data/` — Tailscale node identity state +- Any volume data + +The `.gitignore` at the repo root blocks accidental commits of these. + +## Rotation + +- If a `TS_AUTHKEY` was ever leaked, revoke it at https://login.tailscale.com/admin/authkeys (or your Headscale equivalent) and generate a new one. +- The `POSTGRES_PASSWORD` in `.env` only needs rotation if the database was exposed beyond the tailnet. + +## Threat model + +This deployment assumes: +- The Mac mini is reachable only via Tailscale/Headscale +- All access to Focalboard goes through the Tailscale sidecar (no exposed ports) +- The Tailnet itself is trusted + +If your threat model differs (e.g., you need to expose Focalboard to the public internet), review the `AllowFunnel` setting in `tailscale/config/serve.json` and the Tailscale ACL controls carefully before proceeding. + +## Reporting + +If you find a security issue with this deployment pattern, contact kevin.riordan@damconsulting.llc. diff --git a/docker-compose.yml b/docker-compose.yml index 72aa767..e2410ef 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,21 +1,38 @@ +# ========================================== +# REQUIRED: Tailscale sidecar (all ts-* services) +# ========================================== services: - {{service}}-ts: + focalboard-ts: image: tailscale/tailscale:latest - hostname: {{service}} - container_name: {{service}}-ts + hostname: focalboard + container_name: focalboard-ts environment: - - TS_AUTHKEY={{YOUR_TAILSCALE_AUTHKEY}} + - TS_AUTHKEY=${TS_AUTHKEY} + - TS_LOGIN_SERVER=${TS_LOGIN_SERVER} - TS_STATE_DIR=/var/lib/tailscale - TS_SERVE_CONFIG=/config/serve.json + - TS_EXTRA_ARGS=--login-server=${TS_LOGIN_SERVER} volumes: - ./tailscale/tailscale-data:/var/lib/tailscale - ./tailscale/config:/config - /dev/net/tun:/dev/net/tun cap_add: - net_admin - - sys_module restart: unless-stopped - {{service-compose}} - network_mode: service:{{service}}-ts - depends_on: - - {{service}}-ts \ No newline at end of file + + # ========================================== + # Focalboard (SQLite by default — no separate DB service) + # For Postgres, see README.md "Postgres mode" section. + # ========================================== + focalboard: + image: mattermost/focalboard:7.11.4 + environment: [] + volumes: + - focalboard-data:/opt/focalboard/data + depends_on: + - focalboard-ts + network_mode: service:focalboard-ts + restart: unless-stopped + +volumes: + focalboard-data: diff --git a/tailscale/config/serve.headscale.json b/tailscale/config/serve.headscale.json new file mode 100644 index 0000000..319b42a --- /dev/null +++ b/tailscale/config/serve.headscale.json @@ -0,0 +1,17 @@ +{ + "TCP": { + "80": { + "HTTP": true + } + }, + "Web": { + "{{service}}.yourdomain.com:80": { + "Handlers": { + "/": { + "Proxy": "http://127.0.0.1:8000" + } + } + } + } +} + diff --git a/tailscale/config/serve.json b/tailscale/config/serve.json index 121ffb8..0ebef13 100644 --- a/tailscale/config/serve.json +++ b/tailscale/config/serve.json @@ -1,19 +1,29 @@ { - "TCP": { - "443": { - "HTTPS": true - } + "TCP": { + "80": { + "HTTP": true }, - "Web": { - "${TS_CERT_DOMAIN}:443": { - "Handlers": { - "/": { - "Proxy": "http://127.0.0.1:3000" - } + "443": { + "HTTPS": true + } + }, + "Web": { + "${TS_CERT_DOMAIN}:80": { + "Handlers": { + "/": { + "Proxy": "http://127.0.0.1:8000" } } }, - "AllowFunnel": { - "${TS_CERT_DOMAIN}:443": false + "${TS_CERT_DOMAIN}:443": { + "Handlers": { + "/": { + "Proxy": "http://127.0.0.1:8000" + } + } } - } \ No newline at end of file + }, + "AllowFunnel": { + "${TS_CERT_DOMAIN}:443": false + } +}