chore: replace stale draft with canonical ts-TEMPLATE form for ts-focalboard

- Replace alternate template form (with {{YOUR_TAILSCALE_AUTHKEY}}, sys_module
  cap, {{service-compose}} placeholder) with the canonical ts-TEMPLATE pattern:
  Tailscale sidecar + Focalboard, both via network_mode namespace
- Use SQLite by default (Focalboard's stock behavior); Postgres mode
  documented in README with config.json mount instructions
- Pin to mattermost/focalboard:7.11.4
- Add SECURITY.md and proper .gitignore (incl. focalboard/config.json
  exclude so Postgres config files stay out of repo)
- Note: official Focalboard image is amd64-only; runs via emulation
  on arm64 hosts (Apple Silicon)
- Verified: setup wizard renders, first-time account creation works

.gitignore

@@ -4,3 +4,5 @@
 tskey-*
 authkey*
 tailscale/tailscale-data/
+focalboard/config.json
+

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
+## Quick Start (Tailscale)
-- A Tailscale account and auth key (get one from https://login.tailscale.com/admin/authkeys)
-- Basic understanding of Docker and networking concepts
 
-## Project Structure
+1. Copy the example environment file and fill in your values:
-```
-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**
    ```bash
-   git clone https://gitea.damconsulting.llc/DAM/ts-{{service}}
+   cp .env.example .env
-   cd ts-{{service}}
    ```
-2. Create Required Directories
+2. Edit `.env` and set:
-    ```bash
+   - `TS_AUTHKEY` — your Tailscale auth key
-    mkdir -p tailscale/tailscale-data
+3. Start the stack:
-    ```
+   ```bash
-3. Configure Tailscale
+   docker compose up -d
-    - 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
+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)
-        - CAUTION: Changing `"${TS_CERT_DOMAIN}:443": false` to `true` will expose the service to the internet
+5. Access Focalboard at `http://focalboard.<your-tailnet>.ts.net`
 
-4. Configure {{Service}}
+## Headscale
-    - See the [documentation]({{service_docs}}) for configuration options
 
-5. Start the Services
+If you're using Headscale instead of Tailscale:
-    ```bash
-    docker compose up -d
-    ```
 
-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 
+## Configuration
-    - 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/
 
-## Services
+See `.env.example` for all available options.
 
-### {{service}}-ts (Tailscale)
+### Switching Serve Configs
 
-- Runs Tailscale VPN client
+| Environment       | File to use                          | Notes |
-- Image: tailscale/tailscale:latest
+|-------------------|--------------------------------------|-------|
-- Container name: {{service}}-ts
+| Tailscale (default) | `tailscale/config/serve.json`       | Supports HTTP + HTTPS with certs |
-- Hostname: {{service}}
+| Headscale         | `tailscale/config/serve.headscale.json` | HTTP only |
-- Requires NET_ADMIN and SYS_MODULE capabilities
-- Persists state in ./tailscale/tailscale-data
-- Uses configuration from ./tailscale/config
 
-### {{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/`
+Uncomment the ports section in `docker-compose.yml` if you need direct access without Tailscale:
-- To manually get the Tailscale IP/hostname of your container:
+```yaml
-    ```bash
+ports:
-    docker logs {{service}}-ts
+  - 8000:8000
-    ```
+```
-    Look for the Tailscale IP address in the logs.
 
-## Optional Features
+## Postgres Mode (optional)
 
-- Uncomment and adjust the ports mapping if you need direct access (without Tailscale):
+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:
-    ```yaml
-    ports:
-    - 3000:3000
-    ```
-- Stopping the Services
-    ```bash
-    docker compose down
-    ```
 
-## Troubleshooting
+1. **Add a `focalboard-db` service** to `docker-compose.yml`:
-- Check container logs:
+
-    ```bash
+   ```yaml
-    docker logs {{service}}-ts
+   focalboard-db:
-    docker logs {{service}}
+     image: postgres:16
-    ```
+     environment:
-- Ensure your Tailscale auth key is valid and not expired
+       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
-- Verify the configuration files have proper permissions
+       POSTGRES_USER: ${POSTGRES_USER}
-- Make sure required directories exist before starting
+       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
+- 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.
-- Services restart automatically unless explicitly stopped
+- Focalboard's setup wizard lets you create the first workspace + admin account on first visit. There are no default credentials.
-- For more information:
+
-    - Tailscale documentation: https://tailscale.com/kb/
+## Links
-    - {{Service}} [documentation]({{service_docs}})
+
-    - {{Service}} [repository]({{service_repo}})
+- Official site: https://www.focalboard.com/
-    - {{Service}} [linuxserve.io]({{service_lcsr}})
+- Git repository: https://github.com/mattermost/focalboard
+- Docker image: https://hub.docker.com/r/mattermost/focalboard

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.

docker-compose.yml

@@ -1,21 +1,38 @@
+# ==========================================
+# REQUIRED: Tailscale sidecar (all ts-* services)
+# ==========================================
 services:
-  {{service}}-ts:
+  focalboard-ts:
     image: tailscale/tailscale:latest
-    hostname: {{service}}
+    hostname: focalboard
-    container_name: {{service}}-ts
+    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: 
+  # Focalboard (SQLite by default — no separate DB service)
-      - {{service}}-ts
+  # 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:

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"
+        }
+      }
+    }
+  }
+}
+

tailscale/config/serve.json

@@ -1,19 +1,29 @@
 {
-    "TCP": {
+  "TCP": {
-      "443": {
+    "80": {
-        "HTTPS": true
+      "HTTP": true
-      }
     },
-    "Web": {
+    "443": {
-      "${TS_CERT_DOMAIN}:443": {
+      "HTTPS": true
-        "Handlers": {
+    }
-          "/": {
+  },
-            "Proxy": "http://127.0.0.1:3000"
+  "Web": {
-          }
+    "${TS_CERT_DOMAIN}:80": {
+      "Handlers": {
+        "/": {
+          "Proxy": "http://127.0.0.1:8000"
         }
       }
     },
-    "AllowFunnel": {
+    "${TS_CERT_DOMAIN}:443": {
-      "${TS_CERT_DOMAIN}:443": false
+      "Handlers": {
+        "/": {
+          "Proxy": "http://127.0.0.1:8000"
+        }
+      }
     }
-  }
+  },
+  "AllowFunnel": {
+    "${TS_CERT_DOMAIN}:443": false
+  }
+}