diff --git a/.env.example b/.env.example index a47e2331..27f8b8bc 100644 --- a/.env.example +++ b/.env.example @@ -53,6 +53,14 @@ JWT_REFRESH_EXPIRY=7d # Generate with: openssl rand -hex 32 ENCRYPTION_KEY=GENERATE_WITH_openssl_rand_hex_32 +# Gitea SSO cookie signing secret (separate from JWT — falls back to JWT_ACCESS_SECRET if empty) +# Generate with: openssl rand -hex 32 +GITEA_SSO_SECRET= +# Salt for deriving deterministic service passwords (Gitea, Rocket.Chat) +# Falls back to JWT_ACCESS_SECRET if empty — set a dedicated value to isolate secret rotation +# Generate with: openssl rand -hex 32 +SERVICE_PASSWORD_SALT= + # --- Initial Super Admin User (auto-created during database seeding) --- # These credentials are used to create the initial super admin account # Change these before running the seed script in production diff --git a/CLAUDE.md b/CLAUDE.md index 4f5d757d..6ab9fdd5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co Changemaker Lite is a self-hosted political campaign platform built with Docker Compose. It consolidates advocacy email campaigns, geographic mapping, volunteer management, and administration into a single TypeScript stack. The primary domain is `cmlite.org`. -**Current state:** V2 rebuild substantially complete on the `v2` branch. Core platform operational with Phases 1-14 complete. See `V2_PLAN.md` for the full roadmap. +**Current state:** V2 rebuild substantially complete (merged to `main`). Core platform operational with Phases 1-14 complete. See `V2_PLAN.md` for the full roadmap. **Status Summary:** - ✅ Phases 1-14 Complete (Foundation through Monitoring + DevOps) @@ -160,7 +160,7 @@ changemaker.lite/ The fastest way to deploy. No source code, no compilation: ```bash -curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/v2/scripts/install.sh | bash +curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/main/scripts/install.sh | bash ``` This downloads a ~9MB release tarball, runs the config wizard, and sets `IMAGE_TAG=latest`. Then: @@ -173,11 +173,10 @@ Pre-built images are pulled from `gitea.bnkops.com/admin` (~2 min). Database mig ### Source Install (Development) -1. **Clone repository and checkout v2 branch:** +1. **Clone repository:** ```bash git clone changemaker.lite cd changemaker.lite - git checkout v2 ``` 2. **Create environment file:** @@ -321,7 +320,7 @@ docker compose down ./scripts/upgrade.sh --use-registry --force --skip-backup # Install from tarball (end-user one-liner) -curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/v2/scripts/install.sh | bash +curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/main/scripts/install.sh | bash ``` **Two compose files:** diff --git a/DEV_WORKFLOW.md b/DEV_WORKFLOW.md index 79a31511..3e13cf8b 100644 --- a/DEV_WORKFLOW.md +++ b/DEV_WORKFLOW.md @@ -174,7 +174,7 @@ The tarball contains: ```bash # One-liner -curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/v2/scripts/install.sh | bash +curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/main/scripts/install.sh | bash # Or manual curl -LO https://gitea.bnkops.com/admin/changemaker.lite/releases/latest/download/changemaker-lite-latest.tar.gz diff --git a/README.md b/README.md index acb53945..9a9020ed 100644 --- a/README.md +++ b/README.md @@ -105,7 +105,7 @@ Send SMS campaigns via an Android bridge, sync subscribers to Listmonk for newsl ```bash # One-command install (downloads pre-built images, runs config wizard) -curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/v2/scripts/install.sh | bash +curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/main/scripts/install.sh | bash cd ~/changemaker.lite docker compose up -d @@ -115,7 +115,7 @@ Or clone and build from source: ```bash git clone changemaker.lite -cd changemaker.lite && git checkout v2 +cd changemaker.lite cp .env.example .env # Edit .env -- set passwords, JWT secrets, admin credentials diff --git a/admin/package-lock.json b/admin/package-lock.json index d07a00ce..726e5d9c 100644 --- a/admin/package-lock.json +++ b/admin/package-lock.json @@ -1154,9 +1154,9 @@ "dev": true }, "node_modules/@rollup/rollup-android-arm-eabi": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.57.1.tgz", - "integrity": "sha512-A6ehUVSiSaaliTxai040ZpZ2zTevHYbvu/lDoeAteHI8QnaosIzm4qwtezfRg1jOYaUmnzLX1AOD6Z+UJjtifg==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.60.1.tgz", + "integrity": "sha512-d6FinEBLdIiK+1uACUttJKfgZREXrF0Qc2SmLII7W2AD8FfiZ9Wjd+rD/iRuf5s5dWrr1GgwXCvPqOuDquOowA==", "cpu": [ "arm" ], @@ -1167,9 +1167,9 @@ ] }, "node_modules/@rollup/rollup-android-arm64": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.57.1.tgz", - "integrity": "sha512-dQaAddCY9YgkFHZcFNS/606Exo8vcLHwArFZ7vxXq4rigo2bb494/xKMMwRRQW6ug7Js6yXmBZhSBRuBvCCQ3w==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.60.1.tgz", + "integrity": "sha512-YjG/EwIDvvYI1YvYbHvDz/BYHtkY4ygUIXHnTdLhG+hKIQFBiosfWiACWortsKPKU/+dUwQQCKQM3qrDe8c9BA==", "cpu": [ "arm64" ], @@ -1180,9 +1180,9 @@ ] }, "node_modules/@rollup/rollup-darwin-arm64": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.57.1.tgz", - "integrity": "sha512-crNPrwJOrRxagUYeMn/DZwqN88SDmwaJ8Cvi/TN1HnWBU7GwknckyosC2gd0IqYRsHDEnXf328o9/HC6OkPgOg==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.60.1.tgz", + "integrity": "sha512-mjCpF7GmkRtSJwon+Rq1N8+pI+8l7w5g9Z3vWj4T7abguC4Czwi3Yu/pFaLvA3TTeMVjnu3ctigusqWUfjZzvw==", "cpu": [ "arm64" ], @@ -1193,9 +1193,9 @@ ] }, "node_modules/@rollup/rollup-darwin-x64": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.57.1.tgz", - "integrity": "sha512-Ji8g8ChVbKrhFtig5QBV7iMaJrGtpHelkB3lsaKzadFBe58gmjfGXAOfI5FV0lYMH8wiqsxKQ1C9B0YTRXVy4w==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.60.1.tgz", + "integrity": "sha512-haZ7hJ1JT4e9hqkoT9R/19XW2QKqjfJVv+i5AGg57S+nLk9lQnJ1F/eZloRO3o9Scy9CM3wQ9l+dkXtcBgN5Ew==", "cpu": [ "x64" ], @@ -1206,9 +1206,9 @@ ] }, "node_modules/@rollup/rollup-freebsd-arm64": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.57.1.tgz", - "integrity": "sha512-R+/WwhsjmwodAcz65guCGFRkMb4gKWTcIeLy60JJQbXrJ97BOXHxnkPFrP+YwFlaS0m+uWJTstrUA9o+UchFug==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.60.1.tgz", + "integrity": "sha512-czw90wpQq3ZsAVBlinZjAYTKduOjTywlG7fEeWKUA7oCmpA8xdTkxZZlwNJKWqILlq0wehoZcJYfBvOyhPTQ6w==", "cpu": [ "arm64" ], @@ -1219,9 +1219,9 @@ ] }, "node_modules/@rollup/rollup-freebsd-x64": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.57.1.tgz", - "integrity": "sha512-IEQTCHeiTOnAUC3IDQdzRAGj3jOAYNr9kBguI7MQAAZK3caezRrg0GxAb6Hchg4lxdZEI5Oq3iov/w/hnFWY9Q==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.60.1.tgz", + "integrity": "sha512-KVB2rqsxTHuBtfOeySEyzEOB7ltlB/ux38iu2rBQzkjbwRVlkhAGIEDiiYnO2kFOkJp+Z7pUXKyrRRFuFUKt+g==", "cpu": [ "x64" ], @@ -1232,9 +1232,9 @@ ] }, "node_modules/@rollup/rollup-linux-arm-gnueabihf": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.57.1.tgz", - "integrity": "sha512-F8sWbhZ7tyuEfsmOxwc2giKDQzN3+kuBLPwwZGyVkLlKGdV1nvnNwYD0fKQ8+XS6hp9nY7B+ZeK01EBUE7aHaw==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.60.1.tgz", + "integrity": "sha512-L+34Qqil+v5uC0zEubW7uByo78WOCIrBvci69E7sFASRl0X7b/MB6Cqd1lky/CtcSVTydWa2WZwFuWexjS5o6g==", "cpu": [ "arm" ], @@ -1245,9 +1245,9 @@ ] }, "node_modules/@rollup/rollup-linux-arm-musleabihf": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.57.1.tgz", - "integrity": "sha512-rGfNUfn0GIeXtBP1wL5MnzSj98+PZe/AXaGBCRmT0ts80lU5CATYGxXukeTX39XBKsxzFpEeK+Mrp9faXOlmrw==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.60.1.tgz", + "integrity": "sha512-n83O8rt4v34hgFzlkb1ycniJh7IR5RCIqt6mz1VRJD6pmhRi0CXdmfnLu9dIUS6buzh60IvACM842Ffb3xd6Gg==", "cpu": [ "arm" ], @@ -1258,9 +1258,9 @@ ] }, "node_modules/@rollup/rollup-linux-arm64-gnu": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.57.1.tgz", - "integrity": "sha512-MMtej3YHWeg/0klK2Qodf3yrNzz6CGjo2UntLvk2RSPlhzgLvYEB3frRvbEF2wRKh1Z2fDIg9KRPe1fawv7C+g==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.60.1.tgz", + "integrity": "sha512-Nql7sTeAzhTAja3QXeAI48+/+GjBJ+QmAH13snn0AJSNL50JsDqotyudHyMbO2RbJkskbMbFJfIJKWA6R1LCJQ==", "cpu": [ "arm64" ], @@ -1271,9 +1271,9 @@ ] }, "node_modules/@rollup/rollup-linux-arm64-musl": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.57.1.tgz", - "integrity": "sha512-1a/qhaaOXhqXGpMFMET9VqwZakkljWHLmZOX48R0I/YLbhdxr1m4gtG1Hq7++VhVUmf+L3sTAf9op4JlhQ5u1Q==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.60.1.tgz", + "integrity": "sha512-+pUymDhd0ys9GcKZPPWlFiZ67sTWV5UU6zOJat02M1+PiuSGDziyRuI/pPue3hoUwm2uGfxdL+trT6Z9rxnlMA==", "cpu": [ "arm64" ], @@ -1284,9 +1284,9 @@ ] }, "node_modules/@rollup/rollup-linux-loong64-gnu": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.57.1.tgz", - "integrity": "sha512-QWO6RQTZ/cqYtJMtxhkRkidoNGXc7ERPbZN7dVW5SdURuLeVU7lwKMpo18XdcmpWYd0qsP1bwKPf7DNSUinhvA==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.60.1.tgz", + "integrity": "sha512-VSvgvQeIcsEvY4bKDHEDWcpW4Yw7BtlKG1GUT4FzBUlEKQK0rWHYBqQt6Fm2taXS+1bXvJT6kICu5ZwqKCnvlQ==", "cpu": [ "loong64" ], @@ -1297,9 +1297,9 @@ ] }, "node_modules/@rollup/rollup-linux-loong64-musl": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.57.1.tgz", - "integrity": "sha512-xpObYIf+8gprgWaPP32xiN5RVTi/s5FCR+XMXSKmhfoJjrpRAjCuuqQXyxUa/eJTdAE6eJ+KDKaoEqjZQxh3Gw==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.60.1.tgz", + "integrity": "sha512-4LqhUomJqwe641gsPp6xLfhqWMbQV04KtPp7/dIp0nzPxAkNY1AbwL5W0MQpcalLYk07vaW9Kp1PBhdpZYYcEw==", "cpu": [ "loong64" ], @@ -1310,9 +1310,9 @@ ] }, "node_modules/@rollup/rollup-linux-ppc64-gnu": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.57.1.tgz", - "integrity": "sha512-4BrCgrpZo4hvzMDKRqEaW1zeecScDCR+2nZ86ATLhAoJ5FQ+lbHVD3ttKe74/c7tNT9c6F2viwB3ufwp01Oh2w==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.60.1.tgz", + "integrity": "sha512-tLQQ9aPvkBxOc/EUT6j3pyeMD6Hb8QF2BTBnCQWP/uu1lhc9AIrIjKnLYMEroIz/JvtGYgI9dF3AxHZNaEH0rw==", "cpu": [ "ppc64" ], @@ -1323,9 +1323,9 @@ ] }, "node_modules/@rollup/rollup-linux-ppc64-musl": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.57.1.tgz", - "integrity": "sha512-NOlUuzesGauESAyEYFSe3QTUguL+lvrN1HtwEEsU2rOwdUDeTMJdO5dUYl/2hKf9jWydJrO9OL/XSSf65R5+Xw==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.60.1.tgz", + "integrity": "sha512-RMxFhJwc9fSXP6PqmAz4cbv3kAyvD1etJFjTx4ONqFP9DkTkXsAMU4v3Vyc5BgzC+anz7nS/9tp4obsKfqkDHg==", "cpu": [ "ppc64" ], @@ -1336,9 +1336,9 @@ ] }, "node_modules/@rollup/rollup-linux-riscv64-gnu": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.57.1.tgz", - "integrity": "sha512-ptA88htVp0AwUUqhVghwDIKlvJMD/fmL/wrQj99PRHFRAG6Z5nbWoWG4o81Nt9FT+IuqUQi+L31ZKAFeJ5Is+A==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.60.1.tgz", + "integrity": "sha512-QKgFl+Yc1eEk6MmOBfRHYF6lTxiiiV3/z/BRrbSiW2I7AFTXoBFvdMEyglohPj//2mZS4hDOqeB0H1ACh3sBbg==", "cpu": [ "riscv64" ], @@ -1349,9 +1349,9 @@ ] }, "node_modules/@rollup/rollup-linux-riscv64-musl": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.57.1.tgz", - "integrity": "sha512-S51t7aMMTNdmAMPpBg7OOsTdn4tySRQvklmL3RpDRyknk87+Sp3xaumlatU+ppQ+5raY7sSTcC2beGgvhENfuw==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.60.1.tgz", + "integrity": "sha512-RAjXjP/8c6ZtzatZcA1RaQr6O1TRhzC+adn8YZDnChliZHviqIjmvFwHcxi4JKPSDAt6Uhf/7vqcBzQJy0PDJg==", "cpu": [ "riscv64" ], @@ -1362,9 +1362,9 @@ ] }, "node_modules/@rollup/rollup-linux-s390x-gnu": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.57.1.tgz", - "integrity": "sha512-Bl00OFnVFkL82FHbEqy3k5CUCKH6OEJL54KCyx2oqsmZnFTR8IoNqBF+mjQVcRCT5sB6yOvK8A37LNm/kPJiZg==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.60.1.tgz", + "integrity": "sha512-wcuocpaOlaL1COBYiA89O6yfjlp3RwKDeTIA0hM7OpmhR1Bjo9j31G1uQVpDlTvwxGn2nQs65fBFL5UFd76FcQ==", "cpu": [ "s390x" ], @@ -1375,9 +1375,9 @@ ] }, "node_modules/@rollup/rollup-linux-x64-gnu": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.57.1.tgz", - "integrity": "sha512-ABca4ceT4N+Tv/GtotnWAeXZUZuM/9AQyCyKYyKnpk4yoA7QIAuBt6Hkgpw8kActYlew2mvckXkvx0FfoInnLg==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.60.1.tgz", + "integrity": "sha512-77PpsFQUCOiZR9+LQEFg9GClyfkNXj1MP6wRnzYs0EeWbPcHs02AXu4xuUbM1zhwn3wqaizle3AEYg5aeoohhg==", "cpu": [ "x64" ], @@ -1388,9 +1388,9 @@ ] }, "node_modules/@rollup/rollup-linux-x64-musl": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.57.1.tgz", - "integrity": "sha512-HFps0JeGtuOR2convgRRkHCekD7j+gdAuXM+/i6kGzQtFhlCtQkpwtNzkNj6QhCDp7DRJ7+qC/1Vg2jt5iSOFw==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.60.1.tgz", + "integrity": "sha512-5cIATbk5vynAjqqmyBjlciMJl1+R/CwX9oLk/EyiFXDWd95KpHdrOJT//rnUl4cUcskrd0jCCw3wpZnhIHdD9w==", "cpu": [ "x64" ], @@ -1401,9 +1401,9 @@ ] }, "node_modules/@rollup/rollup-openbsd-x64": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.57.1.tgz", - "integrity": "sha512-H+hXEv9gdVQuDTgnqD+SQffoWoc0Of59AStSzTEj/feWTBAnSfSD3+Dql1ZruJQxmykT/JVY0dE8Ka7z0DH1hw==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.60.1.tgz", + "integrity": "sha512-cl0w09WsCi17mcmWqqglez9Gk8isgeWvoUZ3WiJFYSR3zjBQc2J5/ihSjpl+VLjPqjQ/1hJRcqBfLjssREQILw==", "cpu": [ "x64" ], @@ -1414,9 +1414,9 @@ ] }, "node_modules/@rollup/rollup-openharmony-arm64": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.57.1.tgz", - "integrity": "sha512-4wYoDpNg6o/oPximyc/NG+mYUejZrCU2q+2w6YZqrAs2UcNUChIZXjtafAiiZSUc7On8v5NyNj34Kzj/Ltk6dQ==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.60.1.tgz", + "integrity": "sha512-4Cv23ZrONRbNtbZa37mLSueXUCtN7MXccChtKpUnQNgF010rjrjfHx3QxkS2PI7LqGT5xXyYs1a7LbzAwT0iCA==", "cpu": [ "arm64" ], @@ -1427,9 +1427,9 @@ ] }, "node_modules/@rollup/rollup-win32-arm64-msvc": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.57.1.tgz", - "integrity": "sha512-O54mtsV/6LW3P8qdTcamQmuC990HDfR71lo44oZMZlXU4tzLrbvTii87Ni9opq60ds0YzuAlEr/GNwuNluZyMQ==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.60.1.tgz", + "integrity": "sha512-i1okWYkA4FJICtr7KpYzFpRTHgy5jdDbZiWfvny21iIKky5YExiDXP+zbXzm3dUcFpkEeYNHgQ5fuG236JPq0g==", "cpu": [ "arm64" ], @@ -1440,9 +1440,9 @@ ] }, "node_modules/@rollup/rollup-win32-ia32-msvc": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.57.1.tgz", - "integrity": "sha512-P3dLS+IerxCT/7D2q2FYcRdWRl22dNbrbBEtxdWhXrfIMPP9lQhb5h4Du04mdl5Woq05jVCDPCMF7Ub0NAjIew==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.60.1.tgz", + "integrity": "sha512-u09m3CuwLzShA0EYKMNiFgcjjzwqtUMLmuCJLeZWjjOYA3IT2Di09KaxGBTP9xVztWyIWjVdsB2E9goMjZvTQg==", "cpu": [ "ia32" ], @@ -1453,9 +1453,9 @@ ] }, "node_modules/@rollup/rollup-win32-x64-gnu": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.57.1.tgz", - "integrity": "sha512-VMBH2eOOaKGtIJYleXsi2B8CPVADrh+TyNxJ4mWPnKfLB/DBUmzW+5m1xUrcwWoMfSLagIRpjUFeW5CO5hyciQ==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.60.1.tgz", + "integrity": "sha512-k+600V9Zl1CM7eZxJgMyTUzmrmhB/0XZnF4pRypKAlAgxmedUA+1v9R+XOFv56W4SlHEzfeMtzujLJD22Uz5zg==", "cpu": [ "x64" ], @@ -1466,9 +1466,9 @@ ] }, "node_modules/@rollup/rollup-win32-x64-msvc": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.57.1.tgz", - "integrity": "sha512-mxRFDdHIWRxg3UfIIAwCm6NzvxG0jDX/wBN6KsQFTvKFqqg9vTrWUE68qEjHt19A5wwx5X5aUi2zuZT7YR0jrA==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.60.1.tgz", + "integrity": "sha512-lWMnixq/QzxyhTV6NjQJ4SFo1J6PvOX8vUx5Wb4bBPsEb+8xZ89Bz6kOXpfXj9ak9AHTQVQzlgzBEc1SyM27xQ==", "cpu": [ "x64" ], @@ -2261,9 +2261,9 @@ } }, "node_modules/dompurify": { - "version": "3.3.1", - "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.3.1.tgz", - "integrity": "sha512-qkdCKzLNtrgPFP1Vo+98FRzJnBRGe4ffyCea9IwHB1fyxPOeNTHpLKYGd4Uk9xvNoH0ZoOjwZxNptyMwqrId1Q==", + "version": "3.3.3", + "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.3.3.tgz", + "integrity": "sha512-Oj6pzI2+RqBfFG+qOaOLbFXLQ90ARpcGG6UePL82bJLtdsa6CYJD7nmiU8MW9nQNOtCHV3lZ/Bzq1X0QYbBZCA==", "optionalDependencies": { "@types/trusted-types": "^2.0.7" } @@ -2860,9 +2860,9 @@ "dev": true }, "node_modules/picomatch": { - "version": "4.0.3", - "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz", - "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==", + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz", + "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==", "dev": true, "engines": { "node": ">=12" @@ -3651,9 +3651,9 @@ "integrity": "sha512-LwZrotdHOo12nQuZlHEmtuXdqGoOD0OhaxopaNFxWzInpEgaLWoVuAMbTzixuosCx2nEG58ngzW3vxdWoxIgdg==" }, "node_modules/rollup": { - "version": "4.57.1", - "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.57.1.tgz", - "integrity": "sha512-oQL6lgK3e2QZeQ7gcgIkS2YZPg5slw37hYufJ3edKlfQSGGm8ICoxswK15ntSzF/a8+h7ekRy7k7oWc3BQ7y8A==", + "version": "4.60.1", + "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.60.1.tgz", + "integrity": "sha512-VmtB2rFU/GroZ4oL8+ZqXgSA38O6GR8KSIvWmEFv63pQ0G6KaBH9s07PO8XTXP4vI+3UJUEypOfjkGfmSBBR0w==", "dev": true, "dependencies": { "@types/estree": "1.0.8" @@ -3666,31 +3666,31 @@ "npm": ">=8.0.0" }, "optionalDependencies": { - "@rollup/rollup-android-arm-eabi": "4.57.1", - "@rollup/rollup-android-arm64": "4.57.1", - "@rollup/rollup-darwin-arm64": "4.57.1", - "@rollup/rollup-darwin-x64": "4.57.1", - "@rollup/rollup-freebsd-arm64": "4.57.1", - "@rollup/rollup-freebsd-x64": "4.57.1", - "@rollup/rollup-linux-arm-gnueabihf": "4.57.1", - "@rollup/rollup-linux-arm-musleabihf": "4.57.1", - "@rollup/rollup-linux-arm64-gnu": "4.57.1", - "@rollup/rollup-linux-arm64-musl": "4.57.1", - "@rollup/rollup-linux-loong64-gnu": "4.57.1", - "@rollup/rollup-linux-loong64-musl": "4.57.1", - "@rollup/rollup-linux-ppc64-gnu": "4.57.1", - "@rollup/rollup-linux-ppc64-musl": "4.57.1", - "@rollup/rollup-linux-riscv64-gnu": "4.57.1", - "@rollup/rollup-linux-riscv64-musl": "4.57.1", - "@rollup/rollup-linux-s390x-gnu": "4.57.1", - "@rollup/rollup-linux-x64-gnu": "4.57.1", - "@rollup/rollup-linux-x64-musl": "4.57.1", - "@rollup/rollup-openbsd-x64": "4.57.1", - "@rollup/rollup-openharmony-arm64": "4.57.1", - "@rollup/rollup-win32-arm64-msvc": "4.57.1", - "@rollup/rollup-win32-ia32-msvc": "4.57.1", - "@rollup/rollup-win32-x64-gnu": "4.57.1", - "@rollup/rollup-win32-x64-msvc": "4.57.1", + "@rollup/rollup-android-arm-eabi": "4.60.1", + "@rollup/rollup-android-arm64": "4.60.1", + "@rollup/rollup-darwin-arm64": "4.60.1", + "@rollup/rollup-darwin-x64": "4.60.1", + "@rollup/rollup-freebsd-arm64": "4.60.1", + "@rollup/rollup-freebsd-x64": "4.60.1", + "@rollup/rollup-linux-arm-gnueabihf": "4.60.1", + "@rollup/rollup-linux-arm-musleabihf": "4.60.1", + "@rollup/rollup-linux-arm64-gnu": "4.60.1", + "@rollup/rollup-linux-arm64-musl": "4.60.1", + "@rollup/rollup-linux-loong64-gnu": "4.60.1", + "@rollup/rollup-linux-loong64-musl": "4.60.1", + "@rollup/rollup-linux-ppc64-gnu": "4.60.1", + "@rollup/rollup-linux-ppc64-musl": "4.60.1", + "@rollup/rollup-linux-riscv64-gnu": "4.60.1", + "@rollup/rollup-linux-riscv64-musl": "4.60.1", + "@rollup/rollup-linux-s390x-gnu": "4.60.1", + "@rollup/rollup-linux-x64-gnu": "4.60.1", + "@rollup/rollup-linux-x64-musl": "4.60.1", + "@rollup/rollup-openbsd-x64": "4.60.1", + "@rollup/rollup-openharmony-arm64": "4.60.1", + "@rollup/rollup-win32-arm64-msvc": "4.60.1", + "@rollup/rollup-win32-ia32-msvc": "4.60.1", + "@rollup/rollup-win32-x64-gnu": "4.60.1", + "@rollup/rollup-win32-x64-msvc": "4.60.1", "fsevents": "~2.3.2" } }, @@ -3993,10 +3993,9 @@ "dev": true }, "node_modules/yaml": { - "version": "2.8.2", - "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.2.tgz", - "integrity": "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A==", - "license": "ISC", + "version": "2.8.3", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.3.tgz", + "integrity": "sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg==", "bin": { "yaml": "bin.mjs" }, diff --git a/admin/src/pages/DocsPage.tsx b/admin/src/pages/DocsPage.tsx index 668928f0..80aa8837 100644 --- a/admin/src/pages/DocsPage.tsx +++ b/admin/src/pages/DocsPage.tsx @@ -59,7 +59,6 @@ import { MobileOutlined, DesktopOutlined, CalendarOutlined, - ClearOutlined, FormOutlined, ShareAltOutlined, LockOutlined, @@ -591,40 +590,6 @@ export default function DocsPage() { const isMobile = !screens.md; const { token } = theme.useToken(); const { building, confirmAndBuild, isSuperAdmin } = useMkDocsBuild(); - const [resetting, setResetting] = useState(false); - - const confirmAndReset = useCallback(() => { - if (!isSuperAdmin) return; - Modal.confirm({ - title: 'Reset Documentation Site', - content: ( -
-

This will reset all documentation content to a baseline template.

-

Preserved: header config, analytics tracking, hooks, assets, stylesheets, blog.

-

Deleted: all custom content pages.

-

A backup will be created automatically.

-
- ), - okText: 'Reset Site', - okButtonProps: { danger: true }, - onOk: async () => { - setResetting(true); - try { - const { data } = await api.post('/docs/reset'); - message.success(`Site reset complete. ${data.filesReset} files reset, ${data.filesPreserved} preserved.`); - // Refresh file tree - const treeRes = await api.get('/docs/files'); - setFileTree(treeRes.data.tree || []); - setSelectedFile(null); - setFileContent(''); - } catch { - message.error('Failed to reset documentation site'); - } finally { - setResetting(false); - } - }, - }); - }, [isSuperAdmin]); const [fileTree, setFileTree] = useState(() => getCachedTree() || []); const [config, setConfig] = useState(null); @@ -800,9 +765,10 @@ export default function DocsPage() { } }, [fileContentCache, messageApi]); - // Handle navigation state from command palette — auto-select a file + // Handle navigation state from command palette or metadata page — auto-select a file useEffect(() => { - const selectFile = (location.state as { selectFile?: string } | null)?.selectFile; + const state = location.state as { selectFile?: string; openFile?: string } | null; + const selectFile = state?.selectFile || state?.openFile; if (!selectFile || loading) return; // Expand parent directories so the file is visible in the tree @@ -855,8 +821,22 @@ export default function DocsPage() { if ((e.ctrlKey || e.metaKey) && e.key === 's') { e.preventDefault(); if (collab.active) { - // In collab mode, auto-save handles persistence — just refresh preview - previewIframeRef.current?.contentWindow?.location.reload(); + // In collab mode, explicitly save current content + refresh preview + if (selectedFile && collab.yText) { + const content = collab.yText.toString(); + api.put(`/docs/files/${selectedFile}`, { content }) + .then(() => messageApi.success('Saved')) + .catch(() => messageApi.error('Save failed')); + } + // Refresh preview with cache-buster + if (previewIframeRef.current && selectedFile) { + const url = filePathToMkDocsUrl(selectedFile); + setTimeout(() => { + if (previewIframeRef.current) { + previewIframeRef.current.src = url + '?_t=' + Date.now(); + } + }, 1500); + } } else { saveFile(); } @@ -1603,13 +1583,10 @@ export default function DocsPage() { + + + )} + ), }, diff --git a/api/package-lock.json b/api/package-lock.json index 497b5c67..8acfb808 100644 --- a/api/package-lock.json +++ b/api/package-lock.json @@ -1656,14 +1656,6 @@ "resolved": "https://registry.npmjs.org/@ioredis/commands/-/commands-1.5.0.tgz", "integrity": "sha512-eUgLqrMf8nJkZxT24JvVRrQya1vZkQh8BBeYNwGDqa5I0VUi8ACx7uFvAaLxintokpTenkK6DASvo/bvNbBGow==" }, - "node_modules/@isaacs/cliui": { - "version": "9.0.0", - "resolved": "https://registry.npmjs.org/@isaacs/cliui/-/cliui-9.0.0.tgz", - "integrity": "sha512-AokJm4tuBHillT+FpMtxQ60n8ObyXBatq7jD2/JA9dxbDDokKQm8KMht5ibGzLVU9IJDIKK4TPKgMHEYMn3lMg==", - "engines": { - "node": ">=18" - } - }, "node_modules/@js-temporal/polyfill": { "version": "0.5.1", "resolved": "https://registry.npmjs.org/@js-temporal/polyfill/-/polyfill-0.5.1.tgz", @@ -1901,6 +1893,7 @@ "resolved": "https://registry.npmjs.org/@types/cookie-parser/-/cookie-parser-1.4.10.tgz", "integrity": "sha512-B4xqkqfZ8Wek+rCOeRxsjMS9OgvzebEzzLYw7NHYuvzb7IdxOkI0ZHGgeEBX4PUM7QGVvNSK60T3OvWj3YfBRg==", "dev": true, + "license": "MIT", "peerDependencies": { "@types/express": "*" } @@ -2102,9 +2095,9 @@ } }, "node_modules/ajv": { - "version": "8.17.1", - "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.17.1.tgz", - "integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==", + "version": "8.18.0", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz", + "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==", "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", @@ -2216,14 +2209,11 @@ } }, "node_modules/balanced-match": { - "version": "4.0.2", - "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.2.tgz", - "integrity": "sha512-x0K50QvKQ97fdEz2kPehIerj+YTeptKF9hyYkKf6egnwmMWAkADiO0QCzSp0R5xN8FTZgYaBfSaue46Ej62nMg==", - "dependencies": { - "jackspeak": "^4.2.3" - }, + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz", + "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==", "engines": { - "node": "20 || >=22" + "node": "18 || 20 || >=22" } }, "node_modules/bcryptjs": { @@ -2260,14 +2250,14 @@ } }, "node_modules/brace-expansion": { - "version": "5.0.2", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.2.tgz", - "integrity": "sha512-Pdk8c9poy+YhOgVWw1JNN22/HcivgKWwpxKq04M/jTmHyCZn12WPJebZxdjSa5TmBqISrUSgNYU3eRORljfCCw==", + "version": "5.0.5", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.5.tgz", + "integrity": "sha512-VZznLgtwhn+Mact9tfiwx64fA9erHH/MCXEUfB/0bX/6Fz6ny5EGTXYltMocqg4xFAQZtnO3DHWWXi8RiuN7cQ==", "dependencies": { "balanced-match": "^4.0.2" }, "engines": { - "node": "20 || >=22" + "node": "18 || 20 || >=22" } }, "node_modules/buffer-equal-constant-time": { @@ -2548,6 +2538,7 @@ "version": "1.4.7", "resolved": "https://registry.npmjs.org/cookie-parser/-/cookie-parser-1.4.7.tgz", "integrity": "sha512-nGUvgXnotP3BsjiLX2ypbQnWoGUPIIfHQNZkkC668ntrzGWEZVW70HDEB1qnNGMicPje6EttlIgzo51YSwNQGw==", + "license": "MIT", "dependencies": { "cookie": "0.7.2", "cookie-signature": "1.0.6" @@ -2700,15 +2691,15 @@ } }, "node_modules/drizzle-kit": { - "version": "0.31.9", - "resolved": "https://registry.npmjs.org/drizzle-kit/-/drizzle-kit-0.31.9.tgz", - "integrity": "sha512-GViD3IgsXn7trFyBUUHyTFBpH/FsHTxYJ66qdbVggxef4UBPHRYxQaRzYLTuekYnk9i5FIEL9pbBIwMqX/Uwrg==", + "version": "0.31.10", + "resolved": "https://registry.npmjs.org/drizzle-kit/-/drizzle-kit-0.31.10.tgz", + "integrity": "sha512-7OZcmQUrdGI+DUNNsKBn1aW8qSoKuTH7d0mYgSP8bAzdFzKoovxEFnoGQp2dVs82EOJeYycqRtciopszwUf8bw==", "dev": true, "dependencies": { "@drizzle-team/brocli": "^0.10.2", "@esbuild-kit/esm-loader": "^2.5.5", "esbuild": "^0.25.4", - "esbuild-register": "^3.5.0" + "tsx": "^4.21.0" }, "bin": { "drizzle-kit": "bin.cjs" @@ -3426,41 +3417,6 @@ "@esbuild/win32-x64": "0.27.3" } }, - "node_modules/esbuild-register": { - "version": "3.6.0", - "resolved": "https://registry.npmjs.org/esbuild-register/-/esbuild-register-3.6.0.tgz", - "integrity": "sha512-H2/S7Pm8a9CL1uhp9OvjwrBh5Pvx0H8qVOxNu8Wed9Y7qv56MPtq+GGM8RJpq6glYJn9Wspr8uw7l55uyinNeg==", - "dev": true, - "dependencies": { - "debug": "^4.3.4" - }, - "peerDependencies": { - "esbuild": ">=0.12 <1" - } - }, - "node_modules/esbuild-register/node_modules/debug": { - "version": "4.4.3", - "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz", - "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==", - "dev": true, - "dependencies": { - "ms": "^2.1.3" - }, - "engines": { - "node": ">=6.0" - }, - "peerDependenciesMeta": { - "supports-color": { - "optional": true - } - } - }, - "node_modules/esbuild-register/node_modules/ms": { - "version": "2.1.3", - "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", - "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", - "dev": true - }, "node_modules/escape-html": { "version": "1.0.3", "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz", @@ -3623,9 +3579,9 @@ ] }, "node_modules/fastify": { - "version": "5.7.4", - "resolved": "https://registry.npmjs.org/fastify/-/fastify-5.7.4.tgz", - "integrity": "sha512-e6l5NsRdaEP8rdD8VR0ErJASeyaRbzXYpmkrpr2SuvuMq6Si3lvsaVy5C+7gLanEkvjpMDzBXWE5HPeb/hgTxA==", + "version": "5.8.4", + "resolved": "https://registry.npmjs.org/fastify/-/fastify-5.8.4.tgz", + "integrity": "sha512-sa42J1xylbBAYUWALSBoyXKPDUvM3OoNOibIefA+Oha57FryXKKCZarA1iDntOCWp3O35voZLuDg2mdODXtPzQ==", "funding": [ { "type": "github", @@ -3646,7 +3602,7 @@ "fast-json-stringify": "^6.0.0", "find-my-way": "^9.0.0", "light-my-request": "^6.0.0", - "pino": "^10.1.0", + "pino": "^9.14.0 || ^10.1.0", "process-warning": "^5.0.0", "rfdc": "^1.3.1", "secure-json-parse": "^4.0.0", @@ -4066,20 +4022,6 @@ "url": "https://github.com/sponsors/dmonad" } }, - "node_modules/jackspeak": { - "version": "4.2.3", - "resolved": "https://registry.npmjs.org/jackspeak/-/jackspeak-4.2.3.tgz", - "integrity": "sha512-ykkVRwrYvFm1nb2AJfKKYPr0emF6IiXDYUaFx4Zn9ZuIH7MrzEZ3sD5RlqGXNRpHtvUHJyOnCEFxOlNDtGo7wg==", - "dependencies": { - "@isaacs/cliui": "^9.0.0" - }, - "engines": { - "node": "20 || >=22" - }, - "funding": { - "url": "https://github.com/sponsors/isaacs" - } - }, "node_modules/jiti": { "version": "2.6.1", "resolved": "https://registry.npmjs.org/jiti/-/jiti-2.6.1.tgz", @@ -4407,14 +4349,14 @@ } }, "node_modules/minimatch": { - "version": "10.2.0", - "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.0.tgz", - "integrity": "sha512-ugkC31VaVg9cF0DFVoADH12k6061zNZkZON+aX8AWsR9GhPcErkcMBceb6znR8wLERM2AkkOxy2nWRLpT9Jq5w==", + "version": "10.2.5", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.5.tgz", + "integrity": "sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==", "dependencies": { - "brace-expansion": "^5.0.2" + "brace-expansion": "^5.0.5" }, "engines": { - "node": "20 || >=22" + "node": "18 || 20 || >=22" }, "funding": { "url": "https://github.com/sponsors/isaacs" @@ -4542,9 +4484,9 @@ } }, "node_modules/nodemailer": { - "version": "8.0.1", - "resolved": "https://registry.npmjs.org/nodemailer/-/nodemailer-8.0.1.tgz", - "integrity": "sha512-5kcldIXmaEjZcHR6F28IKGSgpmZHaF1IXLWFTG+Xh3S+Cce4MiakLtWY+PlBU69fLbRa8HlaGIrC/QolUpHkhg==", + "version": "8.0.4", + "resolved": "https://registry.npmjs.org/nodemailer/-/nodemailer-8.0.4.tgz", + "integrity": "sha512-k+jf6N8PfQJ0Fe8ZhJlgqU5qJU44Lpvp2yvidH3vp1lPnVQMgi4yEEMPXg5eJS1gFIJTVq1NHBk7Ia9ARdSBdQ==", "engines": { "node": ">=6.0.0" } @@ -4705,9 +4647,9 @@ } }, "node_modules/path-to-regexp": { - "version": "0.1.12", - "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-0.1.12.tgz", - "integrity": "sha512-RA1GjUVMnvYFxuqovrEqZoxxW5NUZqbwKtYz/Tt7nXerk0LbLblQmrsgdeOxV5SFHf0UDggjS/bSeOZwt1pmEQ==" + "version": "0.1.13", + "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-0.1.13.tgz", + "integrity": "sha512-A/AGNMFN3c8bOlvV9RreMdrv7jsmF9XIfDeCd87+I8RNg6s78BhJxMu69NEMHBSJFxKidViTEdruRwEk/WIKqA==" }, "node_modules/pathe": { "version": "2.0.3", @@ -5000,9 +4942,9 @@ } }, "node_modules/qs": { - "version": "6.14.1", - "resolved": "https://registry.npmjs.org/qs/-/qs-6.14.1.tgz", - "integrity": "sha512-4EK3+xJl8Ts67nLYNwqw/dsFVnCf+qR7RgXSK9jEEm9unao3njwMDdmsdvoKBKHzxd7tCYz5e5M+SnMjdtXGQQ==", + "version": "6.14.2", + "resolved": "https://registry.npmjs.org/qs/-/qs-6.14.2.tgz", + "integrity": "sha512-V/yCWTTF7VJ9hIh18Ugr2zhJMP01MY7c5kh4J870L7imm6/DIzBsNLTXzMwUA3yZ5b/KBqLx8Kp3uRvd7xSe3Q==", "dependencies": { "side-channel": "^1.1.0" }, @@ -5848,10 +5790,9 @@ "integrity": "sha512-JKhqTOwSrqNA1NY5lSztJ1GrBiUodLMmIZuLiDaMRJ+itFd+ABVE8XBjOvIWL+rSqNDC74LCSFmlb/U4UZ4hJQ==" }, "node_modules/yaml": { - "version": "2.8.2", - "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.2.tgz", - "integrity": "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A==", - "license": "ISC", + "version": "2.8.3", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.3.tgz", + "integrity": "sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg==", "bin": { "yaml": "bin.mjs" }, diff --git a/api/src/config/env.ts b/api/src/config/env.ts index 4815fb23..aa1edd85 100644 --- a/api/src/config/env.ts +++ b/api/src/config/env.ts @@ -38,6 +38,11 @@ const envSchema = z.object({ // Encryption (for DB-stored secrets like SMTP password — required for all environments) ENCRYPTION_KEY: z.string().min(32, 'ENCRYPTION_KEY must be at least 32 characters'), + // Gitea SSO cookie signing secret (falls back to JWT_ACCESS_SECRET if empty) + GITEA_SSO_SECRET: z.string().default(''), + // Salt for deriving deterministic service passwords (Gitea, Rocket.Chat — falls back to JWT_ACCESS_SECRET if empty) + SERVICE_PASSWORD_SALT: z.string().default(''), + // Initial Super Admin (auto-created during database seeding) INITIAL_ADMIN_EMAIL: z.string().email().default('admin@cmlite.org'), INITIAL_ADMIN_PASSWORD: z.string().min(12).default('REQUIRED_STRONG_PASSWORD_CHANGE_THIS') diff --git a/api/src/modules/auth/auth.routes.ts b/api/src/modules/auth/auth.routes.ts index 93b0ca00..b1dc2535 100644 --- a/api/src/modules/auth/auth.routes.ts +++ b/api/src/modules/auth/auth.routes.ts @@ -1,6 +1,7 @@ import { Router, Request, Response, NextFunction } from 'express'; import { z } from 'zod'; import bcrypt from 'bcryptjs'; +import jwt from 'jsonwebtoken'; import { UserRole, UserStatus } from '@prisma/client'; import { authService } from './auth.service'; import { loginSchema, registerSchema, refreshSchema } from './auth.schemas'; @@ -22,6 +23,9 @@ const router = Router(); const REFRESH_COOKIE_NAME = 'cml_refresh'; const REFRESH_COOKIE_MAX_AGE = 7 * 24 * 60 * 60 * 1000; // 7 days in ms +const SESSION_COOKIE_NAME = 'cml_session'; +const SESSION_COOKIE_MAX_AGE = 30 * 60 * 1000; // 30 min buffer (JWT inside enforces 15min expiry) + /** Set the refresh token as an httpOnly cookie. * Uses req.secure (respects trust proxy + X-Forwarded-Proto) to determine * the Secure flag, so it works correctly over both HTTP (dev) and HTTPS (tunnel). */ @@ -45,6 +49,53 @@ function clearRefreshCookie(req: Request, res: Response) { }); } +/** Cookie options for the SSO session cookie (domain-wide for Gitea reverse proxy auth) */ +function sessionCookieOptions(req: Request) { + const isSecure = req.secure; + const domain = env.DOMAIN; + // Use domain-wide cookie for production (subdomains); omit for localhost dev + const hasDomain = domain && !domain.includes('localhost') && !domain.match(/^\d/); + return { + httpOnly: true, + secure: isSecure, + sameSite: 'lax' as const, + path: '/', + maxAge: SESSION_COOKIE_MAX_AGE, + ...(hasDomain ? { domain: `.${domain}` } : {}), + }; +} + +/** Set the SSO session cookie for Gitea reverse proxy auth (fire-and-forget). + * Only sets the cookie if the user has a provisioned Gitea account. */ +async function setSessionCookie(req: Request, res: Response, userId: string) { + try { + const user = await prisma.user.findUnique({ + where: { id: userId }, + select: { permissions: true }, + }); + const permissions = (user?.permissions as Record) || {}; + const giteaUser = permissions._giteaUsername as string | undefined; + if (!giteaUser) return; // Not provisioned — skip + + const ssoSecret = env.GITEA_SSO_SECRET || env.JWT_ACCESS_SECRET; + const token = jwt.sign( + { sub: userId, giteaUser }, + ssoSecret, + { algorithm: 'HS256', expiresIn: '15m' }, + ); + res.cookie(SESSION_COOKIE_NAME, token, sessionCookieOptions(req)); + } catch (err) { + logger.debug('Failed to set SSO session cookie:', err); + } +} + +/** Clear the SSO session cookie */ +function clearSessionCookie(req: Request, res: Response) { + const opts = sessionCookieOptions(req); + delete (opts as Record).maxAge; + res.clearCookie(SESSION_COOKIE_NAME, opts); +} + // POST /api/auth/login router.post( '/login', @@ -55,6 +106,8 @@ router.post( const result = await authService.login(req.body.email, req.body.password); // Set refresh token as httpOnly cookie (not in response body) setRefreshCookie(req, res, result.refreshToken); + // Set SSO session cookie for Gitea reverse proxy auth + await setSessionCookie(req, res, result.user.id); const { refreshToken: _, ...responseWithoutRefresh } = result; res.json(responseWithoutRefresh); } catch (err) { @@ -281,6 +334,10 @@ router.post( const result = await authService.refreshTokens(refreshToken); // Set new refresh token as httpOnly cookie setRefreshCookie(req, res, result.refreshToken); + // Renew SSO session cookie for Gitea reverse proxy auth + if (result.user?.id) { + await setSessionCookie(req, res, result.user.id); + } const { refreshToken: _, ...responseWithoutRefresh } = result; res.json(responseWithoutRefresh); } catch (err) { @@ -302,9 +359,11 @@ router.post( await authService.logout(refreshToken); } clearRefreshCookie(req, res); + clearSessionCookie(req, res); res.json({ message: 'Logged out' }); } catch (err) { clearRefreshCookie(req, res); + clearSessionCookie(req, res); next(err); } } diff --git a/api/src/modules/auth/gitea-sso.routes.ts b/api/src/modules/auth/gitea-sso.routes.ts new file mode 100644 index 00000000..81680e61 --- /dev/null +++ b/api/src/modules/auth/gitea-sso.routes.ts @@ -0,0 +1,50 @@ +import { Router, Request, Response } from 'express'; +import jwt from 'jsonwebtoken'; +import { env } from '../../config/env'; +import { logger } from '../../utils/logger'; + +const router = Router(); + +interface SsoPayload { + sub: string; + giteaUser: string; +} + +/** + * GET /api/auth/gitea-sso-validate + * + * Called by nginx auth_request to validate the cml_session cookie. + * Always returns 200 — never blocks requests. + * Sets X-Gitea-User header when the session is valid and the user + * has a provisioned Gitea account. Empty header = no SSO (Gitea + * shows its own login page). + */ +router.get('/gitea-sso-validate', (req: Request, res: Response) => { + const token = req.cookies?.cml_session; + + if (!token) { + res.setHeader('X-Gitea-User', ''); + res.status(200).end(); + return; + } + + try { + const ssoSecret = env.GITEA_SSO_SECRET || env.JWT_ACCESS_SECRET; + const payload = jwt.verify(token, ssoSecret, { + algorithms: ['HS256'], + }) as SsoPayload; + + if (payload.giteaUser) { + res.setHeader('X-Gitea-User', payload.giteaUser); + } else { + res.setHeader('X-Gitea-User', ''); + } + } catch { + // Expired or invalid JWT — no SSO, graceful fallback + res.setHeader('X-Gitea-User', ''); + } + + res.status(200).end(); +}); + +export { router as giteaSsoRouter }; diff --git a/api/src/modules/calendar/shared-calendar.service.ts b/api/src/modules/calendar/shared-calendar.service.ts index 48db2994..09d60a69 100644 --- a/api/src/modules/calendar/shared-calendar.service.ts +++ b/api/src/modules/calendar/shared-calendar.service.ts @@ -925,7 +925,7 @@ export const sharedCalendarService = { include: { members: { where: { status: SharedViewMemberStatus.ACCEPTED }, - include: { user: { select: { id: true, name: true, email: true } } }, + include: { user: { select: { id: true, name: true } } }, }, }, }); @@ -972,7 +972,7 @@ export const sharedCalendarService = { orderBy: [{ date: 'asc' }, { startTime: 'asc' }], }); - const memberName = member.user.name || member.user.email; + const memberName = member.user.name || 'Member'; for (const item of items) { if (item.visibility === CalendarVisibility.PRIVATE || item.visibility === CalendarVisibility.FRIENDS) continue; allItems.push({ @@ -999,7 +999,7 @@ export const sharedCalendarService = { const sysLayers = filteredLayers.filter(l => l.layerType === CalendarLayerType.SYSTEM); for (const sysLayer of sysLayers) { const sysItems = await this.getSystemLayerItems(member.userId, sysLayer, start, end); - const memberName = member.user.name || member.user.email; + const memberName = member.user.name || 'Member'; for (const si of sysItems) { allItems.push({ ...si, diff --git a/api/src/modules/media/routes/photos-public.routes.ts b/api/src/modules/media/routes/photos-public.routes.ts index 3e520944..cb88b35f 100644 --- a/api/src/modules/media/routes/photos-public.routes.ts +++ b/api/src/modules/media/routes/photos-public.routes.ts @@ -1,6 +1,7 @@ import { FastifyInstance } from 'fastify'; import { createReadStream } from 'fs'; import { access } from 'fs/promises'; +import { resolve } from 'path'; import { prisma } from '../../../config/database'; import { optionalAuth } from '../middleware/auth'; import { logger } from '../../../utils/logger'; @@ -181,19 +182,25 @@ export async function photosPublicRoutes(fastify: FastifyInstance) { } } - if (!filePath || filePath.includes('..')) { + if (!filePath) { return reply.code(404).send({ message: 'Image variant not found' }); } + const PHOTOS_BASE = '/media/local/photos'; + const resolvedPath = resolve(filePath); + if (!resolvedPath.startsWith(resolve(PHOTOS_BASE) + '/')) { + logger.warn(`Photo path traversal attempt blocked: ${filePath}`); + return reply.code(403).send({ message: 'Access denied' }); + } try { - await access(filePath); + await access(resolvedPath); } catch { return reply.code(404).send({ message: 'Image file not found' }); } reply.header('Content-Type', contentType); reply.header('Cache-Control', 'public, max-age=604800, immutable'); - return reply.send(createReadStream(filePath)); + return reply.send(createReadStream(resolvedPath)); } ); @@ -208,19 +215,25 @@ export async function photosPublicRoutes(fastify: FastifyInstance) { select: { thumbnailPath: true }, }); - if (!photo?.thumbnailPath || photo.thumbnailPath.includes('..')) { + if (!photo?.thumbnailPath) { return reply.code(404).send({ message: 'Thumbnail not found' }); } + const PHOTOS_BASE = '/media/local/photos'; + const resolvedThumb = resolve(photo.thumbnailPath); + if (!resolvedThumb.startsWith(resolve(PHOTOS_BASE) + '/')) { + logger.warn(`Thumbnail path traversal attempt blocked: ${photo.thumbnailPath}`); + return reply.code(403).send({ message: 'Access denied' }); + } try { - await access(photo.thumbnailPath); + await access(resolvedThumb); } catch { return reply.code(404).send({ message: 'Thumbnail file not found' }); } reply.header('Content-Type', 'image/jpeg'); reply.header('Cache-Control', 'public, max-age=604800, immutable'); - return reply.send(createReadStream(photo.thumbnailPath)); + return reply.send(createReadStream(resolvedThumb)); } ); diff --git a/api/src/modules/meetings/action-items.routes.ts b/api/src/modules/meetings/action-items.routes.ts index 25ea4656..e456bdf8 100644 --- a/api/src/modules/meetings/action-items.routes.ts +++ b/api/src/modules/meetings/action-items.routes.ts @@ -8,7 +8,8 @@ import { import { validate } from '../../middleware/validate'; import { authenticate } from '../../middleware/auth.middleware'; import { requireRole } from '../../middleware/rbac.middleware'; -import { EVENTS_ROLES } from '../../utils/roles'; +import { EVENTS_ROLES, hasAnyRole } from '../../utils/roles'; +import { AppError } from '../../middleware/error-handler'; const router = Router(); @@ -44,6 +45,14 @@ router.get('/:id', authenticate, async (req: Request, res: Response, next: NextF try { const id = req.params.id as string; const item = await actionItemsService.findById(id); + + const isAdmin = hasAnyRole(req.user!, EVENTS_ROLES); + const isAssignee = item.assigneeUserId === req.user!.id; + const isCreator = item.createdByUserId === req.user!.id; + if (!isAdmin && !isAssignee && !isCreator) { + throw new AppError(403, 'Insufficient permissions', 'FORBIDDEN'); + } + res.json(item); } catch (err) { next(err); } }); @@ -56,10 +65,19 @@ router.post('/', authenticate, requireRole(...EVENTS_ROLES), validate(createActi } catch (err) { next(err); } }); -// Update action item (authenticate only - assignees can update their own) +// Update action item — admins, assignees, or creators can update router.put('/:id', authenticate, validate(updateActionItemSchema), async (req: Request, res: Response, next: NextFunction) => { try { const id = req.params.id as string; + const existing = await actionItemsService.findById(id); + + const isAdmin = hasAnyRole(req.user!, EVENTS_ROLES); + const isAssignee = existing.assigneeUserId === req.user!.id; + const isCreator = existing.createdByUserId === req.user!.id; + if (!isAdmin && !isAssignee && !isCreator) { + throw new AppError(403, 'Insufficient permissions', 'FORBIDDEN'); + } + const item = await actionItemsService.update(id, req.body); res.json(item); } catch (err) { next(err); } diff --git a/api/src/modules/sms/contacts/sms-contacts.routes.ts b/api/src/modules/sms/contacts/sms-contacts.routes.ts index 5ddc6e50..d94cf7bd 100644 --- a/api/src/modules/sms/contacts/sms-contacts.routes.ts +++ b/api/src/modules/sms/contacts/sms-contacts.routes.ts @@ -171,6 +171,11 @@ router.post('/:id/import-csv', async (req, res, next) => { res.status(400).json({ error: 'CSV text is required in the "csv" field' }); return; } + const MAX_CSV_SIZE = 5 * 1024 * 1024; // 5MB + if (csv.length > MAX_CSV_SIZE) { + res.status(400).json({ error: { message: 'CSV too large (max 5MB)', code: 'CSV_TOO_LARGE' } }); + return; + } const result = await smsContactsService.importCsv(req.params.id as string, csv, filename); res.json(result); } catch (err) { next(err); } diff --git a/api/src/modules/ticketed-events/ticketed-events-admin.routes.ts b/api/src/modules/ticketed-events/ticketed-events-admin.routes.ts index 21f34e8f..04c13e94 100644 --- a/api/src/modules/ticketed-events/ticketed-events-admin.routes.ts +++ b/api/src/modules/ticketed-events/ticketed-events-admin.routes.ts @@ -39,6 +39,30 @@ async function requireEventPermission(req: Request, _res: Response, next: NextFu return next({ status: 403, message: 'Insufficient permissions' }); } +/** Middleware: for :id routes, verify non-admin users own the event */ +async function requireEventOwnership(req: Request, res: Response, next: NextFunction) { + const eventId = req.params.id as string; + if (!eventId) return next(); + + const userRoles = req.user!.roles || [req.user!.role]; + const isAdmin = userRoles.some(r => EVENTS_ROLES.includes(r as UserRole)); + if (isAdmin) return next(); + + const event = await prisma.ticketedEvent.findUnique({ + where: { id: eventId }, + select: { createdByUserId: true }, + }); + if (!event) { + res.status(404).json({ error: { message: 'Event not found', code: 'NOT_FOUND' } }); + return; + } + if (event.createdByUserId !== req.user!.id) { + res.status(403).json({ error: { message: 'Forbidden', code: 'FORBIDDEN' } }); + return; + } + next(); +} + // All routes require auth + event permission router.use(authenticate, requireEventPermission); @@ -73,7 +97,7 @@ router.post('/', validate(createEventSchema), async (req: Request, res: Response }); // GET /:id — event detail -router.get('/:id', async (req: Request, res: Response, next: NextFunction) => { +router.get('/:id', requireEventOwnership, async (req: Request, res: Response, next: NextFunction) => { try { const event = await ticketedEventsService.findById(req.params.id as string); res.json(event); @@ -144,7 +168,7 @@ router.post('/:id/complete', requireRole(...EVENTS_ROLES), async (req: Request, // --- Meeting --- // POST /:id/meeting-token — generate moderator JWT for Jitsi -router.post('/:id/meeting-token', async (req: Request, res: Response, next: NextFunction) => { +router.post('/:id/meeting-token', requireEventOwnership, async (req: Request, res: Response, next: NextFunction) => { try { const user = await prisma.user.findUnique({ where: { id: req.user!.id }, @@ -159,7 +183,7 @@ router.post('/:id/meeting-token', async (req: Request, res: Response, next: Next // --- Tiers --- // POST /:id/tiers -router.post('/:id/tiers', validate(createTierSchema), async (req: Request, res: Response, next: NextFunction) => { +router.post('/:id/tiers', requireEventOwnership, validate(createTierSchema), async (req: Request, res: Response, next: NextFunction) => { try { const tier = await ticketedEventsService.addTier(req.params.id as string, req.body); res.status(201).json(tier); @@ -167,7 +191,7 @@ router.post('/:id/tiers', validate(createTierSchema), async (req: Request, res: }); // PUT /:id/tiers/:tierId -router.put('/:id/tiers/:tierId', validate(updateTierSchema), async (req: Request, res: Response, next: NextFunction) => { +router.put('/:id/tiers/:tierId', requireEventOwnership, validate(updateTierSchema), async (req: Request, res: Response, next: NextFunction) => { try { const tier = await ticketedEventsService.updateTier( req.params.tierId as string, @@ -179,7 +203,7 @@ router.put('/:id/tiers/:tierId', validate(updateTierSchema), async (req: Request }); // DELETE /:id/tiers/:tierId -router.delete('/:id/tiers/:tierId', async (req: Request, res: Response, next: NextFunction) => { +router.delete('/:id/tiers/:tierId', requireEventOwnership, async (req: Request, res: Response, next: NextFunction) => { try { await ticketedEventsService.deleteTier(req.params.tierId as string, req.params.id as string); res.json({ success: true }); @@ -189,7 +213,7 @@ router.delete('/:id/tiers/:tierId', async (req: Request, res: Response, next: Ne // --- Tickets --- // GET /:id/tickets -router.get('/:id/tickets', async (req: Request, res: Response, next: NextFunction) => { +router.get('/:id/tickets', requireEventOwnership, async (req: Request, res: Response, next: NextFunction) => { try { const page = parseInt(req.query.page as string) || 1; const limit = Math.min(parseInt(req.query.limit as string) || 20, 100); @@ -201,7 +225,7 @@ router.get('/:id/tickets', async (req: Request, res: Response, next: NextFunctio }); // GET /:id/checkins -router.get('/:id/checkins', async (req: Request, res: Response, next: NextFunction) => { +router.get('/:id/checkins', requireEventOwnership, async (req: Request, res: Response, next: NextFunction) => { try { const page = parseInt(req.query.page as string) || 1; const limit = Math.min(parseInt(req.query.limit as string) || 20, 100); @@ -211,7 +235,7 @@ router.get('/:id/checkins', async (req: Request, res: Response, next: NextFuncti }); // GET /:id/stats -router.get('/:id/stats', async (req: Request, res: Response, next: NextFunction) => { +router.get('/:id/stats', requireEventOwnership, async (req: Request, res: Response, next: NextFunction) => { try { const stats = await ticketedEventsService.getEventStats(req.params.id as string); res.json(stats); @@ -219,7 +243,7 @@ router.get('/:id/stats', async (req: Request, res: Response, next: NextFunction) }); // POST /:id/resend-ticket/:ticketId -router.post('/:id/resend-ticket/:ticketId', async (req: Request, res: Response, next: NextFunction) => { +router.post('/:id/resend-ticket/:ticketId', requireEventOwnership, async (req: Request, res: Response, next: NextFunction) => { try { const ticket = await prisma.ticket.findUnique({ where: { id: req.params.ticketId as string }, @@ -273,7 +297,7 @@ router.post('/:id/resend-ticket/:ticketId', async (req: Request, res: Response, }); // POST /:id/tickets/:ticketId/cancel -router.post('/:id/tickets/:ticketId/cancel', async (req: Request, res: Response, next: NextFunction) => { +router.post('/:id/tickets/:ticketId/cancel', requireEventOwnership, async (req: Request, res: Response, next: NextFunction) => { try { await ticketsService.cancelTicket(req.params.ticketId as string); res.json({ success: true }); diff --git a/api/src/services/gitea.client.ts b/api/src/services/gitea.client.ts index 3606fd66..1c2d51b4 100644 --- a/api/src/services/gitea.client.ts +++ b/api/src/services/gitea.client.ts @@ -599,6 +599,51 @@ class GiteaClient { { name: tokenName, scopes: ['read', 'write'] as unknown as Record } as unknown as Record, ); } + + // --- Repository Collaborator Management --- + + /** + * Add a collaborator to a repository with the specified permission level. + * @param permission - "read", "write", or "admin" + */ + async addCollaborator( + owner: string, + repo: string, + username: string, + permission: 'read' | 'write' | 'admin' = 'write', + ): Promise { + await this.request( + 'PUT', + `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/collaborators/${encodeURIComponent(username)}`, + { permission }, + ); + } + + /** + * Remove a collaborator from a repository. + */ + async removeCollaborator(owner: string, repo: string, username: string): Promise { + await this.request( + 'DELETE', + `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/collaborators/${encodeURIComponent(username)}`, + ); + } + + /** + * Check if a user is a collaborator on a repository. + * Returns true if they are, false otherwise. + */ + async isCollaborator(owner: string, repo: string, username: string): Promise { + try { + await this.request( + 'GET', + `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/collaborators/${encodeURIComponent(username)}`, + ); + return true; + } catch { + return false; + } + } } export const giteaClient = new GiteaClient(); diff --git a/api/src/services/user-provisioning/gitea.provisioner.ts b/api/src/services/user-provisioning/gitea.provisioner.ts index f10de915..137b83ac 100644 --- a/api/src/services/user-provisioning/gitea.provisioner.ts +++ b/api/src/services/user-provisioning/gitea.provisioner.ts @@ -1,9 +1,10 @@ import { createHmac } from 'crypto'; -import { Prisma } from '@prisma/client'; +import { Prisma, UserRole } from '@prisma/client'; import { prisma } from '../../config/database'; import { env } from '../../config/env'; import { logger } from '../../utils/logger'; import { giteaClient } from '../gitea.client'; +import { CONTENT_ROLES } from '../../utils/roles'; import type { ServiceProvisioner, ProvisionerConfig, ProvisionResult, CMUser } from './provisioner.interface'; const ROLE_MAP: Record = { @@ -14,9 +15,13 @@ const ROLE_MAP: Record = { TEMP: [], }; +/** The private docs repo name created by gitea-setup */ +const DOCS_REPO_NAME = 'changemaker.lite'; + /** Deterministic password — never exposed to users */ function generateGiteaPassword(userId: string): string { - return createHmac('sha256', env.JWT_ACCESS_SECRET) + const salt = env.SERVICE_PASSWORD_SALT || env.JWT_ACCESS_SECRET; + return createHmac('sha256', salt) .update(`gitea:${userId}`) .digest('hex'); } @@ -94,6 +99,9 @@ class GiteaProvisioner implements ServiceProvisioner { }, }); + // Grant docs repo access based on role + await this.syncDocsRepoAccess(giteaUser.login, user.role); + return { success: true, serviceUserId: String(giteaUser.id), @@ -121,6 +129,9 @@ class GiteaProvisioner implements ServiceProvisioner { admin: isAdmin, active: user.status === 'ACTIVE', }); + + // Re-evaluate docs repo access based on current role + await this.syncDocsRepoAccess(username, user.role); } async deactivate(serviceUserId: string): Promise { @@ -140,13 +151,57 @@ class GiteaProvisioner implements ServiceProvisioner { } await giteaClient.adminUpdateUser(username, { active: false }); + + // Remove docs repo collaborator access + try { + const config = await giteaClient.getConfig(); + if (config.repoOwner) { + await giteaClient.removeCollaborator(config.repoOwner, DOCS_REPO_NAME, username); + } + } catch { + // Ignore — user may not have been a collaborator + } + logger.info(`Gitea provisioner: deactivated user ${username}`); } async getAuthToken(_user: CMUser, _serviceUserId: string): Promise { - // Gitea SSO via API tokens could be implemented here if needed for iframe embedding return null; } + + /** + * Ensure the user's collaborator status on the private docs repo matches + * their role. CONTENT_ROLES (SUPER_ADMIN, CONTENT_ADMIN) get write access; + * SUPER_ADMIN users already have admin access via the Gitea admin flag, + * but we also add them as explicit collaborators for consistency. + * Users without CONTENT_ROLES are removed as collaborators. + */ + private async syncDocsRepoAccess(username: string, role: string): Promise { + try { + const config = await giteaClient.getConfig(); + const repoOwner = config.repoOwner; + if (!repoOwner) return; // Setup not complete — no repo owner yet + + const hasDocsAccess = CONTENT_ROLES.includes(role as UserRole); + + if (hasDocsAccess) { + // SUPER_ADMIN → admin, CONTENT_ADMIN → write + const permission = role === 'SUPER_ADMIN' ? 'admin' : 'write'; + await giteaClient.addCollaborator(repoOwner, DOCS_REPO_NAME, username, permission); + logger.debug(`Gitea provisioner: granted ${permission} access to ${repoOwner}/${DOCS_REPO_NAME} for ${username}`); + } else { + // Remove access if user no longer has CONTENT_ROLES + const isCollab = await giteaClient.isCollaborator(repoOwner, DOCS_REPO_NAME, username); + if (isCollab) { + await giteaClient.removeCollaborator(repoOwner, DOCS_REPO_NAME, username); + logger.debug(`Gitea provisioner: removed ${username} from ${repoOwner}/${DOCS_REPO_NAME}`); + } + } + } catch (err) { + // Non-fatal — don't block provisioning if repo access sync fails + logger.warn(`Gitea provisioner: docs repo access sync failed for ${username}:`, err instanceof Error ? err.message : err); + } + } } export const giteaProvisioner = new GiteaProvisioner(); diff --git a/api/src/services/user-provisioning/rocketchat.provisioner.ts b/api/src/services/user-provisioning/rocketchat.provisioner.ts index 58368ade..a44811c2 100644 --- a/api/src/services/user-provisioning/rocketchat.provisioner.ts +++ b/api/src/services/user-provisioning/rocketchat.provisioner.ts @@ -16,7 +16,8 @@ const ROLE_MAP: Record = { /** Deterministic password — never exposed to users, only used for RC internal auth */ function generateRCPassword(userId: string): string { - return createHmac('sha256', env.JWT_ACCESS_SECRET) + const salt = env.SERVICE_PASSWORD_SALT || env.JWT_ACCESS_SECRET; + return createHmac('sha256', salt) .update(`rc:${userId}`) .digest('hex'); } diff --git a/changemaker-control-panel/templates/docker-compose.yml.hbs b/changemaker-control-panel/templates/docker-compose.yml.hbs index 1ad65268..0803b727 100644 --- a/changemaker-control-panel/templates/docker-compose.yml.hbs +++ b/changemaker-control-panel/templates/docker-compose.yml.hbs @@ -746,6 +746,12 @@ services: GITEA__attachment__MAX_SIZE: "1024" GITEA__repository__MAX_CREATION_LIMIT: "-1" GITEA__server__LFS_START_SERVER: "true" + # Reverse proxy auth — nginx injects X-WEBAUTH-USER for SSO + GITEA__service__ENABLE_REVERSE_PROXY_AUTHENTICATION: "true" + GITEA__service__ENABLE_REVERSE_PROXY_AUTO_REGISTRATION: "false" + GITEA__service__ENABLE_REVERSE_PROXY_EMAIL: "false" + GITEA__service__REVERSE_PROXY_AUTHENTICATION_HEADER: "X-WEBAUTH-USER" + GITEA__service__REQUIRE_SIGNIN_VIEW: "true" volumes: - {{containerPrefix}}-gitea-data:/data networks: diff --git a/changemaker-control-panel/templates/nginx/conf.d/services.conf.hbs b/changemaker-control-panel/templates/nginx/conf.d/services.conf.hbs index 1c7eb583..2ee573e1 100644 --- a/changemaker-control-panel/templates/nginx/conf.d/services.conf.hbs +++ b/changemaker-control-panel/templates/nginx/conf.d/services.conf.hbs @@ -35,19 +35,36 @@ server { } } -# Gitea embed proxy (internal 8883) +# Gitea embed proxy (internal 8883) — SSO via auth_request server { listen 8883; client_max_body_size 2048M; + + # Internal: validate SSO session cookie via API + location = /_auth { + internal; + set $upstream_api http://{{containerPrefix}}-api:4000; + proxy_pass $upstream_api/api/auth/gitea-sso-validate; + proxy_pass_request_body off; + proxy_set_header Content-Length ""; + proxy_set_header Cookie $http_cookie; + } + location / { + auth_request /_auth; + auth_request_set $gitea_user $upstream_http_x_gitea_user; + set $upstream_gitea http://{{containerPrefix}}-gitea:3000; proxy_pass $upstream_gitea; proxy_hide_header X-Frame-Options; proxy_hide_header Content-Security-Policy; + add_header Content-Security-Policy "frame-ancestors 'self' localhost 127.0.0.1" always; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; + # SSO header — empty string if not authenticated (Gitea ignores it) + proxy_set_header X-WEBAUTH-USER $gitea_user; } } diff --git a/docker-compose.prod.yml b/docker-compose.prod.yml index f6027971..bfbae89f 100644 --- a/docker-compose.prod.yml +++ b/docker-compose.prod.yml @@ -32,7 +32,7 @@ services: retries: 3 start_period: 30s environment: - - NODE_ENV=${NODE_ENV:-development} + - NODE_ENV=${NODE_ENV:-production} - PORT=4000 - LOG_DIR=/app/logs - DATABASE_URL=postgresql://${V2_POSTGRES_USER:-changemaker}:${V2_POSTGRES_PASSWORD:?V2_POSTGRES_PASSWORD must be set in .env}@changemaker-v2-postgres:5432/${V2_POSTGRES_DB:-changemaker_v2} @@ -155,7 +155,7 @@ services: retries: 3 start_period: 30s environment: - - NODE_ENV=${NODE_ENV:-development} + - NODE_ENV=${NODE_ENV:-production} - MEDIA_API_PORT=${MEDIA_API_PORT:-4100} - DATABASE_URL=postgresql://${V2_POSTGRES_USER:-changemaker}:${V2_POSTGRES_PASSWORD:?V2_POSTGRES_PASSWORD must be set in .env}@changemaker-v2-postgres:5432/${V2_POSTGRES_DB:-changemaker_v2} - REDIS_URL=redis://:${REDIS_PASSWORD}@redis-changemaker:6379 @@ -204,7 +204,7 @@ services: start_period: 20s environment: - DOMAIN=${DOMAIN:-cmlite.org} - - NODE_ENV=${NODE_ENV:-development} + - NODE_ENV=${NODE_ENV:-production} - VITE_API_URL=http://changemaker-v2-api:4000 - VITE_MEDIA_API_URL=${VITE_MEDIA_API_URL:-http://changemaker-media-api:4100} - VITE_MKDOCS_URL=http://mkdocs-changemaker:8000 @@ -665,6 +665,12 @@ services: - GITEA__server__LFS_MAX_FILE_SIZE=1024 - GITEA__repository__upload__FILE_MAX_SIZE=1024 - GITEA__repository__upload__MAX_FILES=1000 + # Reverse proxy auth — nginx injects X-WEBAUTH-USER for SSO + - GITEA__service__ENABLE_REVERSE_PROXY_AUTHENTICATION=true + - GITEA__service__ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=false + - GITEA__service__ENABLE_REVERSE_PROXY_EMAIL=false + - GITEA__service__REVERSE_PROXY_AUTHENTICATION_HEADER=X-WEBAUTH-USER + - GITEA__service__REQUIRE_SIGNIN_VIEW=true restart: unless-stopped volumes: - gitea-data:/data @@ -1191,7 +1197,7 @@ services: - GF_USERS_ALLOW_SIGN_UP=false - GF_SERVER_ROOT_URL=${GRAFANA_ROOT_URL:-http://localhost:3001} - GF_SECURITY_ALLOW_EMBEDDING=true - - GF_AUTH_ANONYMOUS_ENABLED=true + - GF_AUTH_ANONYMOUS_ENABLED=false - GF_AUTH_ANONYMOUS_ORG_ROLE=Viewer volumes: - grafana-data:/var/lib/grafana diff --git a/mkdocs/.cache/plugin/social/assets/images/social/blog/2026/03/27/test-blog-post---version-3.png b/mkdocs/.cache/plugin/social/assets/images/social/blog/2026/03/27/test-blog-post---version-3.png new file mode 100644 index 00000000..64526dfe Binary files /dev/null and b/mkdocs/.cache/plugin/social/assets/images/social/blog/2026/03/27/test-blog-post---version-3.png differ diff --git a/mkdocs/.cache/plugin/social/assets/images/social/blog/2026/03/27/test-blog-post---version-4.png b/mkdocs/.cache/plugin/social/assets/images/social/blog/2026/03/27/test-blog-post---version-4.png new file mode 100644 index 00000000..baf6ef4c Binary files /dev/null and b/mkdocs/.cache/plugin/social/assets/images/social/blog/2026/03/27/test-blog-post---version-4.png differ diff --git a/mkdocs/.cache/plugin/social/assets/images/social/blog/2026/03/27/test-blog-post---version-5.png b/mkdocs/.cache/plugin/social/assets/images/social/blog/2026/03/27/test-blog-post---version-5.png new file mode 100644 index 00000000..b89e089c Binary files /dev/null and b/mkdocs/.cache/plugin/social/assets/images/social/blog/2026/03/27/test-blog-post---version-5.png differ diff --git a/mkdocs/.cache/plugin/social/assets/images/social/blog/2026/03/27/test-blog-post---version-6.png b/mkdocs/.cache/plugin/social/assets/images/social/blog/2026/03/27/test-blog-post---version-6.png new file mode 100644 index 00000000..4bfeb880 Binary files /dev/null and b/mkdocs/.cache/plugin/social/assets/images/social/blog/2026/03/27/test-blog-post---version-6.png differ diff --git a/mkdocs/.cache/plugin/social/assets/images/social/blog/2026/03/27/test-blog-post---version-7.png b/mkdocs/.cache/plugin/social/assets/images/social/blog/2026/03/27/test-blog-post---version-7.png new file mode 100644 index 00000000..06d3f3f6 Binary files /dev/null and b/mkdocs/.cache/plugin/social/assets/images/social/blog/2026/03/27/test-blog-post---version-7.png differ diff --git a/mkdocs/.cache/plugin/social/assets/images/social/blog/2026/03/27/test-blog-post.png b/mkdocs/.cache/plugin/social/assets/images/social/blog/2026/03/27/test-blog-post.png new file mode 100644 index 00000000..2534f7ea Binary files /dev/null and b/mkdocs/.cache/plugin/social/assets/images/social/blog/2026/03/27/test-blog-post.png differ diff --git a/mkdocs/.cache/plugin/social/assets/images/social/blog/category/testing.png b/mkdocs/.cache/plugin/social/assets/images/social/blog/category/testing.png new file mode 100644 index 00000000..c6d22b02 Binary files /dev/null and b/mkdocs/.cache/plugin/social/assets/images/social/blog/category/testing.png differ diff --git a/mkdocs/.cache/plugin/social/assets/images/social/getting-started.png b/mkdocs/.cache/plugin/social/assets/images/social/getting-started.png new file mode 100644 index 00000000..06a2960b Binary files /dev/null and b/mkdocs/.cache/plugin/social/assets/images/social/getting-started.png differ diff --git a/mkdocs/.cache/plugin/social/assets/images/social/test.png b/mkdocs/.cache/plugin/social/assets/images/social/test.png index 06fed73c..47fa3e3c 100644 Binary files a/mkdocs/.cache/plugin/social/assets/images/social/test.png and b/mkdocs/.cache/plugin/social/assets/images/social/test.png differ diff --git a/mkdocs/.cache/plugin/social/manifest.json b/mkdocs/.cache/plugin/social/manifest.json index bb836ceb..b6127e6a 100644 --- a/mkdocs/.cache/plugin/social/manifest.json +++ b/mkdocs/.cache/plugin/social/manifest.json @@ -9,10 +9,17 @@ "assets/images/social/blog/2025/08/01/3.png": "332b80224e75bda48c92439ad6354e7ffcab52e1", "assets/images/social/blog/2025/09/24/4.png": "840234a707ac182ce6b89203c658b312d03df58e", "assets/images/social/blog/2026/03/22/introducing-changemaker-lite-v2.png": "c79afe23671a3a829e74debe1f3dc23f21d7100f", + "assets/images/social/blog/2026/03/27/test-blog-post---version-3.png": "7fce7e67d83b63b507be00e7ded540dfa7bd0ed5", + "assets/images/social/blog/2026/03/27/test-blog-post---version-4.png": "98cffc754c5be0c9b153444df46ed5b8b4350290", + "assets/images/social/blog/2026/03/27/test-blog-post---version-5.png": "74ac268b9766c50b397e5b02513661d6abe8ebaf", + "assets/images/social/blog/2026/03/27/test-blog-post---version-6.png": "c6d68bac2cdcd6b8c52256df35d542be64de7e0e", + "assets/images/social/blog/2026/03/27/test-blog-post---version-7.png": "f6cc4e78350bbf53560dbc4f119596592fe597c1", + "assets/images/social/blog/2026/03/27/test-blog-post.png": "fd4dfc0ab942b7d648409d37b344d50e348150c7", "assets/images/social/blog/archive/2025.png": "08cbed159d450158ab4d79807f37adcda08bce39", "assets/images/social/blog/archive/2026.png": "e13e604d5c2f61d08e8d14b4442ac65c268424b8", "assets/images/social/blog/category/announcements.png": "096d6368b08dfd41a79a91e7e0fbfdc3bfd32a1b", "assets/images/social/blog/category/platform.png": "036ba6414ed31d34d59423289658a3accefa76c0", + "assets/images/social/blog/category/testing.png": "53d1c9283a3557e3213d9c8cc28a2aa6d6824ce5", "assets/images/social/blog/index.png": "b6fe388cb026572dfa0f42b9a6833e9fa9f95b9e", "assets/images/social/build/index.png": "30e75040da55694ca6485d51a35fb4d19a26b408", "assets/images/social/build/influence.png": "2961db1abb5f36d53086bf2bde9dfe19f1487809", @@ -151,7 +158,7 @@ "assets/images/social/services/static-server.png": "f36d527c80adba4bcb7778784683f429acb4ce74", "assets/images/social/test-2.png": "a6ae43d52d7c58fc106a562777e03b7da2263f83", "assets/images/social/test-page.png": "c9d5751a1f0a4c1341336bb7d00c9bc743d33ef4", - "assets/images/social/test.png": "a6ae43d52d7c58fc106a562777e03b7da2263f83", + "assets/images/social/test.png": "18d63169d742e6321dc4bb2988b8c5de61e79a28", "assets/images/social/testing.png": "f7aaf394b71cbe7084a6afa0e75a324ca59e23d8", "assets/images/social/v1/adv/ansible.png": "cb542ad9a3cc9a869258b3b1353966e1b9616a2b", "assets/images/social/v1/adv/index.png": "faa3ec092003114c031995ba6258c4d43f4262a4", diff --git a/mkdocs/DOCS_NEXT_STEPS.md b/mkdocs/DOCS_NEXT_STEPS.md deleted file mode 100644 index 6b0547c6..00000000 --- a/mkdocs/DOCS_NEXT_STEPS.md +++ /dev/null @@ -1,305 +0,0 @@ -# Documentation Next Steps — Editorial & Material Theme Enhancement Plan - -**Date:** 2026-03-22 -**Branch:** v2 -**Status:** Planning → Execution - ---- - -## Executive Summary - -The MkDocs documentation site is comprehensive (70+ pages, all with proper frontmatter, no stubs) and already uses many Material theme features well (grid cards, admonitions, code copy, mermaid diagrams, social cards, blog plugin, dark/light toggle). This plan focuses on **activating dormant Material theme capabilities** and **editorial polish** to take the docs from "complete" to "professional-grade." - ---- - -## Step 1: mkdocs.yml Configuration Hardening - -**Goal:** Enable Material theme features that are available but not configured. - -### 1a. Add missing theme features -```yaml -features: - # Already enabled (keep): - - announce.dismiss - - content.action.edit - - content.action.view - - content.code.annotate - - content.code.copy - - content.tooltips - - navigation.footer - - navigation.indexes - - navigation.path - - navigation.prune - - navigation.tabs - - navigation.tabs.sticky - - navigation.top - - navigation.tracking - - search.highlight - - search.share - - search.suggest - - toc.follow - - # ADD these: - - navigation.instant # SPA-like navigation (no full page reload) - - navigation.instant.prefetch # Prefetch pages on hover - - navigation.instant.progress # Show loading progress bar - - content.code.select # Line selection in code blocks - - content.tabs.link # Linked content tabs (sync across page) -``` - -### 1b. Fix consent banner -The copyright references `#__consent` but no consent config exists. Add: -```yaml -extra: - consent: - title: Cookie consent - description: > - We use cookies to recognize your repeated visits and preferences, - as well as to measure the effectiveness of our documentation. - With your consent, you help us improve. - actions: - - accept - - reject - - manage -``` - -### 1c. Fix copyright year -Change `2024` → `2024–2026` in the copyright line. - -### 1d. Fix edit_uri branch -Change `edit_uri: src/branch/main/mkdocs/docs` → `edit_uri: src/branch/v2/mkdocs/docs` - -### 1e. Add abbreviations snippets -Create `docs/includes/abbreviations.md` and reference via snippets: -```yaml -markdown_extensions: - - pymdownx.snippets: - auto_append: - - includes/abbreviations.md -``` - -Common abbreviations: API, JWT, RBAC, CSV, ORM, SMTP, CORS, SSL, TLS, DNS, CRUD, SSO, SPA, CLI, GUI, QR, GPS, GDPR, CDN, VPS, CGNAT, NAR, CRM, OG, DDoS, SSE, UUID, FOSS, HSTS, CSP - -### 1f. Add privacy plugin (optional, external resource proxying) -```yaml -plugins: - - privacy -``` - ---- - -## Step 2: Page-Level Metadata Enhancement - -**Goal:** Add `tags`, `status`, and `search.boost` metadata to every page. - -### 2a. Tags -The tags plugin is loaded but zero pages use tags. Add contextually appropriate tags to every page. Example tag taxonomy: - -- **Audience:** `admin`, `volunteer`, `user`, `operator`, `developer` -- **Module:** `influence`, `map`, `media`, `payments`, `broadcast`, `social` -- **Type:** `guide`, `reference`, `tutorial`, `concept`, `troubleshooting` -- **Feature:** `campaigns`, `canvassing`, `shifts`, `gallery`, `landing-pages`, `newsletter`, `sms`, `chat`, `events` - -### 2b. Status badges -Material supports `status: new` and `status: deprecated` on pages, shown as badges in the nav sidebar. Apply: -- `status: new` — Recent features (Gallery Ads, People CRM, Achievements, Social Calendar, CrowdSec, SMS, Docs Comments, Payments) -- `status: deprecated` — Legacy/archival content if any - -Requires adding to `extra:` in mkdocs.yml: -```yaml -extra: - status: - new: Recently added - deprecated: Legacy -``` - -### 2c. Search boost -Boost important entry-point pages so they rank higher: -```yaml ---- -search: - boost: 2 ---- -``` -Apply to: Getting Started index, Installation, First Steps, Features at a Glance, FAQ/Troubleshooting. - ---- - -## Step 3: Abbreviations Glossary - -**Goal:** Create a shared abbreviations file so that hovering over acronyms shows their meaning. - -Create `mkdocs/docs/includes/abbreviations.md`: -```markdown -*[API]: Application Programming Interface -*[JWT]: JSON Web Token -*[RBAC]: Role-Based Access Control -*[CORS]: Cross-Origin Resource Sharing -*[SMTP]: Simple Mail Transfer Protocol -*[CSV]: Comma-Separated Values -*[ORM]: Object-Relational Mapping -*[SSL]: Secure Sockets Layer -*[TLS]: Transport Layer Security -*[DNS]: Domain Name System -*[CRUD]: Create, Read, Update, Delete -*[SSO]: Single Sign-On -*[SPA]: Single Page Application -*[CLI]: Command Line Interface -*[GUI]: Graphical User Interface -*[QR]: Quick Response (code) -*[GPS]: Global Positioning System -*[GDPR]: General Data Protection Regulation -*[CDN]: Content Delivery Network -*[VPS]: Virtual Private Server -*[CGNAT]: Carrier-Grade Network Address Translation -*[NAR]: National Address Register -*[CRM]: Customer Relationship Management -*[OG]: Open Graph -*[DDoS]: Distributed Denial of Service -*[SSE]: Server-Sent Events -*[UUID]: Universally Unique Identifier -*[FOSS]: Free and Open Source Software -*[HSTS]: HTTP Strict Transport Security -*[CSP]: Content Security Policy -*[BullMQ]: Bull Message Queue -*[FFprobe]: FFmpeg Probe (media metadata tool) -*[FFmpeg]: Fast Forward Moving Picture Experts Group -*[XMPP]: Extensible Messaging and Presence Protocol -``` - ---- - -## Step 4: Custom 404 Page - -**Goal:** Branded 404 page instead of browser default. - -Create `mkdocs/docs/404.md`: -```markdown ---- -template: main.html -title: Page Not Found -hide: - - navigation - - toc - - footer -search: - exclude: true ---- - -# Page Not Found - -The page you're looking for doesn't exist or has been moved. - -[Go to Documentation Home](docs/index.md){ .md-button .md-button--primary } -[Search](docs/index.md){ .md-button } -``` - ---- - -## Step 5: Content Fixes — Broken Links & Stale Warnings - -**Goal:** Fix all broken links, placeholder content, and stale warnings. - -### 5a. Fix broken "Coming soon" links -- `docs/index.md`: Monitoring card links to `../blog/index.md` → link to `admin/services/monitoring.md` -- `docs/index.md`: Contributing card links to `../blog/index.md` → create a contributing stub or remove placeholder - -### 5b. Fix Architecture page -Remove "Under Construction" admonition. Flesh out with: -- Mermaid system diagram -- Database entity relationship summary -- Authentication flow (already started) -- Request lifecycle - -### 5c. Fix Troubleshooting page -Remove "Under Construction" admonition. Add more entries from CLAUDE.md and production experience. - -### 5d. Fix Admin Guide roles table -Only lists 5 roles but there are 11. Add missing roles: -BROADCAST_ADMIN, CONTENT_ADMIN, MEDIA_ADMIN, PAYMENTS_ADMIN, EVENTS_ADMIN, SOCIAL_ADMIN - -### 5e. Social icons semantic fix -GitHub icon links to Gitea — change icon to `fontawesome/brands/gitea` or `simple/gitea` if available, or use a generic `fontawesome/solid/code-branch`. - ---- - -## Step 6: Cleanup Test/Orphan Files - -**Goal:** Remove files that shouldn't be in the docs directory. - -- `docs/test.md` (41KB test file) -- `docs/test-page.md` -- `docs/testing.md` -- `docs/lander.md` (override template pointer — keep if used by index.md) -- `docs/main.md` (override template pointer — keep if used) - -Verify `lander.md` and `main.md` are still needed by checking if any page uses `template: lander.html` or `template: main.html`. - ---- - -## Step 7: Announcement Bar - -**Goal:** Use Material's announcement bar for version/status info. - -Create `mkdocs/docs/overrides/main.html` addition (or modify existing) with announcement block: -```html -{% block announce %} - Changemaker Lite v2 — Get started in 5 minutes -{% endblock %} -``` - -Note: The existing `main.html` override is 35KB — check if it already has an announce block before modifying. - ---- - -## Step 8: Blog Seeding - -**Goal:** Create 1–2 initial blog posts so the blog section isn't empty. - -Suggested posts: -1. **"Introducing Changemaker Lite v2"** — Overview of the rebuild, what's new, philosophy -2. **"Why Self-Hosted Campaign Tools Matter in 2026"** — Draws from the Philosophy page - ---- - -## Step 9: Screenshot Audit - -**Goal:** Verify all `![...](../../assets/images/screenshots/...)` references resolve to actual files. Take new screenshots with Playwright where missing or outdated. - -Pages referencing screenshots: -- Getting Started index (dashboard.png) -- First Steps (login.png, dashboard.png, settings-organization.png, campaigns.png, locations.png, shifts.png) -- Dashboard (dashboard.png) -- People & Access (users.png) -- Settings (settings.png) -- Campaigns (campaigns.png) - ---- - -## Priority Order - -| Priority | Step | Impact | Effort | -|----------|------|--------|--------| -| **P0** | Step 1 (mkdocs.yml fixes) | High — broken consent, wrong branch, missing SPA nav | Low | -| **P0** | Step 5 (broken links/content) | High — broken UX | Medium | -| **P0** | Step 6 (cleanup test files) | Medium — professional appearance | Low | -| **P1** | Step 3 (abbreviations) | Medium — reader comprehension | Low | -| **P1** | Step 4 (404 page) | Medium — UX polish | Low | -| **P1** | Step 2 (tags/status/boost) | Medium — discoverability | Medium-High | -| **P2** | Step 7 (announcement bar) | Low-Medium — branding | Low | -| **P2** | Step 8 (blog seeding) | Low — completeness | Medium | -| **P2** | Step 9 (screenshot audit) | Medium — visual credibility | High | - ---- - -## Material Theme Reference - -Key Material docs for implementers: -- [Setting up tags](https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/) -- [Setting up navigation](https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/) -- [Page status](https://squidfunk.github.io/mkdocs-material/reference/index/#setting-the-page-status) -- [Search boosting](https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-boosting) -- [Abbreviations](https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-abbreviations) -- [Cookie consent](https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent) -- [Custom 404](https://www.mkdocs.org/user-guide/custom-themes/#custom-theme) -- [Announcement bar](https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-header/#announcement-bar) diff --git a/mkdocs/docs/assets/images/screenshots/getting-started/upgrade-01-system-tab-initial.png b/mkdocs/docs/assets/images/screenshots/getting-started/upgrade-01-system-tab-initial.png new file mode 100644 index 00000000..0146549f Binary files /dev/null and b/mkdocs/docs/assets/images/screenshots/getting-started/upgrade-01-system-tab-initial.png differ diff --git a/mkdocs/docs/assets/images/screenshots/getting-started/upgrade-02-update-available.png b/mkdocs/docs/assets/images/screenshots/getting-started/upgrade-02-update-available.png new file mode 100644 index 00000000..251a753c Binary files /dev/null and b/mkdocs/docs/assets/images/screenshots/getting-started/upgrade-02-update-available.png differ diff --git a/mkdocs/docs/assets/images/screenshots/getting-started/upgrade-03-confirm-dialog.png b/mkdocs/docs/assets/images/screenshots/getting-started/upgrade-03-confirm-dialog.png new file mode 100644 index 00000000..5bb04204 Binary files /dev/null and b/mkdocs/docs/assets/images/screenshots/getting-started/upgrade-03-confirm-dialog.png differ diff --git a/mkdocs/docs/assets/images/screenshots/getting-started/upgrade-04-success-result.png b/mkdocs/docs/assets/images/screenshots/getting-started/upgrade-04-success-result.png new file mode 100644 index 00000000..617d0a13 Binary files /dev/null and b/mkdocs/docs/assets/images/screenshots/getting-started/upgrade-04-success-result.png differ diff --git a/mkdocs/docs/assets/repo-data/admin-changemaker.lite.json b/mkdocs/docs/assets/repo-data/admin-changemaker.lite.json index 1c310e1b..46a51b57 100644 --- a/mkdocs/docs/assets/repo-data/admin-changemaker.lite.json +++ b/mkdocs/docs/assets/repo-data/admin-changemaker.lite.json @@ -7,10 +7,10 @@ "stars_count": 0, "forks_count": 0, "open_issues_count": 0, - "updated_at": "2026-03-25T20:11:01-06:00", + "updated_at": "2026-03-30T11:54:37-06:00", "created_at": "2025-05-28T14:54:59-06:00", "clone_url": "https://gitea.bnkops.com/admin/changemaker.lite.git", "ssh_url": "git@gitea.bnkops.com:admin/changemaker.lite.git", "default_branch": "main", - "last_build_update": "2026-03-25T20:11:01-06:00" + "last_build_update": "2026-03-30T11:54:37-06:00" } \ No newline at end of file diff --git a/mkdocs/docs/assets/repo-data/anthropics-claude-code.json b/mkdocs/docs/assets/repo-data/anthropics-claude-code.json index f5bf5c8d..e8b7b36f 100644 --- a/mkdocs/docs/assets/repo-data/anthropics-claude-code.json +++ b/mkdocs/docs/assets/repo-data/anthropics-claude-code.json @@ -4,13 +4,13 @@ "description": "Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.", "html_url": "https://github.com/anthropics/claude-code", "language": "Shell", - "stars_count": 82863, - "forks_count": 6945, - "open_issues_count": 7902, - "updated_at": "2026-03-26T05:46:26Z", + "stars_count": 88332, + "forks_count": 9745, + "open_issues_count": 8343, + "updated_at": "2026-03-31T15:50:05Z", "created_at": "2025-02-22T17:41:21Z", "clone_url": "https://github.com/anthropics/claude-code.git", "ssh_url": "git@github.com:anthropics/claude-code.git", "default_branch": "main", - "last_build_update": "2026-03-26T00:31:05Z" + "last_build_update": "2026-03-31T14:35:57Z" } \ No newline at end of file diff --git a/mkdocs/docs/assets/repo-data/coder-code-server.json b/mkdocs/docs/assets/repo-data/coder-code-server.json index c1778600..2449031a 100644 --- a/mkdocs/docs/assets/repo-data/coder-code-server.json +++ b/mkdocs/docs/assets/repo-data/coder-code-server.json @@ -4,13 +4,13 @@ "description": "VS Code in the browser", "html_url": "https://github.com/coder/code-server", "language": "TypeScript", - "stars_count": 76836, - "forks_count": 6567, - "open_issues_count": 166, - "updated_at": "2026-03-26T04:51:01Z", + "stars_count": 76910, + "forks_count": 6575, + "open_issues_count": 172, + "updated_at": "2026-03-31T14:49:15Z", "created_at": "2019-02-27T16:50:41Z", "clone_url": "https://github.com/coder/code-server.git", "ssh_url": "git@github.com:coder/code-server.git", "default_branch": "main", - "last_build_update": "2026-03-25T23:42:46Z" + "last_build_update": "2026-03-31T00:00:24Z" } \ No newline at end of file diff --git a/mkdocs/docs/assets/repo-data/gethomepage-homepage.json b/mkdocs/docs/assets/repo-data/gethomepage-homepage.json index 918e35c4..c05131aa 100644 --- a/mkdocs/docs/assets/repo-data/gethomepage-homepage.json +++ b/mkdocs/docs/assets/repo-data/gethomepage-homepage.json @@ -4,13 +4,13 @@ "description": "A highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.", "html_url": "https://github.com/gethomepage/homepage", "language": "JavaScript", - "stars_count": 29142, - "forks_count": 1831, - "open_issues_count": 2, - "updated_at": "2026-03-26T04:32:12Z", + "stars_count": 29249, + "forks_count": 1833, + "open_issues_count": 0, + "updated_at": "2026-03-31T14:45:22Z", "created_at": "2022-08-24T07:29:42Z", "clone_url": "https://github.com/gethomepage/homepage.git", "ssh_url": "git@github.com:gethomepage/homepage.git", "default_branch": "dev", - "last_build_update": "2026-03-26T04:09:25Z" + "last_build_update": "2026-03-31T14:36:10Z" } \ No newline at end of file diff --git a/mkdocs/docs/assets/repo-data/go-gitea-gitea.json b/mkdocs/docs/assets/repo-data/go-gitea-gitea.json index 9c1b719f..f418fec9 100644 --- a/mkdocs/docs/assets/repo-data/go-gitea-gitea.json +++ b/mkdocs/docs/assets/repo-data/go-gitea-gitea.json @@ -4,13 +4,13 @@ "description": "Git with a cup of tea! Painless self-hosted all-in-one software development service, including Git hosting, code review, team collaboration, package registry and CI/CD", "html_url": "https://github.com/go-gitea/gitea", "language": "Go", - "stars_count": 54497, - "forks_count": 6492, - "open_issues_count": 2870, - "updated_at": "2026-03-26T05:41:32Z", + "stars_count": 54629, + "forks_count": 6518, + "open_issues_count": 2866, + "updated_at": "2026-03-31T15:12:57Z", "created_at": "2016-11-01T02:13:26Z", "clone_url": "https://github.com/go-gitea/gitea.git", "ssh_url": "git@github.com:go-gitea/gitea.git", "default_branch": "main", - "last_build_update": "2026-03-26T00:53:32Z" + "last_build_update": "2026-03-31T15:40:43Z" } \ No newline at end of file diff --git a/mkdocs/docs/assets/repo-data/knadh-listmonk.json b/mkdocs/docs/assets/repo-data/knadh-listmonk.json index 50516355..9dedf154 100644 --- a/mkdocs/docs/assets/repo-data/knadh-listmonk.json +++ b/mkdocs/docs/assets/repo-data/knadh-listmonk.json @@ -4,13 +4,13 @@ "description": "High performance, self-hosted, newsletter and mailing list manager with a modern dashboard. Single binary app.", "html_url": "https://github.com/knadh/listmonk", "language": "Go", - "stars_count": 19343, - "forks_count": 1965, - "open_issues_count": 103, - "updated_at": "2026-03-26T04:23:08Z", + "stars_count": 19396, + "forks_count": 1977, + "open_issues_count": 91, + "updated_at": "2026-03-31T14:23:10Z", "created_at": "2019-06-26T05:08:39Z", "clone_url": "https://github.com/knadh/listmonk.git", "ssh_url": "git@github.com:knadh/listmonk.git", "default_branch": "master", - "last_build_update": "2026-03-26T04:23:38Z" + "last_build_update": "2026-03-31T05:18:48Z" } \ No newline at end of file diff --git a/mkdocs/docs/assets/repo-data/lyqht-mini-qr.json b/mkdocs/docs/assets/repo-data/lyqht-mini-qr.json index 0e80408f..211c1560 100644 --- a/mkdocs/docs/assets/repo-data/lyqht-mini-qr.json +++ b/mkdocs/docs/assets/repo-data/lyqht-mini-qr.json @@ -4,13 +4,13 @@ "description": "Create & scan cute qr codes easily \ud83d\udc7e", "html_url": "https://github.com/lyqht/mini-qr", "language": "Vue", - "stars_count": 1931, - "forks_count": 244, - "open_issues_count": 21, - "updated_at": "2026-03-26T02:38:23Z", + "stars_count": 1938, + "forks_count": 245, + "open_issues_count": 23, + "updated_at": "2026-03-31T12:32:17Z", "created_at": "2023-04-21T14:20:14Z", "clone_url": "https://github.com/lyqht/mini-qr.git", "ssh_url": "git@github.com:lyqht/mini-qr.git", "default_branch": "main", - "last_build_update": "2026-03-13T12:48:04Z" + "last_build_update": "2026-03-31T12:43:07Z" } \ No newline at end of file diff --git a/mkdocs/docs/assets/repo-data/n8n-io-n8n.json b/mkdocs/docs/assets/repo-data/n8n-io-n8n.json index 4d2e67ba..a83a8a25 100644 --- a/mkdocs/docs/assets/repo-data/n8n-io-n8n.json +++ b/mkdocs/docs/assets/repo-data/n8n-io-n8n.json @@ -4,13 +4,13 @@ "description": "Fair-code workflow automation platform with native AI capabilities. Combine visual building with custom code, self-host or cloud, 400+ integrations.", "html_url": "https://github.com/n8n-io/n8n", "language": "TypeScript", - "stars_count": 181103, - "forks_count": 56170, - "open_issues_count": 1416, - "updated_at": "2026-03-26T05:48:22Z", + "stars_count": 181869, + "forks_count": 56348, + "open_issues_count": 1447, + "updated_at": "2026-03-31T15:46:32Z", "created_at": "2019-06-22T09:24:21Z", "clone_url": "https://github.com/n8n-io/n8n.git", "ssh_url": "git@github.com:n8n-io/n8n.git", "default_branch": "master", - "last_build_update": "2026-03-26T05:30:58Z" + "last_build_update": "2026-03-31T15:47:22Z" } \ No newline at end of file diff --git a/mkdocs/docs/assets/repo-data/nocodb-nocodb.json b/mkdocs/docs/assets/repo-data/nocodb-nocodb.json index d391743b..27c13a76 100644 --- a/mkdocs/docs/assets/repo-data/nocodb-nocodb.json +++ b/mkdocs/docs/assets/repo-data/nocodb-nocodb.json @@ -4,13 +4,13 @@ "description": "\ud83d\udd25 \ud83d\udd25 \ud83d\udd25 A Free & Self-hostable Airtable Alternative", "html_url": "https://github.com/nocodb/nocodb", "language": "TypeScript", - "stars_count": 62543, - "forks_count": 4681, - "open_issues_count": 658, - "updated_at": "2026-03-26T05:48:04Z", + "stars_count": 62566, + "forks_count": 4703, + "open_issues_count": 665, + "updated_at": "2026-03-31T15:24:55Z", "created_at": "2017-10-29T18:51:48Z", "clone_url": "https://github.com/nocodb/nocodb.git", "ssh_url": "git@github.com:nocodb/nocodb.git", "default_branch": "develop", - "last_build_update": "2026-03-26T05:48:41Z" + "last_build_update": "2026-03-31T15:24:48Z" } \ No newline at end of file diff --git a/mkdocs/docs/assets/repo-data/ollama-ollama.json b/mkdocs/docs/assets/repo-data/ollama-ollama.json index 64aba706..52c9fd44 100644 --- a/mkdocs/docs/assets/repo-data/ollama-ollama.json +++ b/mkdocs/docs/assets/repo-data/ollama-ollama.json @@ -4,13 +4,13 @@ "description": "Get up and running with Kimi-K2.5, GLM-5, MiniMax, DeepSeek, gpt-oss, Qwen, Gemma and other models.", "html_url": "https://github.com/ollama/ollama", "language": "Go", - "stars_count": 166179, - "forks_count": 15178, - "open_issues_count": 2726, - "updated_at": "2026-03-26T05:38:58Z", + "stars_count": 166587, + "forks_count": 15255, + "open_issues_count": 2778, + "updated_at": "2026-03-31T15:34:55Z", "created_at": "2023-06-26T19:39:32Z", "clone_url": "https://github.com/ollama/ollama.git", "ssh_url": "git@github.com:ollama/ollama.git", "default_branch": "main", - "last_build_update": "2026-03-26T02:01:29Z" + "last_build_update": "2026-03-31T15:11:36Z" } \ No newline at end of file diff --git a/mkdocs/docs/assets/repo-data/squidfunk-mkdocs-material.json b/mkdocs/docs/assets/repo-data/squidfunk-mkdocs-material.json index b209ab35..e947759c 100644 --- a/mkdocs/docs/assets/repo-data/squidfunk-mkdocs-material.json +++ b/mkdocs/docs/assets/repo-data/squidfunk-mkdocs-material.json @@ -4,13 +4,13 @@ "description": "Documentation that simply works", "html_url": "https://github.com/squidfunk/mkdocs-material", "language": "Python", - "stars_count": 26394, - "forks_count": 4060, - "open_issues_count": 2, - "updated_at": "2026-03-26T02:34:14Z", + "stars_count": 26430, + "forks_count": 4062, + "open_issues_count": 1, + "updated_at": "2026-03-31T14:42:16Z", "created_at": "2016-01-28T22:09:23Z", "clone_url": "https://github.com/squidfunk/mkdocs-material.git", "ssh_url": "git@github.com:squidfunk/mkdocs-material.git", "default_branch": "master", - "last_build_update": "2026-03-25T22:14:34Z" + "last_build_update": "2026-03-27T10:24:49Z" } \ No newline at end of file diff --git a/mkdocs/docs/blog/posts/2026-03-27-test-blog-post.md b/mkdocs/docs/blog/posts/2026-03-27-test-blog-post.md new file mode 100644 index 00000000..3ff70050 --- /dev/null +++ b/mkdocs/docs/blog/posts/2026-03-27-test-blog-post.md @@ -0,0 +1,12 @@ +--- +date: 2026-03-27 +authors: + - admin +categories: + - Testing +draft: false +--- + +# Test Blog Post - Version 7 + +This version uses the auto-setup token. diff --git a/mkdocs/docs/blog/posts/introducing-changemaker-lite-v2.md b/mkdocs/docs/blog/posts/introducing-changemaker-lite-v2.md index f9462cba..de90f3f1 100644 --- a/mkdocs/docs/blog/posts/introducing-changemaker-lite-v2.md +++ b/mkdocs/docs/blog/posts/introducing-changemaker-lite-v2.md @@ -55,7 +55,7 @@ Read more in our [Philosophy](../../docs/phil.md) page. ## Get Started ```bash -curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/v2/scripts/install.sh | bash +curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/main/scripts/install.sh | bash ``` Or follow the [Getting Started guide](../../docs/getting-started/index.md) for a walkthrough. diff --git a/mkdocs/docs/docs/deployment/index.md b/mkdocs/docs/docs/deployment/index.md index 926d33d6..aaa83f4b 100644 --- a/mkdocs/docs/docs/deployment/index.md +++ b/mkdocs/docs/docs/deployment/index.md @@ -530,7 +530,7 @@ Pre-configured alerts in `configs/prometheus/alerts.yml`: ```bash # Pull latest code -git pull origin v2 +git pull origin main # Rebuild and restart containers docker compose build api admin diff --git a/mkdocs/docs/docs/getting-started/index.md b/mkdocs/docs/docs/getting-started/index.md index a72e6d01..2fb6157d 100644 --- a/mkdocs/docs/docs/getting-started/index.md +++ b/mkdocs/docs/docs/getting-started/index.md @@ -30,7 +30,7 @@ This guide walks you through installing Changemaker Lite, running your first dep The fastest way to deploy — no source code, no compilation: ```bash -curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/v2/scripts/install.sh | bash +curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/main/scripts/install.sh | bash ``` This downloads a lightweight release package (~2 MB), runs the configuration wizard, and pulls pre-built Docker images. First startup takes ~2 minutes. See [Installation](installation.md#pre-built-image-installation) for details. @@ -42,7 +42,6 @@ For development or customization, clone the full repository: ```bash git clone https://gitea.bnkops.com/admin/changemaker.lite cd changemaker.lite -git checkout v2 ``` ```bash diff --git a/mkdocs/docs/docs/getting-started/installation.md b/mkdocs/docs/docs/getting-started/installation.md index a410f489..fb1835f3 100644 --- a/mkdocs/docs/docs/getting-started/installation.md +++ b/mkdocs/docs/docs/getting-started/installation.md @@ -34,7 +34,6 @@ Clone the repository: ```bash git clone https://gitea.bnkops.com/admin/changemaker.lite cd changemaker.lite -git checkout v2 ``` Run the configuration wizard: @@ -63,7 +62,7 @@ For production deployments, you can skip cloning the source repository entirely. ### One-Line Install ```bash -curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/v2/scripts/install.sh | bash +curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/main/scripts/install.sh | bash ``` This script: diff --git a/mkdocs/docs/docs/getting-started/upgrades.md b/mkdocs/docs/docs/getting-started/upgrades.md index 574a17f8..858392d8 100644 --- a/mkdocs/docs/docs/getting-started/upgrades.md +++ b/mkdocs/docs/docs/getting-started/upgrades.md @@ -61,6 +61,10 @@ sudo systemctl status changemaker-upgrade.path 2. Click the **System** tab 3. Click **Check for Updates** +The System tab shows your current version, last commit message, and auto-upgrade settings: + +![System tab initial state](../../assets/images/screenshots/getting-started/upgrade-01-system-tab-initial.png) + The system fetches from the git remote and shows: - Current commit hash and message @@ -68,6 +72,10 @@ The system fetches from the git remote and shows: - Number of commits behind - Changelog of incoming changes +When updates are available, the panel highlights how many commits are behind and lists the incoming changes: + +![Update available notification](../../assets/images/screenshots/getting-started/upgrade-02-update-available.png) + ### Starting an Upgrade 1. Review the changelog to understand what's changing @@ -79,8 +87,19 @@ The system fetches from the git remote and shows: - **Dry run** — preview what would happen without making changes 4. Monitor the 6-phase progress indicator +![Confirm System Upgrade dialog](../../assets/images/screenshots/getting-started/upgrade-03-confirm-dialog.png) + The GUI polls for progress updates and displays the current phase, percentage, and status message in real time. +### Upgrade Results + +After the upgrade completes, the System tab shows the result — including the new version, health check status, and any warnings: + +![Upgrade success result](../../assets/images/screenshots/getting-started/upgrade-04-success-result.png) + +!!! tip + If health checks show warnings immediately after an upgrade, wait 1-2 minutes for services to fully start before investigating. + --- ## The 6 Upgrade Phases diff --git a/mkdocs/docs/hooks/__pycache__/env_config_hook.cpython-311.pyc b/mkdocs/docs/hooks/__pycache__/env_config_hook.cpython-311.pyc index 0d11b807..c6df05c6 100644 Binary files a/mkdocs/docs/hooks/__pycache__/env_config_hook.cpython-311.pyc and b/mkdocs/docs/hooks/__pycache__/env_config_hook.cpython-311.pyc differ diff --git a/mkdocs/docs/hooks/__pycache__/repo_widget_hook.cpython-311.pyc b/mkdocs/docs/hooks/__pycache__/repo_widget_hook.cpython-311.pyc index 9bf58cc1..c610655e 100644 Binary files a/mkdocs/docs/hooks/__pycache__/repo_widget_hook.cpython-311.pyc and b/mkdocs/docs/hooks/__pycache__/repo_widget_hook.cpython-311.pyc differ diff --git a/mkdocs/docs/hooks/__pycache__/wikilinks_hook.cpython-311.pyc b/mkdocs/docs/hooks/__pycache__/wikilinks_hook.cpython-311.pyc index 3054014a..88bec183 100644 Binary files a/mkdocs/docs/hooks/__pycache__/wikilinks_hook.cpython-311.pyc and b/mkdocs/docs/hooks/__pycache__/wikilinks_hook.cpython-311.pyc differ diff --git a/mkdocs/docs/test-page.md b/mkdocs/docs/test-page.md index 67ea0f95..51395036 100644 --- a/mkdocs/docs/test-page.md +++ b/mkdocs/docs/test-page.md @@ -5,3 +5,9 @@ hide: - toc title: "Test Page" --- + +Testing + +testing testing one two + +hello is this content going to show? \ No newline at end of file diff --git a/mkdocs/docs/test.md b/mkdocs/docs/test.md new file mode 100644 index 00000000..e98ae0fa --- /dev/null +++ b/mkdocs/docs/test.md @@ -0,0 +1,3 @@ +# test + +Hello! \ No newline at end of file diff --git a/mkdocs/mkdocs.yml.bak b/mkdocs/mkdocs.yml.bak index f0ac4d81..04c7e9db 100644 --- a/mkdocs/mkdocs.yml.bak +++ b/mkdocs/mkdocs.yml.bak @@ -9,7 +9,7 @@ use_directory_urls: true # Repository repo_url: https://gitea.bnkops.com/admin/changemaker.lite repo_name: changemaker.lite -edit_uri: src/branch/v2/mkdocs/docs +edit_uri: src/branch/main/mkdocs/docs # Theme theme: diff --git a/mkdocs/site/404.html b/mkdocs/site/404.html index 5d702923..8880df87 100644 --- a/mkdocs/site/404.html +++ b/mkdocs/site/404.html @@ -1522,6 +1522,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output { + + diff --git a/mkdocs/site/404/index.html b/mkdocs/site/404/index.html index ef29bda1..78ecfde8 100644 --- a/mkdocs/site/404/index.html +++ b/mkdocs/site/404/index.html @@ -1397,7 +1397,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output { - + @@ -1406,7 +1406,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output { - + @@ -1598,6 +1598,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output { + + diff --git a/mkdocs/site/assets/images/screenshots/getting-started/upgrade-01-system-tab-initial.png b/mkdocs/site/assets/images/screenshots/getting-started/upgrade-01-system-tab-initial.png new file mode 100644 index 00000000..0146549f Binary files /dev/null and b/mkdocs/site/assets/images/screenshots/getting-started/upgrade-01-system-tab-initial.png differ diff --git a/mkdocs/site/assets/images/screenshots/getting-started/upgrade-02-update-available.png b/mkdocs/site/assets/images/screenshots/getting-started/upgrade-02-update-available.png new file mode 100644 index 00000000..251a753c Binary files /dev/null and b/mkdocs/site/assets/images/screenshots/getting-started/upgrade-02-update-available.png differ diff --git a/mkdocs/site/assets/images/screenshots/getting-started/upgrade-03-confirm-dialog.png b/mkdocs/site/assets/images/screenshots/getting-started/upgrade-03-confirm-dialog.png new file mode 100644 index 00000000..5bb04204 Binary files /dev/null and b/mkdocs/site/assets/images/screenshots/getting-started/upgrade-03-confirm-dialog.png differ diff --git a/mkdocs/site/assets/images/screenshots/getting-started/upgrade-04-success-result.png b/mkdocs/site/assets/images/screenshots/getting-started/upgrade-04-success-result.png new file mode 100644 index 00000000..617d0a13 Binary files /dev/null and b/mkdocs/site/assets/images/screenshots/getting-started/upgrade-04-success-result.png differ diff --git a/mkdocs/site/assets/images/social/blog/2026/03/27/test-blog-post---version-7.png b/mkdocs/site/assets/images/social/blog/2026/03/27/test-blog-post---version-7.png new file mode 100644 index 00000000..06d3f3f6 Binary files /dev/null and b/mkdocs/site/assets/images/social/blog/2026/03/27/test-blog-post---version-7.png differ diff --git a/mkdocs/site/assets/images/social/blog/category/testing.png b/mkdocs/site/assets/images/social/blog/category/testing.png new file mode 100644 index 00000000..c6d22b02 Binary files /dev/null and b/mkdocs/site/assets/images/social/blog/category/testing.png differ diff --git a/mkdocs/site/assets/images/social/test.png b/mkdocs/site/assets/images/social/test.png new file mode 100644 index 00000000..47fa3e3c Binary files /dev/null and b/mkdocs/site/assets/images/social/test.png differ diff --git a/mkdocs/site/assets/js/straw-poll-widget.js b/mkdocs/site/assets/js/straw-poll-widget.js new file mode 100644 index 00000000..a245d59d --- /dev/null +++ b/mkdocs/site/assets/js/straw-poll-widget.js @@ -0,0 +1,226 @@ +/** + * Straw Poll Widget Hydration for MkDocs + * + * Supports two modes: + * .straw-poll-inline — Full voting UI embedded in docs page + * .straw-poll-card — Preview card linking to the full poll lander + * + * Uses the lightweight /api/straw-polls/widget/:slug endpoint (cached). + * Follows the scheduling-poll.js hydration pattern. + */ +(function () { + 'use strict'; + + function getApiUrl() { + if (window.PAYMENT_API_URL) return window.PAYMENT_API_URL; + if (window.API_URL) return window.API_URL; + var host = window.location.hostname; + if (host !== 'localhost' && host.indexOf('.') !== -1) { + var parts = host.split('.'); + var base = parts.slice(-2).join('.'); + return window.location.protocol + '//api.' + base; + } + return 'http://localhost:4000'; + } + + function getAppUrl() { + if (window.APP_URL) return window.APP_URL; + var host = window.location.hostname; + if (host !== 'localhost' && host.indexOf('.') !== -1) { + var parts = host.split('.'); + var base = parts.slice(-2).join('.'); + return window.location.protocol + '//app.' + base; + } + return 'http://localhost:3000'; + } + + var COLORS = ['#1890ff', '#52c41a', '#faad14', '#ff4d4f', '#722ed1', '#13c2c2', '#eb2f96']; + var YNA_COLORS = { Yes: '#52c41a', No: '#ff4d4f', Abstain: '#8c8c8c' }; + + function tokenKey(slug) { + return 'straw_poll_voter_token_' + slug; + } + + // ===== Card Mode ===== + function renderCard(block, poll, appUrl) { + var html = '
'; + html += '
'; + html += (poll.type === 'YES_NO_ABSTAIN' ? 'Yes / No / Abstain' : 'Single Choice') + ' Poll
'; + html += '

' + poll.title + '

'; + html += '
' + poll.totalVotes + ' vote' + (poll.totalVotes !== 1 ? 's' : '') + '
'; + if (poll.status === 'ACTIVE') { + html += ' 0; + + var html = '
'; + + // Title + html += '

' + poll.title + '

'; + html += '
'; + html += (poll.type === 'YES_NO_ABSTAIN' ? 'Yes / No / Abstain' : 'Single Choice'); + html += ' · ' + poll.totalVotes + ' vote' + (poll.totalVotes !== 1 ? 's' : '') + '
'; + + if (poll.status === 'ACTIVE' && !hasVoted) { + // Vote form + html += '
'; + poll.options.forEach(function (opt, i) { + var isYNA = poll.type === 'YES_NO_ABSTAIN'; + var color = isYNA ? (YNA_COLORS[opt.label] || COLORS[i]) : COLORS[i % COLORS.length]; + html += ''; + }); + html += ''; + html += ''; + html += '
'; + } + + // Results + if (showResults && (hasVoted || poll.status !== 'ACTIVE')) { + html += renderResultsHtml(poll); + } + + if (hasVoted && poll.status === 'ACTIVE') { + html += '
✓ You\'ve voted
'; + } + + html += '
'; + block.innerHTML = html; + + // Wire up vote form + if (poll.status === 'ACTIVE' && !hasVoted) { + wireVoteForm(block, poll, apiUrl, slug); + } + } + + function renderResultsHtml(poll) { + var html = '
'; + poll.options.forEach(function (opt, i) { + var pct = poll.totalVotes > 0 ? Math.round((opt.voteCount / poll.totalVotes) * 100) : 0; + var color = poll.type === 'YES_NO_ABSTAIN' ? (YNA_COLORS[opt.label] || COLORS[i]) : COLORS[i % COLORS.length]; + html += '
'; + html += '
'; + html += '' + opt.label + '' + opt.voteCount + ' (' + pct + '%)
'; + html += '
'; + html += '
'; + html += '
'; + }); + html += '
'; + return html; + } + + function wireVoteForm(block, poll, apiUrl, slug) { + var selectedId = null; + var buttons = block.querySelectorAll('.sp-opt-btn'); + var submitBtn = block.querySelector('#sp-submit-' + slug); + + buttons.forEach(function (btn) { + btn.addEventListener('click', function () { + selectedId = btn.getAttribute('data-option-id'); + buttons.forEach(function (b) { b.style.borderWidth = '2px'; b.style.fontWeight = 'normal'; }); + btn.style.borderWidth = '3px'; + btn.style.fontWeight = '600'; + submitBtn.disabled = false; + submitBtn.style.opacity = '1'; + }); + }); + + submitBtn.addEventListener('click', function () { + if (!selectedId) return; + submitBtn.disabled = true; + submitBtn.textContent = 'Submitting...'; + + var voterName = (block.querySelector('#sp-voter-name-' + slug) || {}).value || ''; + var body = { optionId: selectedId }; + if (voterName) body.voterName = voterName; + var storedToken = localStorage.getItem(tokenKey(slug)); + if (storedToken) body.voterToken = storedToken; + + fetch(apiUrl + '/api/straw-polls/public/' + encodeURIComponent(slug) + '/vote', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify(body), + }) + .then(function (res) { return res.json(); }) + .then(function (data) { + if (data.voterToken) localStorage.setItem(tokenKey(slug), data.voterToken); + // Re-fetch and re-render with results + return fetch(apiUrl + '/api/straw-polls/widget/' + encodeURIComponent(slug)).then(function (r) { return r.json(); }); + }) + .then(function (updated) { + renderInline(block, updated, apiUrl); + }) + .catch(function () { + submitBtn.textContent = 'Error — try again'; + submitBtn.disabled = false; + submitBtn.style.opacity = '1'; + }); + }); + } + + // ===== Hydration ===== + function hydrateBlocks() { + var apiUrl = getApiUrl(); + var appUrl = getAppUrl(); + + // Inline embeds + document.querySelectorAll('.straw-poll-inline').forEach(function (block) { + if (block.getAttribute('data-hydrated') === 'true') return; + var slug = block.getAttribute('data-poll-slug'); + if (!slug) return; + block.setAttribute('data-hydrated', 'true'); + block.innerHTML = '
Loading poll...
'; + + fetch(apiUrl + '/api/straw-polls/widget/' + encodeURIComponent(slug)) + .then(function (res) { if (!res.ok) throw new Error(); return res.json(); }) + .then(function (poll) { renderInline(block, poll, apiUrl); }) + .catch(function () { + block.innerHTML = '
Poll unavailable
'; + }); + }); + + // Card links + document.querySelectorAll('.straw-poll-card').forEach(function (block) { + if (block.getAttribute('data-hydrated') === 'true') return; + var slug = block.getAttribute('data-poll-slug'); + if (!slug) return; + block.setAttribute('data-hydrated', 'true'); + block.innerHTML = '
Loading...
'; + + fetch(apiUrl + '/api/straw-polls/widget/' + encodeURIComponent(slug)) + .then(function (res) { if (!res.ok) throw new Error(); return res.json(); }) + .then(function (poll) { renderCard(block, poll, appUrl); }) + .catch(function () { + block.innerHTML = '
Poll unavailable
'; + }); + }); + } + + // Initial hydration + if (document.readyState === 'loading') { + document.addEventListener('DOMContentLoaded', hydrateBlocks); + } else { + hydrateBlocks(); + } + + // Re-hydrate on MkDocs SPA navigation + if (typeof document$ !== 'undefined') { + document$.subscribe(function () { setTimeout(hydrateBlocks, 100); }); + } +})(); diff --git a/mkdocs/site/assets/repo-data/admin-changemaker.lite.json b/mkdocs/site/assets/repo-data/admin-changemaker.lite.json index 159085f7..46a51b57 100644 --- a/mkdocs/site/assets/repo-data/admin-changemaker.lite.json +++ b/mkdocs/site/assets/repo-data/admin-changemaker.lite.json @@ -7,10 +7,10 @@ "stars_count": 0, "forks_count": 0, "open_issues_count": 0, - "updated_at": "2026-03-23T15:48:06-06:00", + "updated_at": "2026-03-30T11:54:37-06:00", "created_at": "2025-05-28T14:54:59-06:00", "clone_url": "https://gitea.bnkops.com/admin/changemaker.lite.git", "ssh_url": "git@gitea.bnkops.com:admin/changemaker.lite.git", "default_branch": "main", - "last_build_update": "2026-03-23T15:48:06-06:00" + "last_build_update": "2026-03-30T11:54:37-06:00" } \ No newline at end of file diff --git a/mkdocs/site/assets/repo-data/anthropics-claude-code.json b/mkdocs/site/assets/repo-data/anthropics-claude-code.json index 86f4e3f6..e8b7b36f 100644 --- a/mkdocs/site/assets/repo-data/anthropics-claude-code.json +++ b/mkdocs/site/assets/repo-data/anthropics-claude-code.json @@ -4,13 +4,13 @@ "description": "Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.", "html_url": "https://github.com/anthropics/claude-code", "language": "Shell", - "stars_count": 81725, - "forks_count": 6816, - "open_issues_count": 7445, - "updated_at": "2026-03-23T23:45:06Z", + "stars_count": 88332, + "forks_count": 9745, + "open_issues_count": 8343, + "updated_at": "2026-03-31T15:50:05Z", "created_at": "2025-02-22T17:41:21Z", "clone_url": "https://github.com/anthropics/claude-code.git", "ssh_url": "git@github.com:anthropics/claude-code.git", "default_branch": "main", - "last_build_update": "2026-03-20T22:24:50Z" + "last_build_update": "2026-03-31T14:35:57Z" } \ No newline at end of file diff --git a/mkdocs/site/assets/repo-data/coder-code-server.json b/mkdocs/site/assets/repo-data/coder-code-server.json index 192a8e2c..2449031a 100644 --- a/mkdocs/site/assets/repo-data/coder-code-server.json +++ b/mkdocs/site/assets/repo-data/coder-code-server.json @@ -4,13 +4,13 @@ "description": "VS Code in the browser", "html_url": "https://github.com/coder/code-server", "language": "TypeScript", - "stars_count": 76802, - "forks_count": 6567, - "open_issues_count": 167, - "updated_at": "2026-03-23T23:30:09Z", + "stars_count": 76910, + "forks_count": 6575, + "open_issues_count": 172, + "updated_at": "2026-03-31T14:49:15Z", "created_at": "2019-02-27T16:50:41Z", "clone_url": "https://github.com/coder/code-server.git", "ssh_url": "git@github.com:coder/code-server.git", "default_branch": "main", - "last_build_update": "2026-03-23T18:50:37Z" + "last_build_update": "2026-03-31T00:00:24Z" } \ No newline at end of file diff --git a/mkdocs/site/assets/repo-data/gethomepage-homepage.json b/mkdocs/site/assets/repo-data/gethomepage-homepage.json index 46b3bc59..c05131aa 100644 --- a/mkdocs/site/assets/repo-data/gethomepage-homepage.json +++ b/mkdocs/site/assets/repo-data/gethomepage-homepage.json @@ -4,13 +4,13 @@ "description": "A highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.", "html_url": "https://github.com/gethomepage/homepage", "language": "JavaScript", - "stars_count": 29108, - "forks_count": 1825, - "open_issues_count": 1, - "updated_at": "2026-03-23T22:44:02Z", + "stars_count": 29249, + "forks_count": 1833, + "open_issues_count": 0, + "updated_at": "2026-03-31T14:45:22Z", "created_at": "2022-08-24T07:29:42Z", "clone_url": "https://github.com/gethomepage/homepage.git", "ssh_url": "git@github.com:gethomepage/homepage.git", "default_branch": "dev", - "last_build_update": "2026-03-23T12:27:34Z" + "last_build_update": "2026-03-31T14:36:10Z" } \ No newline at end of file diff --git a/mkdocs/site/assets/repo-data/go-gitea-gitea.json b/mkdocs/site/assets/repo-data/go-gitea-gitea.json index 2a2d1493..f418fec9 100644 --- a/mkdocs/site/assets/repo-data/go-gitea-gitea.json +++ b/mkdocs/site/assets/repo-data/go-gitea-gitea.json @@ -4,13 +4,13 @@ "description": "Git with a cup of tea! Painless self-hosted all-in-one software development service, including Git hosting, code review, team collaboration, package registry and CI/CD", "html_url": "https://github.com/go-gitea/gitea", "language": "Go", - "stars_count": 54439, - "forks_count": 6485, - "open_issues_count": 2870, - "updated_at": "2026-03-23T23:19:17Z", + "stars_count": 54629, + "forks_count": 6518, + "open_issues_count": 2866, + "updated_at": "2026-03-31T15:12:57Z", "created_at": "2016-11-01T02:13:26Z", "clone_url": "https://github.com/go-gitea/gitea.git", "ssh_url": "git@github.com:go-gitea/gitea.git", "default_branch": "main", - "last_build_update": "2026-03-23T23:20:24Z" + "last_build_update": "2026-03-31T15:40:43Z" } \ No newline at end of file diff --git a/mkdocs/site/assets/repo-data/knadh-listmonk.json b/mkdocs/site/assets/repo-data/knadh-listmonk.json index 4381eade..9dedf154 100644 --- a/mkdocs/site/assets/repo-data/knadh-listmonk.json +++ b/mkdocs/site/assets/repo-data/knadh-listmonk.json @@ -4,13 +4,13 @@ "description": "High performance, self-hosted, newsletter and mailing list manager with a modern dashboard. Single binary app.", "html_url": "https://github.com/knadh/listmonk", "language": "Go", - "stars_count": 19329, - "forks_count": 1958, - "open_issues_count": 105, - "updated_at": "2026-03-23T23:36:16Z", + "stars_count": 19396, + "forks_count": 1977, + "open_issues_count": 91, + "updated_at": "2026-03-31T14:23:10Z", "created_at": "2019-06-26T05:08:39Z", "clone_url": "https://github.com/knadh/listmonk.git", "ssh_url": "git@github.com:knadh/listmonk.git", "default_branch": "master", - "last_build_update": "2026-03-23T11:44:19Z" + "last_build_update": "2026-03-31T05:18:48Z" } \ No newline at end of file diff --git a/mkdocs/site/assets/repo-data/lyqht-mini-qr.json b/mkdocs/site/assets/repo-data/lyqht-mini-qr.json index c67a8a41..211c1560 100644 --- a/mkdocs/site/assets/repo-data/lyqht-mini-qr.json +++ b/mkdocs/site/assets/repo-data/lyqht-mini-qr.json @@ -4,13 +4,13 @@ "description": "Create & scan cute qr codes easily \ud83d\udc7e", "html_url": "https://github.com/lyqht/mini-qr", "language": "Vue", - "stars_count": 1928, - "forks_count": 243, - "open_issues_count": 20, - "updated_at": "2026-03-23T14:42:50Z", + "stars_count": 1938, + "forks_count": 245, + "open_issues_count": 23, + "updated_at": "2026-03-31T12:32:17Z", "created_at": "2023-04-21T14:20:14Z", "clone_url": "https://github.com/lyqht/mini-qr.git", "ssh_url": "git@github.com:lyqht/mini-qr.git", "default_branch": "main", - "last_build_update": "2026-03-13T12:48:04Z" + "last_build_update": "2026-03-31T12:43:07Z" } \ No newline at end of file diff --git a/mkdocs/site/assets/repo-data/n8n-io-n8n.json b/mkdocs/site/assets/repo-data/n8n-io-n8n.json index d57c7a2f..a83a8a25 100644 --- a/mkdocs/site/assets/repo-data/n8n-io-n8n.json +++ b/mkdocs/site/assets/repo-data/n8n-io-n8n.json @@ -4,13 +4,13 @@ "description": "Fair-code workflow automation platform with native AI capabilities. Combine visual building with custom code, self-host or cloud, 400+ integrations.", "html_url": "https://github.com/n8n-io/n8n", "language": "TypeScript", - "stars_count": 180706, - "forks_count": 56089, - "open_issues_count": 1433, - "updated_at": "2026-03-23T23:47:25Z", + "stars_count": 181869, + "forks_count": 56348, + "open_issues_count": 1447, + "updated_at": "2026-03-31T15:46:32Z", "created_at": "2019-06-22T09:24:21Z", "clone_url": "https://github.com/n8n-io/n8n.git", "ssh_url": "git@github.com:n8n-io/n8n.git", "default_branch": "master", - "last_build_update": "2026-03-23T22:55:38Z" + "last_build_update": "2026-03-31T15:47:22Z" } \ No newline at end of file diff --git a/mkdocs/site/assets/repo-data/nocodb-nocodb.json b/mkdocs/site/assets/repo-data/nocodb-nocodb.json index 9072cbd1..27c13a76 100644 --- a/mkdocs/site/assets/repo-data/nocodb-nocodb.json +++ b/mkdocs/site/assets/repo-data/nocodb-nocodb.json @@ -4,13 +4,13 @@ "description": "\ud83d\udd25 \ud83d\udd25 \ud83d\udd25 A Free & Self-hostable Airtable Alternative", "html_url": "https://github.com/nocodb/nocodb", "language": "TypeScript", - "stars_count": 62544, - "forks_count": 4679, - "open_issues_count": 647, - "updated_at": "2026-03-23T22:41:15Z", + "stars_count": 62566, + "forks_count": 4703, + "open_issues_count": 665, + "updated_at": "2026-03-31T15:24:55Z", "created_at": "2017-10-29T18:51:48Z", "clone_url": "https://github.com/nocodb/nocodb.git", "ssh_url": "git@github.com:nocodb/nocodb.git", "default_branch": "develop", - "last_build_update": "2026-03-23T19:39:55Z" + "last_build_update": "2026-03-31T15:24:48Z" } \ No newline at end of file diff --git a/mkdocs/site/assets/repo-data/ollama-ollama.json b/mkdocs/site/assets/repo-data/ollama-ollama.json index b042dc06..52c9fd44 100644 --- a/mkdocs/site/assets/repo-data/ollama-ollama.json +++ b/mkdocs/site/assets/repo-data/ollama-ollama.json @@ -4,13 +4,13 @@ "description": "Get up and running with Kimi-K2.5, GLM-5, MiniMax, DeepSeek, gpt-oss, Qwen, Gemma and other models.", "html_url": "https://github.com/ollama/ollama", "language": "Go", - "stars_count": 165968, - "forks_count": 15121, - "open_issues_count": 2708, - "updated_at": "2026-03-23T23:47:27Z", + "stars_count": 166587, + "forks_count": 15255, + "open_issues_count": 2778, + "updated_at": "2026-03-31T15:34:55Z", "created_at": "2023-06-26T19:39:32Z", "clone_url": "https://github.com/ollama/ollama.git", "ssh_url": "git@github.com:ollama/ollama.git", "default_branch": "main", - "last_build_update": "2026-03-23T23:31:24Z" + "last_build_update": "2026-03-31T15:11:36Z" } \ No newline at end of file diff --git a/mkdocs/site/assets/repo-data/squidfunk-mkdocs-material.json b/mkdocs/site/assets/repo-data/squidfunk-mkdocs-material.json index 66f348b2..e947759c 100644 --- a/mkdocs/site/assets/repo-data/squidfunk-mkdocs-material.json +++ b/mkdocs/site/assets/repo-data/squidfunk-mkdocs-material.json @@ -4,13 +4,13 @@ "description": "Documentation that simply works", "html_url": "https://github.com/squidfunk/mkdocs-material", "language": "Python", - "stars_count": 26370, - "forks_count": 4058, + "stars_count": 26430, + "forks_count": 4062, "open_issues_count": 1, - "updated_at": "2026-03-23T21:42:58Z", + "updated_at": "2026-03-31T14:42:16Z", "created_at": "2016-01-28T22:09:23Z", "clone_url": "https://github.com/squidfunk/mkdocs-material.git", "ssh_url": "git@github.com:squidfunk/mkdocs-material.git", "default_branch": "master", - "last_build_update": "2026-03-22T15:57:47Z" + "last_build_update": "2026-03-27T10:24:49Z" } \ No newline at end of file diff --git a/mkdocs/site/blog/2026/03/22/introducing-changemaker-lite-v2/index.html b/mkdocs/site/blog/2026/03/22/introducing-changemaker-lite-v2/index.html index a17094ca..ef933160 100644 --- a/mkdocs/site/blog/2026/03/22/introducing-changemaker-lite-v2/index.html +++ b/mkdocs/site/blog/2026/03/22/introducing-changemaker-lite-v2/index.html @@ -17,6 +17,8 @@ + + @@ -1432,6 +1434,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output { + + @@ -1704,7 +1708,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output { - + @@ -1713,7 +1717,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output { - + @@ -1752,7 +1756,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {

Changemaker Lite costs roughly the price of a VPS — often under $50/month for the full stack. But the real value isn't cost savings. It's control. No vendor can cut off your access. No acquisition can change your terms.

Read more in our Philosophy page.

Get Started

-
curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/v2/scripts/install.sh | bash
+
curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/main/scripts/install.sh | bash
 

 
Or follow the Getting Started guide for a walkthrough.

 
What's Next

@@ -1803,6 +1807,30 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
         

   
     
+      
+        
+      
+      
+    
   
   

     

@@ -1940,6 +1968,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/blog/2026/03/27/test-blog-post---version-7/index.html b/mkdocs/site/blog/2026/03/27/test-blog-post---version-7/index.html
new file mode 100644
index 00000000..9dce6d66
--- /dev/null
+++ b/mkdocs/site/blog/2026/03/27/test-blog-post---version-7/index.html
@@ -0,0 +1,1842 @@
+
+
+
+
+  
+    
+      
+      
+      
+        
+      
+      
+        
+      
+      
+        
+      
+      
+        
+      
+      
+      
+        
+      
+      
+      
+      
+    
+    
+      
+        Test Blog Post - Version 7 - Changemaker Lite
+      
+    
+    
+      
+      
+        
+        
+      
+      
+
+
+    
+    
+      
+    
+    
+      
+        
+        
+        
+        
+        
+      
+    
+    
+      
+    
+      
+    
+      
+    
+      
+    
+      
+    
+      
+    
+    
+    
+      
+  
+
+
+  
+  
+    
+  
+
+    
+    
+  
+
+
+
+
+
+
+
+
+
+
+
+
+
+  
+  
+    
+    
+      
+    
+    
+    
+    
+    
+  
+    
+    
+    
+    
+    
+    

+      
+        
+      
+    

+    
+    
+

+  

+    
+      
+        

+  
+    
+    
+    
+    
+    
+      
+    
+  
+    
+    
+    
+    
+    
+      
+    
+  
+

+      
+    
+  

+  
+    
+  
+

+
+    

+      
+      
+
+  
+
+
+
+      

+        

+          
+            
+              
+                
+              
+              
+            
+            
+              
+                
+              
+              

+                

+                  

+                    
+
+  
+
+
+                  

+                

+              

+            
+          
+          
+  

+    

+      

+        

+          
+          
+        

+      

+    

+    

+      
+        
+  
+
+
+
+  
+    
+      
+      
+    
+  
+  
+    
+      
+    
+    
+      
+      
+    
+  
+
+
+
Test Blog Post - Version 7

+
This version uses the auto-setup token.

+
+
+
+
+
+
+
+  
+  
+
+
+
+  
+
+
+  
+
+
+
+      
+    

+  

+
+          
+  
+
+
+        

+        
+          
+        
+      

+      
+        
+      
+    

+    

+      

+    

+    
+      

+    
+    
+      
+      
+    
+    
+      
+      
+      
+    
+    
+      
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+    
+  
+
\ No newline at end of file
diff --git a/mkdocs/site/blog/archive/2026/index.html b/mkdocs/site/blog/archive/2026/index.html
index cfe6b34f..c6075d42 100644
--- a/mkdocs/site/blog/archive/2026/index.html
+++ b/mkdocs/site/blog/archive/2026/index.html
@@ -16,7 +16,7 @@
         
       
       
-        
+        
       
       
       
@@ -1484,6 +1484,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
     
     
     
@@ -1582,6 +1584,48 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
         
       
     
+    

+      
    
+        
  • 
+          
    • 
+        
+          
  • 
+            in
+            
+              Testing
    • 
+        
+        
+          
+          
  • 
+            
+              1 min read
+            
+          
    • 
+        
+        
+      

+      
+    

+  
+  

+    
Test Blog Post - Version 7

+
This version uses the auto-setup token.

+    
+    
+  

+
+      
+        

+  

+    
+      
+    
     

       
    
         
  • 
@@ -1656,7 +1700,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       

         
       
@@ -1859,6 +1891,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/blog/category/platform/index.html b/mkdocs/site/blog/category/platform/index.html
index 000e2495..19880829 100644
--- a/mkdocs/site/blog/category/platform/index.html
+++ b/mkdocs/site/blog/category/platform/index.html
@@ -19,7 +19,7 @@
         
       
       
-        
+        
       
       
         
@@ -1435,6 +1435,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
         
       
         
+      
+        
       
     
     
@@ -1553,6 +1555,36 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
               
             
+              
+                
+  
+  
+  
+    
+  
+  
+    
  • 
+      
+        
+  
+  
+  
+    
+  
+    Testing
+  
+
+    
+  
+  
+  
+
+      
+    
    • 
+  
+
+              
+            
           
         
       
@@ -1705,13 +1737,13 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
         
         
           
-          
+          
             
    
               
                 Next
               
               
    
-                2026
+                Testing
               
    
             
    
             
    
@@ -1859,6 +1891,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/blog/category/testing/index.html b/mkdocs/site/blog/category/testing/index.html
new file mode 100644
index 00000000..a8d0f075
--- /dev/null
+++ b/mkdocs/site/blog/category/testing/index.html
@@ -0,0 +1,1894 @@
+
+
+
+
+  
+    
+      
+      
+      
+        
+      
+      
+        
+      
+      
+        
+      
+      
+        
+      
+      
+        
+      
+      
+        
+      
+      
+      
+      
+    
+    
+      
+        Testing - Changemaker Lite
+      
+    
+    
+      
+      
+        
+        
+      
+      
+
+
+    
+    
+      
+    
+    
+      
+        
+        
+        
+        
+        
+      
+    
+    
+      
+    
+      
+    
+      
+    
+      
+    
+      
+    
+      
+    
+    
+    
+      
+  
+
+
+  
+  
+    
+  
+
+    
+    
+  
+
+
+
+
+
+
+
+
+
+
+
+
+
+  
+  
+    
+    
+      
+    
+    
+    
+    
+    
+  
+    
+    
+    
+    
+    
+    
    
+      
+        
+      
+    
    
+    
+    
+
    
+  
    
+    
+      
+        
    
+  
+    
+    
+    
+    
+    
+      
+    
+  
+    
+    
+    
+    
+    
+      
+    
+  
+
    
+      
+    
+  
    
+  
+    
+  
+
    
+
+    
    
+      
+      
+
+  
+
+
+
+      
    
+        
    
+          
+            
+              
+              
    
+                
    
+                  
    
+                    
+
+
+  
+
+
+
+                  
    
+                
    
+              
    
+            
+            
+              
+              
    
+                
    
+                  
    
+                    
+
+  
+
+
+                  
    
+                
    
+              
    
+            
+          
+          
+  
    
+    
    
+      
    
+        
    Testing
    
+      
    
+      
+        
    
+  
    
+    
+      
+    
+    
    
+      
      
+        
    • 
+          
      • 
+        
+          
    • 
+            in
+            
+              Testing
      • 
+        
+        
+          
+          
    • 
+            
+              1 min read
+            
+          
      • 
+        
+        
+      
    
+      
+    
    
+  
    
+  
    
+    
    Test Blog Post - Version 7
    
+
    This version uses the auto-setup token.
    
+    
+    
+  
    
+
    
+      
+      
+        
+          
+
+
+
+
+        
+      
+    
    
+  
    
+
+          
+  
+
+
+        
    
+        
+          
+        
+      
    
+      
+        
+      
+    
    
+    
    
+      
    
+    
    
+    
+      
    
+    
+    
+      
+      
+    
+    
+      
+      
+      
+    
+    
+      
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+    
+  
+
\ No newline at end of file
diff --git a/mkdocs/site/blog/index.html b/mkdocs/site/blog/index.html
index 14005f14..63aa5dec 100644
--- a/mkdocs/site/blog/index.html
+++ b/mkdocs/site/blog/index.html
@@ -1434,6 +1434,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
     
     
     
@@ -1532,6 +1534,48 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
         
       
     
+    
    
+      
      
+        
    • 
+          
      • 
+        
+          
    • 
+            in
+            
+              Testing
      • 
+        
+        
+          
+          
    • 
+            
+              1 min read
+            
+          
      • 
+        
+        
+      
    
+      
+    
    
+  
    
+  
    
+    
    Test Blog Post - Version 7
    
+
    This version uses the auto-setup token.
    
+    
+    
+  
    
+
    
+      
+        
    
+  
    
+    
+      
+    
     
    
       
      
         
    • 
@@ -1777,6 +1821,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/comments/callback/index.html b/mkdocs/site/comments/callback/index.html
index e756de7c..0a355dbf 100644
--- a/mkdocs/site/comments/callback/index.html
+++ b/mkdocs/site/comments/callback/index.html
@@ -1390,7 +1390,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -1399,7 +1399,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -1601,6 +1601,8 @@ setTimeout(function() {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/advocacy/campaigns/index.html b/mkdocs/site/docs/admin/advocacy/campaigns/index.html
index acef8c03..bc6f6621 100644
--- a/mkdocs/site/docs/admin/advocacy/campaigns/index.html
+++ b/mkdocs/site/docs/admin/advocacy/campaigns/index.html
@@ -3076,7 +3076,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3085,7 +3085,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3382,6 +3382,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/advocacy/email-queue/index.html b/mkdocs/site/docs/admin/advocacy/email-queue/index.html
index e7c4a5a2..319e4a7a 100644
--- a/mkdocs/site/docs/admin/advocacy/email-queue/index.html
+++ b/mkdocs/site/docs/admin/advocacy/email-queue/index.html
@@ -2966,7 +2966,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2975,7 +2975,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3212,6 +3212,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/advocacy/index.html b/mkdocs/site/docs/admin/advocacy/index.html
index fe7f7685..fe3d3704 100644
--- a/mkdocs/site/docs/admin/advocacy/index.html
+++ b/mkdocs/site/docs/admin/advocacy/index.html
@@ -2875,7 +2875,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2884,7 +2884,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3114,6 +3114,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/advocacy/representatives/index.html b/mkdocs/site/docs/admin/advocacy/representatives/index.html
index 9a5059fb..61b9e6a9 100644
--- a/mkdocs/site/docs/admin/advocacy/representatives/index.html
+++ b/mkdocs/site/docs/admin/advocacy/representatives/index.html
@@ -2959,7 +2959,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2968,7 +2968,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3204,6 +3204,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/advocacy/responses/index.html b/mkdocs/site/docs/admin/advocacy/responses/index.html
index b8cf3998..6f11ab28 100644
--- a/mkdocs/site/docs/admin/advocacy/responses/index.html
+++ b/mkdocs/site/docs/admin/advocacy/responses/index.html
@@ -2966,7 +2966,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2975,7 +2975,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3212,6 +3212,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/broadcast/email-templates/index.html b/mkdocs/site/docs/admin/broadcast/email-templates/index.html
index 1913eaff..b6ef1a48 100644
--- a/mkdocs/site/docs/admin/broadcast/email-templates/index.html
+++ b/mkdocs/site/docs/admin/broadcast/email-templates/index.html
@@ -3032,7 +3032,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3041,7 +3041,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3309,6 +3309,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/broadcast/index.html b/mkdocs/site/docs/admin/broadcast/index.html
index b2a84c0d..d7b02973 100644
--- a/mkdocs/site/docs/admin/broadcast/index.html
+++ b/mkdocs/site/docs/admin/broadcast/index.html
@@ -2853,7 +2853,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2862,7 +2862,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3091,6 +3091,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/broadcast/newsletter/index.html b/mkdocs/site/docs/admin/broadcast/newsletter/index.html
index 05135a78..95267e55 100644
--- a/mkdocs/site/docs/admin/broadcast/newsletter/index.html
+++ b/mkdocs/site/docs/admin/broadcast/newsletter/index.html
@@ -2988,7 +2988,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2997,7 +2997,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3314,6 +3314,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/broadcast/sms/index.html b/mkdocs/site/docs/admin/broadcast/sms/index.html
index 54a74886..11fb4307 100644
--- a/mkdocs/site/docs/admin/broadcast/sms/index.html
+++ b/mkdocs/site/docs/admin/broadcast/sms/index.html
@@ -3784,7 +3784,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3793,7 +3793,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -4537,6 +4537,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/dashboard/index.html b/mkdocs/site/docs/admin/dashboard/index.html
index e3dc3903..cc67e613 100644
--- a/mkdocs/site/docs/admin/dashboard/index.html
+++ b/mkdocs/site/docs/admin/dashboard/index.html
@@ -2771,7 +2771,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2780,7 +2780,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3014,6 +3014,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/index.html b/mkdocs/site/docs/admin/index.html
index 78f8aa5f..bb2a7138 100644
--- a/mkdocs/site/docs/admin/index.html
+++ b/mkdocs/site/docs/admin/index.html
@@ -2720,7 +2720,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2729,7 +2729,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3063,6 +3063,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/map/areas/index.html b/mkdocs/site/docs/admin/map/areas/index.html
index 5b169f4e..229c42b0 100644
--- a/mkdocs/site/docs/admin/map/areas/index.html
+++ b/mkdocs/site/docs/admin/map/areas/index.html
@@ -3048,7 +3048,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3057,7 +3057,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3304,6 +3304,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/map/canvassing/index.html b/mkdocs/site/docs/admin/map/canvassing/index.html
index 48641525..a2d786d6 100644
--- a/mkdocs/site/docs/admin/map/canvassing/index.html
+++ b/mkdocs/site/docs/admin/map/canvassing/index.html
@@ -3070,7 +3070,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3079,7 +3079,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3332,6 +3332,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/map/data-quality/index.html b/mkdocs/site/docs/admin/map/data-quality/index.html
index 7c784e86..ed431452 100644
--- a/mkdocs/site/docs/admin/map/data-quality/index.html
+++ b/mkdocs/site/docs/admin/map/data-quality/index.html
@@ -3026,7 +3026,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3035,7 +3035,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3272,6 +3272,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/map/index.html b/mkdocs/site/docs/admin/map/index.html
index 88288802..a9ebb4c0 100644
--- a/mkdocs/site/docs/admin/map/index.html
+++ b/mkdocs/site/docs/admin/map/index.html
@@ -2935,7 +2935,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2944,7 +2944,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3176,6 +3176,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/map/locations/index.html b/mkdocs/site/docs/admin/map/locations/index.html
index 75b39347..44942cff 100644
--- a/mkdocs/site/docs/admin/map/locations/index.html
+++ b/mkdocs/site/docs/admin/map/locations/index.html
@@ -3070,7 +3070,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3079,7 +3079,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3327,6 +3327,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/map/settings/index.html b/mkdocs/site/docs/admin/map/settings/index.html
index f30921df..e1b68eff 100644
--- a/mkdocs/site/docs/admin/map/settings/index.html
+++ b/mkdocs/site/docs/admin/map/settings/index.html
@@ -3026,7 +3026,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3035,7 +3035,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3270,6 +3270,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/map/shifts/index.html b/mkdocs/site/docs/admin/map/shifts/index.html
index 588396b2..3cf26819 100644
--- a/mkdocs/site/docs/admin/map/shifts/index.html
+++ b/mkdocs/site/docs/admin/map/shifts/index.html
@@ -3070,7 +3070,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3079,7 +3079,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3328,6 +3328,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/media/ads/index.html b/mkdocs/site/docs/admin/media/ads/index.html
index 930ec0a4..9fd3812b 100644
--- a/mkdocs/site/docs/admin/media/ads/index.html
+++ b/mkdocs/site/docs/admin/media/ads/index.html
@@ -3005,7 +3005,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3014,7 +3014,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3250,6 +3250,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/media/analytics/index.html b/mkdocs/site/docs/admin/media/analytics/index.html
index c63fac10..e1b058dc 100644
--- a/mkdocs/site/docs/admin/media/analytics/index.html
+++ b/mkdocs/site/docs/admin/media/analytics/index.html
@@ -3048,7 +3048,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3057,7 +3057,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3311,6 +3311,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/media/curated/index.html b/mkdocs/site/docs/admin/media/curated/index.html
index 65d4f211..6f5c3ead 100644
--- a/mkdocs/site/docs/admin/media/curated/index.html
+++ b/mkdocs/site/docs/admin/media/curated/index.html
@@ -3026,7 +3026,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3035,7 +3035,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3280,6 +3280,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/media/index.html b/mkdocs/site/docs/admin/media/index.html
index 89721d57..436074d8 100644
--- a/mkdocs/site/docs/admin/media/index.html
+++ b/mkdocs/site/docs/admin/media/index.html
@@ -2913,7 +2913,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2922,7 +2922,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3153,6 +3153,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/media/library/index.html b/mkdocs/site/docs/admin/media/library/index.html
index a8ddc27f..cef26de3 100644
--- a/mkdocs/site/docs/admin/media/library/index.html
+++ b/mkdocs/site/docs/admin/media/library/index.html
@@ -3070,7 +3070,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3079,7 +3079,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3334,6 +3334,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/media/moderation/index.html b/mkdocs/site/docs/admin/media/moderation/index.html
index b9724aef..53d893ff 100644
--- a/mkdocs/site/docs/admin/media/moderation/index.html
+++ b/mkdocs/site/docs/admin/media/moderation/index.html
@@ -3048,7 +3048,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3057,7 +3057,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3331,6 +3331,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/payments/donations/index.html b/mkdocs/site/docs/admin/payments/donations/index.html
index 631d57e3..27d9c998 100644
--- a/mkdocs/site/docs/admin/payments/donations/index.html
+++ b/mkdocs/site/docs/admin/payments/donations/index.html
@@ -3029,7 +3029,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3038,7 +3038,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3285,6 +3285,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/payments/index.html b/mkdocs/site/docs/admin/payments/index.html
index 4c4b3775..e782115f 100644
--- a/mkdocs/site/docs/admin/payments/index.html
+++ b/mkdocs/site/docs/admin/payments/index.html
@@ -2926,7 +2926,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2935,7 +2935,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3172,6 +3172,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/payments/plans/index.html b/mkdocs/site/docs/admin/payments/plans/index.html
index 1fcf0891..b89d414c 100644
--- a/mkdocs/site/docs/admin/payments/plans/index.html
+++ b/mkdocs/site/docs/admin/payments/plans/index.html
@@ -3007,7 +3007,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3016,7 +3016,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3252,6 +3252,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/payments/products/index.html b/mkdocs/site/docs/admin/payments/products/index.html
index 182f6f48..32fff16f 100644
--- a/mkdocs/site/docs/admin/payments/products/index.html
+++ b/mkdocs/site/docs/admin/payments/products/index.html
@@ -3007,7 +3007,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3016,7 +3016,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3251,6 +3251,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/payments/settings/index.html b/mkdocs/site/docs/admin/payments/settings/index.html
index 57219252..83760a83 100644
--- a/mkdocs/site/docs/admin/payments/settings/index.html
+++ b/mkdocs/site/docs/admin/payments/settings/index.html
@@ -3036,7 +3036,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3045,7 +3045,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3287,6 +3287,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/people-access/index.html b/mkdocs/site/docs/admin/people-access/index.html
index 4261fa33..6e240598 100644
--- a/mkdocs/site/docs/admin/people-access/index.html
+++ b/mkdocs/site/docs/admin/people-access/index.html
@@ -3162,7 +3162,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3171,7 +3171,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3544,6 +3544,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/services/crowdsec/index.html b/mkdocs/site/docs/admin/services/crowdsec/index.html
index dfbc47ac..b85adcf4 100644
--- a/mkdocs/site/docs/admin/services/crowdsec/index.html
+++ b/mkdocs/site/docs/admin/services/crowdsec/index.html
@@ -3298,7 +3298,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3307,7 +3307,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3734,6 +3734,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/services/index.html b/mkdocs/site/docs/admin/services/index.html
index 2c579674..fdddfc19 100644
--- a/mkdocs/site/docs/admin/services/index.html
+++ b/mkdocs/site/docs/admin/services/index.html
@@ -2921,7 +2921,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2930,7 +2930,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3161,6 +3161,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/services/integrations/index.html b/mkdocs/site/docs/admin/services/integrations/index.html
index 7ce62ead..97100470 100644
--- a/mkdocs/site/docs/admin/services/integrations/index.html
+++ b/mkdocs/site/docs/admin/services/integrations/index.html
@@ -3122,7 +3122,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3131,7 +3131,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3420,6 +3420,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/services/monitoring/index.html b/mkdocs/site/docs/admin/services/monitoring/index.html
index 5b79d4b9..975b7298 100644
--- a/mkdocs/site/docs/admin/services/monitoring/index.html
+++ b/mkdocs/site/docs/admin/services/monitoring/index.html
@@ -3100,7 +3100,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3109,7 +3109,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3374,6 +3374,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/services/tunnel/index.html b/mkdocs/site/docs/admin/services/tunnel/index.html
index 0a61c37b..9d130e27 100644
--- a/mkdocs/site/docs/admin/services/tunnel/index.html
+++ b/mkdocs/site/docs/admin/services/tunnel/index.html
@@ -3078,7 +3078,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3087,7 +3087,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3347,6 +3347,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/services/user-provisioning/index.html b/mkdocs/site/docs/admin/services/user-provisioning/index.html
index ee8eaa98..7a8de609 100644
--- a/mkdocs/site/docs/admin/services/user-provisioning/index.html
+++ b/mkdocs/site/docs/admin/services/user-provisioning/index.html
@@ -3057,7 +3057,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3066,7 +3066,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3338,6 +3338,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/settings/index.html b/mkdocs/site/docs/admin/settings/index.html
index f440029d..64c806d9 100644
--- a/mkdocs/site/docs/admin/settings/index.html
+++ b/mkdocs/site/docs/admin/settings/index.html
@@ -2922,7 +2922,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2931,7 +2931,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3305,6 +3305,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/web/documentation/index.html b/mkdocs/site/docs/admin/web/documentation/index.html
index c9cb8d63..27da0474 100644
--- a/mkdocs/site/docs/admin/web/documentation/index.html
+++ b/mkdocs/site/docs/admin/web/documentation/index.html
@@ -3003,7 +3003,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3012,7 +3012,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3267,6 +3267,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/web/homepage/index.html b/mkdocs/site/docs/admin/web/homepage/index.html
index c0b0dc8f..d64472a8 100644
--- a/mkdocs/site/docs/admin/web/homepage/index.html
+++ b/mkdocs/site/docs/admin/web/homepage/index.html
@@ -3003,7 +3003,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3012,7 +3012,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3261,6 +3261,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/web/index.html b/mkdocs/site/docs/admin/web/index.html
index bd417768..a0e34127 100644
--- a/mkdocs/site/docs/admin/web/index.html
+++ b/mkdocs/site/docs/admin/web/index.html
@@ -2886,7 +2886,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2895,7 +2895,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3128,6 +3128,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/web/landing-pages/index.html b/mkdocs/site/docs/admin/web/landing-pages/index.html
index 38f2c534..e44fc97a 100644
--- a/mkdocs/site/docs/admin/web/landing-pages/index.html
+++ b/mkdocs/site/docs/admin/web/landing-pages/index.html
@@ -2988,7 +2988,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2997,7 +2997,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3238,6 +3238,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/admin/web/navigation/index.html b/mkdocs/site/docs/admin/web/navigation/index.html
index 581e923a..6649f8d8 100644
--- a/mkdocs/site/docs/admin/web/navigation/index.html
+++ b/mkdocs/site/docs/admin/web/navigation/index.html
@@ -3025,7 +3025,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3034,7 +3034,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3287,6 +3287,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/api/index.html b/mkdocs/site/docs/api/index.html
index c19b468a..796f6ce6 100644
--- a/mkdocs/site/docs/api/index.html
+++ b/mkdocs/site/docs/api/index.html
@@ -3131,7 +3131,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3140,7 +3140,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -6740,6 +6740,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/architecture/index.html b/mkdocs/site/docs/architecture/index.html
index bb007fd3..82020a59 100644
--- a/mkdocs/site/docs/architecture/index.html
+++ b/mkdocs/site/docs/architecture/index.html
@@ -2239,7 +2239,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2248,7 +2248,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -2742,6 +2742,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/deployment/index.html b/mkdocs/site/docs/deployment/index.html
index ca53d446..4b4cf086 100644
--- a/mkdocs/site/docs/deployment/index.html
+++ b/mkdocs/site/docs/deployment/index.html
@@ -2652,7 +2652,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2661,7 +2661,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3295,7 +3295,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
      Upgrading
      
 
      Pulling Updates
      
 
      # Pull latest code
-git pull origin v2
+git pull origin main
 
 # Rebuild and restart containers
 docker compose build api admin
@@ -3550,6 +3550,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/getting-started/control-panel/index.html b/mkdocs/site/docs/getting-started/control-panel/index.html
index a065324c..37c23589 100644
--- a/mkdocs/site/docs/getting-started/control-panel/index.html
+++ b/mkdocs/site/docs/getting-started/control-panel/index.html
@@ -3002,7 +3002,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3011,7 +3011,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3635,6 +3635,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/getting-started/environment-variables/index.html b/mkdocs/site/docs/getting-started/environment-variables/index.html
index c783074d..951aa568 100644
--- a/mkdocs/site/docs/getting-started/environment-variables/index.html
+++ b/mkdocs/site/docs/getting-started/environment-variables/index.html
@@ -3229,7 +3229,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3238,7 +3238,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3408,7 +3408,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 ENCRYPTION_KEY
 —
- AES key for encrypting secrets stored in the database (SMTP passwords, API keys, etc.). Generate with openssl rand -hex 32. Must not reuse a JWT secret. Required in production (NODE_ENV=production).
+ AES key for encrypting secrets stored in the database (SMTP passwords, API keys, etc.). Generate with openssl rand -hex 32. Must not reuse a JWT secret. Required in all environments (no longer falls back to JWT secret in development).
 
 
 
@@ -4103,14 +4103,9 @@ Then restart the API: docker compose restart api
      
 
 
 CODE_SERVER_URL
-http://code-server:8080
+http://code-server-changemaker:8443
 Internal container URL.
 
-
-USER_NAME
-coder
-User account inside the Code Server container.
-
 
 
 
      
@@ -4297,6 +4292,16 @@ Then restart the API: docker compose restart api
      
 8891
 Port for iframe embedding in admin.
 
+
+MONGO_ROOT_USER
+rocketchat
+MongoDB admin username.
+
+
+MONGO_ROOT_PASSWORD
+—
+ MongoDB admin password. MongoDB runs with --auth enabled.
+
 
 
 
      
@@ -4799,16 +4804,17 @@ Then restart the API: docker compose restart api
      
       # Vaultwarden
 echo "VAULTWARDEN_ADMIN_TOKEN=$(openssl rand -hex 32)"
 
-# Rocket.Chat
+# Rocket.Chat + MongoDB
 echo "ROCKETCHAT_ADMIN_PASSWORD=$(openssl rand -hex 16)"
-
-# Gancio
-echo "GANCIO_ADMIN_PASSWORD=$(openssl rand -hex 16)"
-
-# Jitsi Meet
-echo "JITSI_APP_SECRET=$(openssl rand -hex 32)"
-echo "JITSI_JICOFO_AUTH_PASSWORD=$(openssl rand -hex 16)"
-echo "JITSI_JVB_AUTH_PASSWORD=$(openssl rand -hex 16)"
+echo "MONGO_ROOT_PASSWORD=$(openssl rand -hex 24)"
+
+# Gancio
+echo "GANCIO_ADMIN_PASSWORD=$(openssl rand -hex 16)"
+
+# Jitsi Meet
+echo "JITSI_APP_SECRET=$(openssl rand -hex 32)"
+echo "JITSI_JICOFO_AUTH_PASSWORD=$(openssl rand -hex 16)"
+echo "JITSI_JVB_AUTH_PASSWORD=$(openssl rand -hex 16)"
 
      
 
      
 
      Tip
      
@@ -4850,16 +4856,17 @@ Then restart the API: docker compose restart api
      
 N8N_USER_PASSWORD=...
 VAULTWARDEN_ADMIN_TOKEN=...
 ROCKETCHAT_ADMIN_PASSWORD=...
-GANCIO_ADMIN_PASSWORD=...
-JITSI_APP_SECRET=...
-JITSI_JICOFO_AUTH_PASSWORD=...
-JITSI_JVB_AUTH_PASSWORD=...
-JVB_ADVERTISE_IP=your.public.ip.here
-EMAIL_TEST_MODE=false
-SMTP_HOST=smtp.your-provider.com
-SMTP_PORT=587
-SMTP_USER=you@example.com
-SMTP_PASS=your-smtp-password
+MONGO_ROOT_PASSWORD=...
+GANCIO_ADMIN_PASSWORD=...
+JITSI_APP_SECRET=...
+JITSI_JICOFO_AUTH_PASSWORD=...
+JITSI_JVB_AUTH_PASSWORD=...
+JVB_ADVERTISE_IP=your.public.ip.here
+EMAIL_TEST_MODE=false
+SMTP_HOST=smtp.your-provider.com
+SMTP_PORT=587
+SMTP_USER=you@example.com
+SMTP_PASS=your-smtp-password
    Start services
    docker compose up -d
 docker compose --profile monitoring up -d
@@ -5080,6 +5087,8 @@ Then restart the API: docker compose restart api
    
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/getting-started/features/index.html b/mkdocs/site/docs/getting-started/features/index.html
index 195628cc..d23d7ae5 100644
--- a/mkdocs/site/docs/getting-started/features/index.html
+++ b/mkdocs/site/docs/getting-started/features/index.html
@@ -2533,7 +2533,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2542,7 +2542,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -2974,6 +2974,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/getting-started/first-steps/index.html b/mkdocs/site/docs/getting-started/first-steps/index.html
index 6ff947cc..855e3792 100644
--- a/mkdocs/site/docs/getting-started/first-steps/index.html
+++ b/mkdocs/site/docs/getting-started/first-steps/index.html
@@ -2584,7 +2584,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2593,7 +2593,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -2878,6 +2878,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/getting-started/index.html b/mkdocs/site/docs/getting-started/index.html
index b1b21ecb..ddacdd8e 100644
--- a/mkdocs/site/docs/getting-started/index.html
+++ b/mkdocs/site/docs/getting-started/index.html
@@ -2423,7 +2423,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2432,7 +2432,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -2452,14 +2452,13 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
    Quick Install (Pre-built Images)
    
 
    The fastest way to deploy — no source code, no compilation:
    
-
    curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/v2/scripts/install.sh | bash
+
    curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/main/scripts/install.sh | bash
 
    
 
    This downloads a lightweight release package (~2 MB), runs the configuration wizard, and pulls pre-built Docker images. First startup takes ~2 minutes. See Installation for details.
    
 
    Quick Start (From Source)
    
 
    For development or customization, clone the full repository:
    
 
    git clone https://gitea.bnkops.com/admin/changemaker.lite
 cd changemaker.lite
-git checkout v2
 
    
 
    bash config.sh
 
    
@@ -2819,6 +2818,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/getting-started/installation/index.html b/mkdocs/site/docs/getting-started/installation/index.html
index 6747065e..631258a8 100644
--- a/mkdocs/site/docs/getting-started/installation/index.html
+++ b/mkdocs/site/docs/getting-started/installation/index.html
@@ -3067,7 +3067,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3076,7 +3076,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3099,7 +3099,6 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
    Clone the repository:
    
 
    git clone https://gitea.bnkops.com/admin/changemaker.lite
 cd changemaker.lite
-git checkout v2
 
    
 
    Run the configuration wizard:
    
 
    bash config.sh
@@ -3116,7 +3115,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
    Pre-built Image Installation
    
 
    For production deployments, you can skip cloning the source repository entirely. Pre-built Docker images are pulled from the Gitea container registry.
    
 
    One-Line Install
    
-
    curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/v2/scripts/install.sh | bash
+
    curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/main/scripts/install.sh | bash
 
    
 
    This script:
    
 
      
@@ -3816,6 +3815,8 @@ locally without Docker:
      
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/getting-started/services/index.html b/mkdocs/site/docs/getting-started/services/index.html
index 7ed429b5..1a13a7a3 100644
--- a/mkdocs/site/docs/getting-started/services/index.html
+++ b/mkdocs/site/docs/getting-started/services/index.html
@@ -2757,7 +2757,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2766,7 +2766,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3565,6 +3565,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/getting-started/upgrades/index.html b/mkdocs/site/docs/getting-started/upgrades/index.html
index fa291a87..ba5d9cb7 100644
--- a/mkdocs/site/docs/getting-started/upgrades/index.html
+++ b/mkdocs/site/docs/getting-started/upgrades/index.html
@@ -1643,6 +1643,17 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
   
   
+
+        
+          
    1. 
+  
+    
+      
+        Upgrade Results
+      
+    
+  
+  
 
      2. 
         
       
@@ -2660,6 +2671,17 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
   
   
+
+        
+          
    2. 
+  
+    
+      
+        Upgrade Results
+      
+    
+  
+  
 
      3. 
         
       
@@ -3008,7 +3030,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -3017,7 +3039,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -3062,6 +3084,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
    3. Click the System tab
      4. 
 
    4. Click Check for Updates
      5. 
 
    
+
    The System tab shows your current version, last commit message, and auto-upgrade settings:
    
+
    System tab initial state
    
 
    The system fetches from the git remote and shows:
    
 
      
 
    • Current commit hash and message
      • 
@@ -3069,6 +3093,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
    • Number of commits behind
      • 
 
    • Changelog of incoming changes
      • 
 
    
+
    When updates are available, the panel highlights how many commits are behind and lists the incoming changes:
    
+
    Update available notification
    
 
    Starting an Upgrade
    
 
      
 
    1. Review the changelog to understand what's changing
      2. 
@@ -3082,7 +3108,15 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
    2. Monitor the 6-phase progress indicator
      3. 
 
    
+
    Confirm System Upgrade dialog
    
 
    The GUI polls for progress updates and displays the current phase, percentage, and status message in real time.
    
+
    Upgrade Results
    
+
    After the upgrade completes, the System tab shows the result — including the new version, health check status, and any warnings:
    
+
    Upgrade success result
    
+
    
+
    Tip
    
+
    If health checks show warnings immediately after an upgrade, wait 1-2 minutes for services to fully start before investigating.
    
+
    
 
    
 
    The 6 Upgrade Phases
    
 
    Both the GUI and CLI methods execute the same 6-phase process:
    
@@ -3581,6 +3615,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/index.html b/mkdocs/site/docs/index.html
index e392ef9e..ef0ddef6 100644
--- a/mkdocs/site/docs/index.html
+++ b/mkdocs/site/docs/index.html
@@ -2137,7 +2137,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2146,7 +2146,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -2517,6 +2517,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/phil/index.html b/mkdocs/site/docs/phil/index.html
index 4d5479a5..a73b26ec 100644
--- a/mkdocs/site/docs/phil/index.html
+++ b/mkdocs/site/docs/phil/index.html
@@ -2325,7 +2325,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2334,7 +2334,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -2662,6 +2662,8 @@ Self-hosted doesn't have to mean self-excluding. Changemaker Lite is designed fo
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/services/index.html b/mkdocs/site/docs/services/index.html
index 90ed70f1..be57f339 100644
--- a/mkdocs/site/docs/services/index.html
+++ b/mkdocs/site/docs/services/index.html
@@ -2240,7 +2240,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2249,7 +2249,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -2921,6 +2921,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/troubleshooting/index.html b/mkdocs/site/docs/troubleshooting/index.html
index 03ccb446..17e8869e 100644
--- a/mkdocs/site/docs/troubleshooting/index.html
+++ b/mkdocs/site/docs/troubleshooting/index.html
@@ -2281,7 +2281,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2290,7 +2290,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -2673,6 +2673,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/user-guide/campaigns/index.html b/mkdocs/site/docs/user-guide/campaigns/index.html
index 86ef886f..5a357910 100644
--- a/mkdocs/site/docs/user-guide/campaigns/index.html
+++ b/mkdocs/site/docs/user-guide/campaigns/index.html
@@ -2549,7 +2549,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2558,7 +2558,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -2804,6 +2804,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/user-guide/donations/index.html b/mkdocs/site/docs/user-guide/donations/index.html
index acaa0d88..ac57f65e 100644
--- a/mkdocs/site/docs/user-guide/donations/index.html
+++ b/mkdocs/site/docs/user-guide/donations/index.html
@@ -2528,7 +2528,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2537,7 +2537,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -2783,6 +2783,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/user-guide/events/index.html b/mkdocs/site/docs/user-guide/events/index.html
index bf4fa2ac..6db21b92 100644
--- a/mkdocs/site/docs/user-guide/events/index.html
+++ b/mkdocs/site/docs/user-guide/events/index.html
@@ -2542,7 +2542,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2551,7 +2551,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -2799,6 +2799,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/user-guide/gallery/index.html b/mkdocs/site/docs/user-guide/gallery/index.html
index 2eb97411..48e8b18d 100644
--- a/mkdocs/site/docs/user-guide/gallery/index.html
+++ b/mkdocs/site/docs/user-guide/gallery/index.html
@@ -2549,7 +2549,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2558,7 +2558,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -2808,6 +2808,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/user-guide/index.html b/mkdocs/site/docs/user-guide/index.html
index 9ce65a96..a1878d12 100644
--- a/mkdocs/site/docs/user-guide/index.html
+++ b/mkdocs/site/docs/user-guide/index.html
@@ -2407,7 +2407,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2416,7 +2416,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -2684,6 +2684,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/user-guide/map/index.html b/mkdocs/site/docs/user-guide/map/index.html
index d8359e4d..cae765fe 100644
--- a/mkdocs/site/docs/user-guide/map/index.html
+++ b/mkdocs/site/docs/user-guide/map/index.html
@@ -2498,7 +2498,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2507,7 +2507,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -2742,6 +2742,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/user-guide/profile/index.html b/mkdocs/site/docs/user-guide/profile/index.html
index 461ba137..5fe51161 100644
--- a/mkdocs/site/docs/user-guide/profile/index.html
+++ b/mkdocs/site/docs/user-guide/profile/index.html
@@ -2572,7 +2572,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2581,7 +2581,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -2836,6 +2836,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/user-guide/shifts/index.html b/mkdocs/site/docs/user-guide/shifts/index.html
index c6066469..9d536f72 100644
--- a/mkdocs/site/docs/user-guide/shifts/index.html
+++ b/mkdocs/site/docs/user-guide/shifts/index.html
@@ -2542,7 +2542,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2551,7 +2551,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -2805,6 +2805,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/user-guide/shop/index.html b/mkdocs/site/docs/user-guide/shop/index.html
index f06947f3..e835d0ba 100644
--- a/mkdocs/site/docs/user-guide/shop/index.html
+++ b/mkdocs/site/docs/user-guide/shop/index.html
@@ -2528,7 +2528,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2537,7 +2537,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -2781,6 +2781,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/volunteer/achievements/index.html b/mkdocs/site/docs/volunteer/achievements/index.html
index c142a3a2..37412d4a 100644
--- a/mkdocs/site/docs/volunteer/achievements/index.html
+++ b/mkdocs/site/docs/volunteer/achievements/index.html
@@ -2566,7 +2566,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2575,7 +2575,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -2949,6 +2949,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/volunteer/canvassing/index.html b/mkdocs/site/docs/volunteer/canvassing/index.html
index 67cfc69a..1841ed53 100644
--- a/mkdocs/site/docs/volunteer/canvassing/index.html
+++ b/mkdocs/site/docs/volunteer/canvassing/index.html
@@ -2477,7 +2477,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2486,7 +2486,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -2751,6 +2751,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/volunteer/index.html b/mkdocs/site/docs/volunteer/index.html
index 3599bdb2..c4dcd736 100644
--- a/mkdocs/site/docs/volunteer/index.html
+++ b/mkdocs/site/docs/volunteer/index.html
@@ -2351,7 +2351,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2360,7 +2360,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -2617,6 +2617,8 @@ A: Visit the public shifts page at /shifts.
    
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/volunteer/shifts/index.html b/mkdocs/site/docs/volunteer/shifts/index.html
index c708f94d..bd1ec480 100644
--- a/mkdocs/site/docs/volunteer/shifts/index.html
+++ b/mkdocs/site/docs/volunteer/shifts/index.html
@@ -2392,7 +2392,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2401,7 +2401,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -2645,6 +2645,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/docs/volunteer/social/index.html b/mkdocs/site/docs/volunteer/social/index.html
index a1e636e8..1a46701a 100644
--- a/mkdocs/site/docs/volunteer/social/index.html
+++ b/mkdocs/site/docs/volunteer/social/index.html
@@ -2532,7 +2532,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -2541,7 +2541,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -2842,6 +2842,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/hooks/__pycache__/env_config_hook.cpython-311.pyc b/mkdocs/site/hooks/__pycache__/env_config_hook.cpython-311.pyc
index 0d11b807..c6df05c6 100644
Binary files a/mkdocs/site/hooks/__pycache__/env_config_hook.cpython-311.pyc and b/mkdocs/site/hooks/__pycache__/env_config_hook.cpython-311.pyc differ
diff --git a/mkdocs/site/hooks/__pycache__/repo_widget_hook.cpython-311.pyc b/mkdocs/site/hooks/__pycache__/repo_widget_hook.cpython-311.pyc
index 9bf58cc1..c610655e 100644
Binary files a/mkdocs/site/hooks/__pycache__/repo_widget_hook.cpython-311.pyc and b/mkdocs/site/hooks/__pycache__/repo_widget_hook.cpython-311.pyc differ
diff --git a/mkdocs/site/hooks/__pycache__/wikilinks_hook.cpython-311.pyc b/mkdocs/site/hooks/__pycache__/wikilinks_hook.cpython-311.pyc
index 3054014a..88bec183 100644
Binary files a/mkdocs/site/hooks/__pycache__/wikilinks_hook.cpython-311.pyc and b/mkdocs/site/hooks/__pycache__/wikilinks_hook.cpython-311.pyc differ
diff --git a/mkdocs/site/includes/abbreviations/index.html b/mkdocs/site/includes/abbreviations/index.html
index 7d91e953..aaef179a 100644
--- a/mkdocs/site/includes/abbreviations/index.html
+++ b/mkdocs/site/includes/abbreviations/index.html
@@ -1382,7 +1382,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -1391,7 +1391,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -1573,6 +1573,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/index.html b/mkdocs/site/index.html
index 4f77ba3c..c00fa490 100644
--- a/mkdocs/site/index.html
+++ b/mkdocs/site/index.html
@@ -92,6 +92,10 @@
     /* ============================================
        TYPOGRAPHY
        ============================================ */
+    html {
+        overflow-x: hidden;
+    }
+
     body {
         font-family: 'Inter', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
         color: var(--text-primary);
@@ -482,7 +486,7 @@
         flex-direction: column;
         align-items: center;
         justify-content: flex-start;
-        padding: calc(var(--header-height) + 3rem) 2rem 0;
+        padding: calc(var(--header-height) + 2rem) 2rem 0;
         overflow: hidden;
     }
 
@@ -510,6 +514,22 @@
         background: radial-gradient(circle, rgba(111, 66, 193, 0.08) 0%, rgba(139, 92, 246, 0.03) 40%, transparent 70%);
     }
 
+    [data-theme="light"] .showcase-card {
+        border-color: rgba(100, 116, 139, 0.2);
+    }
+    [data-theme="light"] .showcase-card.active {
+        box-shadow: 0 0 30px rgba(111, 66, 193, 0.08), 0 8px 32px rgba(0, 0, 0, 0.1);
+        border-color: rgba(111, 66, 193, 0.25);
+    }
+    [data-theme="light"] .hero-stats {
+        background: rgba(255, 255, 255, 0.9);
+        border-color: rgba(100, 116, 139, 0.15);
+    }
+    [data-theme="light"] .hero-pill {
+        background: rgba(111, 66, 193, 0.06);
+        border-color: rgba(111, 66, 193, 0.15);
+    }
+
     .hero-root-svg {
         position: absolute;
         top: 65%;
@@ -526,11 +546,38 @@
         to { opacity: 1; }
     }
 
+    /* ---- Two-column hero grid (desktop) ---- */
     .hero-content {
         position: relative;
         z-index: 1;
-        text-align: center;
-        max-width: 800px;
+        width: 100%;
+        max-width: 1400px;
+        display: grid;
+        grid-template-columns: minmax(380px, 1fr) minmax(0, 1.4fr);
+        grid-template-rows: auto auto;
+        gap: 0 2.5rem;
+        align-items: start;
+    }
+
+    .hero-left {
+        text-align: left;
+        padding-top: 1.5rem;
+    }
+
+    .hero-right {
+        display: flex;
+        align-items: flex-start;
+        justify-content: flex-end;
+        padding-top: 0.5rem;
+    }
+    .hero-right > div {
+        width: 100%;
+    }
+
+    /* Spans full width below both columns */
+    .hero-bottom {
+        grid-column: 1 / -1;
+        margin-top: 1.5rem;
     }
 
     .hero-badge {
@@ -543,38 +590,388 @@
         font-size: 0.8rem;
         font-weight: 600;
         letter-spacing: 0.02em;
+        margin-bottom: 1rem;
+    }
+
+    .beta-pill {
+        display: inline-block;
+        padding: 0.35rem 1.1rem;
+        background: linear-gradient(135deg, #EC4899, #8B5CF6);
+        border: none;
+        border-radius: 100px;
+        color: #fff;
+        font-size: 0.78rem;
+        font-weight: 700;
+        letter-spacing: 0.04em;
+        cursor: pointer;
+        margin-bottom: 0.75rem;
+        box-shadow: 0 0 16px rgba(236, 72, 153, 0.4), 0 0 40px rgba(139, 92, 246, 0.2);
+        transition: transform 0.2s ease, box-shadow 0.2s ease;
+        animation: beta-pulse 3s ease-in-out infinite;
+    }
+    .beta-pill:hover {
+        transform: scale(1.06);
+        box-shadow: 0 0 22px rgba(236, 72, 153, 0.55), 0 0 50px rgba(139, 92, 246, 0.35);
+    }
+    @keyframes beta-pulse {
+        0%, 100% { box-shadow: 0 0 16px rgba(236, 72, 153, 0.4), 0 0 40px rgba(139, 92, 246, 0.2); }
+        50% { box-shadow: 0 0 24px rgba(236, 72, 153, 0.6), 0 0 55px rgba(139, 92, 246, 0.35); }
+    }
+
+    .beta-modal-backdrop {
+        display: none;
+        position: fixed;
+        inset: 0;
+        z-index: 9999;
+        background: rgba(0, 0, 0, 0.6);
+        backdrop-filter: blur(4px);
+        -webkit-backdrop-filter: blur(4px);
+        align-items: center;
+        justify-content: center;
+    }
+    .beta-modal-backdrop.open { display: flex; }
+    .beta-modal {
+        background: var(--bg-surface);
+        border: 1px solid var(--myc-node-border);
+        border-radius: var(--radius-lg);
+        max-width: 440px;
+        width: 90%;
+        padding: 2.5rem 2rem 2rem;
+        text-align: center;
+        box-shadow: var(--shadow-lg), 0 0 60px rgba(139, 92, 246, 0.15);
+        position: relative;
+        animation: beta-modal-in 0.25s ease-out;
+    }
+    @keyframes beta-modal-in {
+        from { opacity: 0; transform: scale(0.92) translateY(12px); }
+        to { opacity: 1; transform: scale(1) translateY(0); }
+    }
+    .beta-modal-emoji { font-size: 2.5rem; margin-bottom: 1rem; }
+    .beta-modal h3 {
+        font-size: 1.25rem;
+        color: var(--text-primary);
+        margin-bottom: 0.75rem;
+    }
+    .beta-modal p {
+        color: var(--text-secondary);
+        font-size: 0.95rem;
+        line-height: 1.7;
         margin-bottom: 1.5rem;
     }
+    .beta-modal-close {
+        display: inline-block;
+        padding: 0.5rem 1.5rem;
+        background: linear-gradient(135deg, #8B5CF6, #6f42c1);
+        border: none;
+        border-radius: 100px;
+        color: #fff;
+        font-size: 0.85rem;
+        font-weight: 600;
+        cursor: pointer;
+        transition: transform 0.15s ease, box-shadow 0.15s ease;
+    }
+    .beta-modal-close:hover {
+        transform: scale(1.04);
+        box-shadow: 0 0 14px rgba(139, 92, 246, 0.4);
+    }
 
     .hero h1 {
         background: linear-gradient(135deg, var(--primary-light) 0%, #C084FC 50%, #F5A9B8 100%);
         -webkit-background-clip: text;
         -webkit-text-fill-color: transparent;
         background-clip: text;
+        margin-bottom: 0.5rem;
+        font-size: clamp(2.5rem, 5vw, 3.75rem);
+    }
+
+    /* ---- Typewriter rotating line ---- */
+    .hero-rotating-line {
+        font-size: clamp(1.15rem, 2.2vw, 1.5rem);
+        color: var(--text-secondary);
         margin-bottom: 1.25rem;
+        min-height: 2.2em;
+        line-height: 1.5;
+    }
+    .hero-rotating-line .tw-static {
+        color: var(--text-secondary);
+    }
+    .hero-rotating-line .tw-word {
+        color: var(--primary-light);
+        font-weight: 700;
+        border-right: 2px solid var(--primary-light);
+        padding-right: 2px;
+        animation: blink-cursor 0.75s step-end infinite;
+    }
+    @keyframes blink-cursor {
+        50% { border-color: transparent; }
     }
 
     .hero-subtitle {
         color: var(--text-secondary);
-        font-size: clamp(1rem, 2vw, 1.2rem);
-        max-width: 640px;
-        margin: 0 auto 2rem;
+        font-size: clamp(0.95rem, 1.8vw, 1.1rem);
+        max-width: 540px;
+        margin: 0 0 1.5rem;
         line-height: 1.7;
     }
 
     .hero-cta {
         display: flex;
-        gap: 1rem;
-        justify-content: center;
+        gap: 0.75rem;
         flex-wrap: wrap;
-        margin-bottom: 2.5rem;
+        margin-bottom: 1.5rem;
     }
 
-    /* Search */
-    .hero-search {
+    /* ---- Feature pills ---- */
+    .hero-pills {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 0.5rem;
+        margin-bottom: 1.5rem;
+    }
+    .hero-pill {
+        display: inline-flex;
+        align-items: center;
+        gap: 0.35rem;
+        padding: 0.3rem 0.75rem;
+        background: var(--myc-node-bg);
+        border: 1px solid var(--myc-node-border);
+        border-radius: 100px;
+        color: var(--text-secondary);
+        font-size: 0.72rem;
+        font-weight: 500;
+        letter-spacing: 0.01em;
+        opacity: 0;
+        transform: translateY(8px);
+        transition: opacity 0.4s ease, transform 0.4s ease, background 0.2s ease;
+    }
+    .hero-pill.visible {
+        opacity: 1;
+        transform: translateY(0);
+    }
+    .hero-pill:hover {
+        background: rgba(139, 92, 246, 0.15);
+        color: var(--primary-light);
+        text-decoration: none;
+    }
+    .hero-pill .pill-icon {
+        font-size: 0.82rem;
+        line-height: 1;
+    }
+
+    /* ---- Feature showcase (right column) ---- */
+    .hero-showcase {
         position: relative;
-        max-width: 520px;
-        margin: 0 auto 3rem;
+        width: 100%;
+        aspect-ratio: 16 / 9.5;
+        perspective: 1200px;
+    }
+
+    .showcase-card {
+        position: absolute;
+        inset: 0;
+        border: 1px solid var(--border-color);
+        border-radius: var(--radius-lg);
+        display: flex;
+        flex-direction: column;
+        opacity: 0;
+        transform: rotateY(8deg) translateX(30px) scale(0.95);
+        transition: opacity 0.6s ease, transform 0.6s ease;
+        pointer-events: none;
+        overflow: hidden;
+    }
+    .showcase-card.active {
+        opacity: 1;
+        transform: rotateY(0deg) translateX(0) scale(1);
+        pointer-events: auto;
+        border-color: var(--myc-node-border);
+        box-shadow: 0 0 30px rgba(139, 92, 246, 0.12), var(--shadow-lg);
+    }
+    .showcase-card.exiting {
+        opacity: 0;
+        transform: rotateY(-8deg) translateX(-30px) scale(0.95);
+    }
+
+    /* Screenshot image fills the card */
+    .showcase-card-img {
+        width: 100%;
+        height: 100%;
+        object-fit: cover;
+        object-position: top left;
+        display: block;
+    }
+
+    /* Caption overlay at bottom */
+    .showcase-card-caption {
+        position: absolute;
+        bottom: 0;
+        left: 0;
+        right: 0;
+        padding: 2.5rem 1.25rem 1rem;
+        background: linear-gradient(to top, rgba(15, 23, 42, 0.95) 0%, rgba(15, 23, 42, 0.75) 50%, transparent 100%);
+        display: flex;
+        align-items: flex-end;
+        gap: 0.75rem;
+    }
+    [data-theme="light"] .showcase-card-caption {
+        background: linear-gradient(to top, rgba(255, 255, 255, 0.97) 0%, rgba(255, 255, 255, 0.8) 50%, transparent 100%);
+    }
+    .showcase-card-icon {
+        width: 36px;
+        height: 36px;
+        border-radius: 8px;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        font-size: 1.1rem;
+        flex-shrink: 0;
+        backdrop-filter: blur(4px);
+        -webkit-backdrop-filter: blur(4px);
+    }
+    .showcase-card-title {
+        font-size: 0.95rem;
+        font-weight: 700;
+        color: #F1F5F9;
+        line-height: 1.3;
+    }
+    [data-theme="light"] .showcase-card-title {
+        color: #0F172A;
+    }
+    .showcase-card-subtitle {
+        font-size: 0.72rem;
+        color: #94A3B8;
+        margin-top: 0.1rem;
+    }
+    [data-theme="light"] .showcase-card-subtitle {
+        color: #64748B;
+    }
+
+    /* Showcase progress dots */
+    .showcase-dots {
+        display: flex;
+        justify-content: center;
+        gap: 0.5rem;
+        margin-top: 0.75rem;
+    }
+    .showcase-dot {
+        width: 8px;
+        height: 8px;
+        border-radius: 50%;
+        background: var(--text-muted);
+        opacity: 0.3;
+        cursor: pointer;
+        transition: opacity 0.3s ease, transform 0.3s ease, background 0.3s ease;
+    }
+    .showcase-dot.active {
+        opacity: 1;
+        background: var(--primary-light);
+        transform: scale(1.3);
+    }
+    .showcase-dot:hover {
+        opacity: 0.7;
+    }
+
+    /* ---- Particle canvas ---- */
+    .hero-particles {
+        position: absolute;
+        inset: 0;
+        z-index: 0;
+        pointer-events: none;
+    }
+
+    /* ---- Quick deploy terminal ---- */
+    .hero-terminal {
+        margin: 0.75rem 0 0;
+        background: #0D1117;
+        border: 1px solid rgba(139, 92, 246, 0.2);
+        border-radius: var(--radius);
+        opacity: 0;
+        transform: translateY(8px);
+        animation: fadeSlideIn 0.6s ease 1.4s forwards;
+    }
+    @keyframes fadeSlideIn {
+        to { opacity: 1; transform: translateY(0); }
+    }
+    [data-theme="light"] .hero-terminal {
+        background: #1E293B;
+    }
+    .hero-terminal-bar {
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+        padding: 0.5rem 0.85rem;
+        background: rgba(255, 255, 255, 0.04);
+        border-bottom: 1px solid rgba(255, 255, 255, 0.06);
+        border-radius: var(--radius) var(--radius) 0 0;
+    }
+    .hero-terminal-dot {
+        width: 8px;
+        height: 8px;
+        border-radius: 50%;
+    }
+    .hero-terminal-title {
+        font-size: 0.65rem;
+        color: #64748B;
+        font-family: 'SF Mono', 'Fira Code', 'Cascadia Code', monospace;
+        margin-left: auto;
+    }
+    .hero-terminal-body {
+        padding: 0.6rem 0.85rem;
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+    }
+    .hero-terminal-prompt {
+        color: #34D399;
+        font-family: 'SF Mono', 'Fira Code', 'Cascadia Code', monospace;
+        font-size: 0.82rem;
+        font-weight: 600;
+        flex-shrink: 0;
+        user-select: none;
+    }
+    .hero-terminal-cmd {
+        color: #E2E8F0;
+        font-family: 'SF Mono', 'Fira Code', 'Cascadia Code', monospace;
+        font-size: 0.82rem;
+        white-space: nowrap;
+        overflow-x: auto;
+        overflow-y: hidden;
+        flex: 1;
+        min-width: 0;
+        scrollbar-width: none;
+        -ms-overflow-style: none;
+    }
+    .hero-terminal-cmd::-webkit-scrollbar { display: none; }
+    .hero-terminal-cmd .cmd-highlight {
+        color: var(--primary-light);
+    }
+    .hero-terminal-copy {
+        background: none;
+        border: 1px solid rgba(148, 163, 184, 0.2);
+        border-radius: 6px;
+        color: #94A3B8;
+        font-size: 0.7rem;
+        padding: 0.25rem 0.55rem;
+        cursor: pointer;
+        font-family: inherit;
+        transition: color 0.2s ease, border-color 0.2s ease, background 0.2s ease;
+        flex-shrink: 0;
+        display: flex;
+        align-items: center;
+        gap: 0.3rem;
+    }
+    .hero-terminal-copy:hover {
+        color: #E2E8F0;
+        border-color: rgba(148, 163, 184, 0.4);
+        background: rgba(255, 255, 255, 0.05);
+    }
+    .hero-terminal-copy.copied {
+        color: #34D399;
+        border-color: rgba(52, 211, 153, 0.3);
+    }
+
+    /* Search (moved out of hero, kept for search functionality) */
+    .hero-search {
+        display: none;
     }
 
     .search-input-wrap {
@@ -699,8 +1096,14 @@
         display: grid;
         grid-template-columns: repeat(4, 1fr);
         gap: 1.5rem;
-        max-width: 640px;
+        max-width: 800px;
         margin: 0 auto;
+        padding: 1.25rem 2rem;
+        background: var(--bg-card);
+        border: 1px solid var(--border-color);
+        border-radius: var(--radius);
+        backdrop-filter: blur(8px);
+        -webkit-backdrop-filter: blur(8px);
     }
 
     .hero-stat {
@@ -708,9 +1111,10 @@
     }
 
     .hero-stat-value {
-        font-size: 1.5rem;
+        font-size: 1.6rem;
         font-weight: 800;
         color: var(--primary-light);
+        font-variant-numeric: tabular-nums;
     }
 
     .hero-stat-label {
@@ -719,6 +1123,24 @@
         margin-top: 0.25rem;
     }
 
+    .hero-trust {
+        text-align: center;
+        margin-top: 1rem;
+        color: var(--text-muted);
+        font-size: 0.78rem;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        gap: 0.5rem;
+        opacity: 0;
+        animation: fadeIn 1s ease 1.5s forwards;
+    }
+    .hero-trust svg {
+        width: 14px;
+        height: 14px;
+        color: var(--primary-light);
+    }
+
     /* ============================================
        PROBLEMS SECTION
        ============================================ */
@@ -1746,16 +2168,41 @@
     @media (max-width: 768px) {
         .nav-links { display: none; }
         .nav-right .btn-primary { display: none; }
+        .nav-right .btn-demo { display: none; }
         .hamburger { display: block; }
         .logo-tagline { display: none; }
 
         .section { padding: 4rem 0; }
 
-        .hero { min-height: auto; padding-top: calc(var(--header-height) + 2rem); padding-bottom: 3rem; }
+        .hero { min-height: auto; padding-top: calc(var(--header-height) + 1.5rem); padding-bottom: 1.5rem; overflow-x: hidden; }
         .hero h1 { font-size: 2rem; }
         .hero-root-glow { width: 250px; height: 250px; top: 50%; bottom: auto; }
         .hero-root-svg { top: 50%; bottom: auto; transform: translate(-50%, -50%); width: 250px; height: 250px; }
 
+        .hero-content {
+            display: flex;
+            flex-direction: column;
+            max-width: 100%;
+            width: 100%;
+            overflow: hidden;
+        }
+        .hero-left { text-align: center; padding-top: 0; }
+        .hero-right { margin-top: 1.5rem; overflow: hidden; width: 100%; }
+        .hero-right > div { max-width: 100%; overflow: hidden; width: 100%; }
+        .hero-showcase { width: 100%; max-width: 100%; }
+        .hero-terminal { width: 100%; max-width: 100%; box-sizing: border-box; }
+        .hero-showcase { aspect-ratio: 16 / 10; }
+        .hero-cta { justify-content: center; }
+        .hero-pills { justify-content: center; }
+        .hero-terminal { max-width: 100%; overflow: hidden; }
+        .hero-terminal-body { padding: 0.5rem 0.7rem; gap: 0.4rem; }
+        .hero-terminal-prompt { font-size: 0.7rem; }
+        .hero-terminal-cmd { font-size: 0.65rem; }
+        .hero-terminal-copy { font-size: 0.62rem; padding: 0.2rem 0.4rem; }
+        .hero-terminal-copy .copy-label { display: none; }
+        .hero-rotating-line { text-align: center; }
+        .hero-subtitle { margin-left: auto; margin-right: auto; }
+
         .hero-stats {
             grid-template-columns: repeat(2, 1fr);
             gap: 1rem;
@@ -1798,6 +2245,8 @@
             flex-direction: column;
             align-items: center;
         }
+        .hero-pills { gap: 0.4rem; }
+        .hero-pill { font-size: 0.68rem; padding: 0.25rem 0.6rem; }
 
         .cta-buttons {
             flex-direction: column;
@@ -1818,7 +2267,15 @@
         .hero { padding-left: 1rem; padding-right: 1rem; }
         .section { padding: 3rem 0; }
         .section-header { margin-bottom: 2.5rem; }
-        .hero-stats { grid-template-columns: repeat(2, 1fr); }
+        .hero-stats { grid-template-columns: repeat(2, 1fr); padding: 1rem; }
+        .hero-showcase { aspect-ratio: 16 / 11; }
+        .showcase-card-title { font-size: 0.85rem; }
+        .showcase-card-subtitle { font-size: 0.65rem; }
+        .showcase-card-caption { padding: 1.5rem 1rem 0.75rem; }
+        .hero-terminal-cmd { font-size: 0.58rem; }
+        .hero-terminal-prompt { font-size: 0.6rem; }
+        .hero-terminal-title { font-size: 0.55rem; }
+        .hero-terminal-dot { width: 6px; height: 6px; }
         .live-stats { grid-template-columns: 1fr; }
     }
 
@@ -2115,72 +2572,175 @@
      HERO
      ============================================ -->
 
    
+    
+    
+
     
     
    
         
    
         
-        
     
    
 
     
    
-        
    Self-Hosted Campaign Infrastructure
    
-        
    Grow Power.
    Don't Rent It.
    
-        
    
-            Run your campaigns, canvassing, fundraising, team chat, media, and more — all on your own infrastructure.
-            No corporate surveillance. No foreign interference. No monthly ransoms.
-            A free* and open source toolkit built for growing political movements.
-        
    
-        
    
-            Explore the Demo 
-            Schedule a Chat
-            Source Code
+        
+        
    
+            
+            
    Self-Hosted Campaign Infrastructure
    
+            
    Grow Power.
    Don't Rent It.
    
+
+            
    
+                Your  — on your own infrastructure.
+            
    
+
+            
    
+                No corporate surveillance. No foreign interference. No monthly ransoms.
+                A free* and open source toolkit built for growing political movements.
+            
    
+
+            
    
+                Explore the Demo 
+                Schedule a Chat
+                Source Code
+            
    
+
+            
+            
+
         
    
 
-        
-        
    
-            
    
-                
-                
-                
-            
    
-            
    
-                
    
-                    
-                    
+        
+        
    
+            
    
+                
    
+                    
+                    
    
+                        Advocacy campaigns dashboard showing campaign list with status badges, email counts, and response tracking
+                        
    
+                            
    ✉
    
+                            
    
+                                
    Advocacy Campaigns
    
+                                
    Email your representatives in 3 clicks
    
+                            
    
+                        
    
+                    
    
+
+                    
+                    
    
+                        Canvassing dashboard with live volunteer map, cut progress tracking, and activity feed
+                        
    
+                            
    🌎
    
+                            
    
+                                
    GPS Canvassing
    
+                                
    Track door-to-door outreach in real time
    
+                            
    
+                        
    
+                    
    
+
+                    
+                    
    
+                        Media library with video thumbnails, filters, and publishing controls
+                        
    
+                            
    🎥
    
+                            
    
+                                
    Media Library
    
+                                
    Host, schedule, and share your campaign videos
    
+                            
    
+                        
    
+                    
    
+
+                    
+                    
    
+                        Shift management dashboard with stats, table view, and volunteer signups
+                        
    
+                            
    📅
    
+                            
    
+                                
    Volunteer Management
    
+                                
    Coordinate shifts, track attendance, grow your team
    
+                            
    
+                        
    
+                    
    
+                
    
+                
    
+                    
+                    
+                    
+                    
+                
    
+
+                
+                
    
+                    
    
+                        
+                        
+                        
+                        Quick Deploy on Linux w/ Docker
+                    
    
+                    
    
+                        $
+                        curl -fsSL gitea.bnkops.com/admin/changemaker.lite/raw/branch/main/scripts/install.sh | bash
+                        
+                    
    
                 
    
-                
    
             
    
         
    
 
-        
    
-            
    
-                
    100%
    
-                
    Data Ownership
    
+        
+        
    
+            
    
+                
    
+                    
    0%
    
+                    
    Data Ownership
    
+                
    
+                
    
+                    
    $0
    
+                    
    Self-Hosted
    
+                
    
+                
    
+                    
    0+
    
+                    
    Integrated Tools
    
+                
    
+                
    
+                    
    FOSS
    
+                    
    Open Source
    
+                
    
             
    
-            
    
-                
    $0
    
-                
    Self-Hosted
    
-            
    
-            
    
-                
    45+
    
-                
    Integrated Tools
    
-            
    
-            
    
-                
    FOSS
    
-                
    Open Source
    
+            
    
+                
+                Self-hosted by community organizers across Canada
             
    
         
    
     
    
 
    
 
+
+
    
+    
    
+        
    🚧
    
+        
    Now in Beta
    
+        
    Changemaker Lite is under active development and breaking changes are still being pushed. A stable release is expected by June 2026.
    
+        
+    
    
+
    
+
 
@@ -2287,7 +2847,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
    📨
    
                 
    
@@ -2376,7 +2936,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
    🗺
    
                 
    
@@ -2461,7 +3021,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
    🎬
    
                 
    
@@ -2550,7 +3110,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
    📊
    
                 
    
@@ -2621,7 +3181,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
    🛡
    
                 
    
@@ -2697,7 +3257,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
    💳
    
                 
    
@@ -2768,7 +3328,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
                 
    
@@ -2830,7 +3390,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
    🇨🇦
    
                 
    
@@ -3864,6 +4424,275 @@
         }
     };
 
+    /* ===========================================
+       BETA MODAL
+       =========================================== */
+    const BetaModal = {
+        init() {
+            const pill = document.getElementById('beta-pill');
+            const backdrop = document.getElementById('beta-modal-backdrop');
+            const closeBtn = document.getElementById('beta-modal-close');
+            if (!pill || !backdrop || !closeBtn) return;
+            pill.addEventListener('click', () => backdrop.classList.add('open'));
+            closeBtn.addEventListener('click', () => backdrop.classList.remove('open'));
+            backdrop.addEventListener('click', (e) => { if (e.target === backdrop) backdrop.classList.remove('open'); });
+            document.addEventListener('keydown', (e) => { if (e.key === 'Escape' && backdrop.classList.contains('open')) backdrop.classList.remove('open'); });
+        }
+    };
+
+    /* ===========================================
+       TERMINAL COPY — clipboard for install cmd
+       =========================================== */
+    const TerminalCopy = {
+        init() {
+            const btn = document.getElementById('hero-copy-btn');
+            if (!btn) return;
+            btn.addEventListener('click', () => {
+                const cmd = 'curl -fsSL gitea.bnkops.com/admin/changemaker.lite/raw/branch/main/scripts/install.sh | bash';
+                navigator.clipboard.writeText(cmd).then(() => {
+                    btn.classList.add('copied');
+                    btn.querySelector('.copy-label').textContent = 'Copied!';
+                    setTimeout(() => {
+                        btn.classList.remove('copied');
+                        btn.querySelector('.copy-label').textContent = 'Copy';
+                    }, 2000);
+                });
+            });
+        }
+    };
+
+    /* ===========================================
+       TYPEWRITER — rotating hero words
+       =========================================== */
+    const Typewriter = {
+        words: ['campaigns', 'canvassing', 'fundraising', 'newsletters', 'media library', 'volunteer shifts', 'team chat', 'events'],
+        el: null,
+        wordIdx: 0,
+        charIdx: 0,
+        isDeleting: false,
+        timeout: null,
+
+        init() {
+            this.el = document.getElementById('tw-word');
+            if (!this.el) return;
+            if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+                this.el.textContent = this.words[0];
+                return;
+            }
+            this.tick();
+        },
+
+        tick() {
+            const word = this.words[this.wordIdx];
+
+            if (this.isDeleting) {
+                this.charIdx--;
+            } else {
+                this.charIdx++;
+            }
+
+            this.el.textContent = word.substring(0, this.charIdx);
+
+            let delay = this.isDeleting ? 40 : 80;
+
+            if (!this.isDeleting && this.charIdx === word.length) {
+                delay = 2200;
+                this.isDeleting = true;
+            } else if (this.isDeleting && this.charIdx === 0) {
+                this.isDeleting = false;
+                this.wordIdx = (this.wordIdx + 1) % this.words.length;
+                delay = 400;
+            }
+
+            this.timeout = setTimeout(() => this.tick(), delay);
+        }
+    };
+
+    /* ===========================================
+       FEATURE PILLS — staggered entrance
+       =========================================== */
+    const FeaturePills = {
+        init() {
+            const pills = document.querySelectorAll('.hero-pill');
+            if (!pills.length) return;
+            if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+                pills.forEach(p => p.classList.add('visible'));
+                return;
+            }
+            pills.forEach((pill, i) => {
+                setTimeout(() => pill.classList.add('visible'), 600 + i * 120);
+            });
+        }
+    };
+
+    /* ===========================================
+       FEATURE SHOWCASE — rotating cards
+       =========================================== */
+    const FeatureShowcase = {
+        current: 0,
+        cards: [],
+        dots: [],
+        interval: null,
+        DURATION: 5000,
+
+        init() {
+            this.cards = document.querySelectorAll('.showcase-card');
+            this.dots = document.querySelectorAll('.showcase-dot');
+            if (this.cards.length < 2) return;
+
+            this.dots.forEach(dot => {
+                dot.addEventListener('click', () => {
+                    const idx = parseInt(dot.getAttribute('data-idx'), 10);
+                    if (idx !== this.current) this.goTo(idx);
+                });
+            });
+
+            this.startAutoplay();
+        },
+
+        goTo(idx) {
+            const prev = this.cards[this.current];
+            prev.classList.remove('active');
+            prev.classList.add('exiting');
+            setTimeout(() => prev.classList.remove('exiting'), 600);
+
+            this.current = idx;
+            this.cards[this.current].classList.add('active');
+
+            this.dots.forEach((d, i) => d.classList.toggle('active', i === idx));
+            this.restartAutoplay();
+        },
+
+        next() {
+            this.goTo((this.current + 1) % this.cards.length);
+        },
+
+        startAutoplay() {
+            this.interval = setInterval(() => this.next(), this.DURATION);
+        },
+
+        restartAutoplay() {
+            clearInterval(this.interval);
+            this.startAutoplay();
+        }
+    };
+
+    /* ===========================================
+       COUNT-UP STATS — animated number counters
+       =========================================== */
+    const CountUpStats = {
+        init() {
+            const stats = document.querySelectorAll('.hero-stat-value[data-count]');
+            if (!stats.length) return;
+            if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+                stats.forEach(el => {
+                    const target = parseInt(el.getAttribute('data-count'), 10);
+                    const prefix = el.getAttribute('data-prefix') || '';
+                    const suffix = el.getAttribute('data-suffix') || '';
+                    el.textContent = prefix + target + suffix;
+                });
+                return;
+            }
+
+            const obs = new IntersectionObserver((entries) => {
+                entries.forEach(entry => {
+                    if (entry.isIntersecting) {
+                        this.animate(entry.target);
+                        obs.unobserve(entry.target);
+                    }
+                });
+            }, { threshold: 0.5 });
+
+            stats.forEach(el => obs.observe(el));
+        },
+
+        animate(el) {
+            const target = parseInt(el.getAttribute('data-count'), 10);
+            const prefix = el.getAttribute('data-prefix') || '';
+            const suffix = el.getAttribute('data-suffix') || '';
+            const duration = 1400;
+            const start = performance.now();
+
+            const step = (now) => {
+                const progress = Math.min((now - start) / duration, 1);
+                const eased = 1 - Math.pow(1 - progress, 3);
+                const current = Math.round(eased * target);
+                el.textContent = prefix + current + suffix;
+                if (progress < 1) requestAnimationFrame(step);
+            };
+            requestAnimationFrame(step);
+        }
+    };
+
+    /* ===========================================
+       PARTICLE DRIFT — floating background dots
+       =========================================== */
+    const ParticleDrift = {
+        canvas: null,
+        ctx: null,
+        particles: [],
+        raf: null,
+        COUNT: 35,
+
+        init() {
+            this.canvas = document.getElementById('hero-particles');
+            if (!this.canvas) return;
+            if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return;
+            // Fewer particles on mobile
+            if (window.innerWidth < 768) this.COUNT = 15;
+
+            this.ctx = this.canvas.getContext('2d');
+            this.resize();
+            this.createParticles();
+            this.loop();
+            window.addEventListener('resize', () => this.resize());
+        },
+
+        resize() {
+            const hero = this.canvas.parentElement;
+            this.canvas.width = hero.offsetWidth;
+            this.canvas.height = hero.offsetHeight;
+        },
+
+        createParticles() {
+            this.particles = [];
+            for (let i = 0; i < this.COUNT; i++) {
+                this.particles.push({
+                    x: Math.random() * this.canvas.width,
+                    y: Math.random() * this.canvas.height,
+                    r: Math.random() * 2 + 0.5,
+                    vx: (Math.random() - 0.5) * 0.3,
+                    vy: -(Math.random() * 0.4 + 0.1),
+                    alpha: Math.random() * 0.3 + 0.1,
+                });
+            }
+        },
+
+        loop() {
+            const { ctx, canvas, particles } = this;
+            ctx.clearRect(0, 0, canvas.width, canvas.height);
+
+            const isDark = document.documentElement.getAttribute('data-theme') !== 'light';
+            const baseColor = isDark ? '139, 92, 246' : '111, 66, 193';
+
+            particles.forEach(p => {
+                p.x += p.vx;
+                p.y += p.vy;
+                // Wrap around
+                if (p.y < -5) { p.y = canvas.height + 5; p.x = Math.random() * canvas.width; }
+                if (p.x < -5) p.x = canvas.width + 5;
+                if (p.x > canvas.width + 5) p.x = -5;
+
+                ctx.beginPath();
+                ctx.arc(p.x, p.y, p.r, 0, Math.PI * 2);
+                ctx.fillStyle = `rgba(${baseColor}, ${p.alpha})`;
+                ctx.fill();
+            });
+
+            this.raf = requestAnimationFrame(() => this.loop());
+        }
+    };
+
     /* ===========================================
        BOOT
        =========================================== */
@@ -3877,7 +4706,14 @@
         FloatingElements.init();
         SmoothScroll.init();
         FreeModal.init();
+        BetaModal.init();
         initSearch();
+        TerminalCopy.init();
+        Typewriter.init();
+        FeaturePills.init();
+        FeatureShowcase.init();
+        CountUpStats.init();
+        ParticleDrift.init();
     });
 
 })();
diff --git a/mkdocs/site/lander/index.html b/mkdocs/site/lander/index.html
index 74a960ff..e7af9a76 100644
--- a/mkdocs/site/lander/index.html
+++ b/mkdocs/site/lander/index.html
@@ -92,6 +92,10 @@
     /* ============================================
        TYPOGRAPHY
        ============================================ */
+    html {
+        overflow-x: hidden;
+    }
+
     body {
         font-family: 'Inter', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
         color: var(--text-primary);
@@ -482,7 +486,7 @@
         flex-direction: column;
         align-items: center;
         justify-content: flex-start;
-        padding: calc(var(--header-height) + 3rem) 2rem 0;
+        padding: calc(var(--header-height) + 2rem) 2rem 0;
         overflow: hidden;
     }
 
@@ -510,6 +514,22 @@
         background: radial-gradient(circle, rgba(111, 66, 193, 0.08) 0%, rgba(139, 92, 246, 0.03) 40%, transparent 70%);
     }
 
+    [data-theme="light"] .showcase-card {
+        border-color: rgba(100, 116, 139, 0.2);
+    }
+    [data-theme="light"] .showcase-card.active {
+        box-shadow: 0 0 30px rgba(111, 66, 193, 0.08), 0 8px 32px rgba(0, 0, 0, 0.1);
+        border-color: rgba(111, 66, 193, 0.25);
+    }
+    [data-theme="light"] .hero-stats {
+        background: rgba(255, 255, 255, 0.9);
+        border-color: rgba(100, 116, 139, 0.15);
+    }
+    [data-theme="light"] .hero-pill {
+        background: rgba(111, 66, 193, 0.06);
+        border-color: rgba(111, 66, 193, 0.15);
+    }
+
     .hero-root-svg {
         position: absolute;
         top: 65%;
@@ -526,11 +546,38 @@
         to { opacity: 1; }
     }
 
+    /* ---- Two-column hero grid (desktop) ---- */
     .hero-content {
         position: relative;
         z-index: 1;
-        text-align: center;
-        max-width: 800px;
+        width: 100%;
+        max-width: 1400px;
+        display: grid;
+        grid-template-columns: minmax(380px, 1fr) minmax(0, 1.4fr);
+        grid-template-rows: auto auto;
+        gap: 0 2.5rem;
+        align-items: start;
+    }
+
+    .hero-left {
+        text-align: left;
+        padding-top: 1.5rem;
+    }
+
+    .hero-right {
+        display: flex;
+        align-items: flex-start;
+        justify-content: flex-end;
+        padding-top: 0.5rem;
+    }
+    .hero-right > div {
+        width: 100%;
+    }
+
+    /* Spans full width below both columns */
+    .hero-bottom {
+        grid-column: 1 / -1;
+        margin-top: 1.5rem;
     }
 
     .hero-badge {
@@ -543,38 +590,388 @@
         font-size: 0.8rem;
         font-weight: 600;
         letter-spacing: 0.02em;
+        margin-bottom: 1rem;
+    }
+
+    .beta-pill {
+        display: inline-block;
+        padding: 0.35rem 1.1rem;
+        background: linear-gradient(135deg, #EC4899, #8B5CF6);
+        border: none;
+        border-radius: 100px;
+        color: #fff;
+        font-size: 0.78rem;
+        font-weight: 700;
+        letter-spacing: 0.04em;
+        cursor: pointer;
+        margin-bottom: 0.75rem;
+        box-shadow: 0 0 16px rgba(236, 72, 153, 0.4), 0 0 40px rgba(139, 92, 246, 0.2);
+        transition: transform 0.2s ease, box-shadow 0.2s ease;
+        animation: beta-pulse 3s ease-in-out infinite;
+    }
+    .beta-pill:hover {
+        transform: scale(1.06);
+        box-shadow: 0 0 22px rgba(236, 72, 153, 0.55), 0 0 50px rgba(139, 92, 246, 0.35);
+    }
+    @keyframes beta-pulse {
+        0%, 100% { box-shadow: 0 0 16px rgba(236, 72, 153, 0.4), 0 0 40px rgba(139, 92, 246, 0.2); }
+        50% { box-shadow: 0 0 24px rgba(236, 72, 153, 0.6), 0 0 55px rgba(139, 92, 246, 0.35); }
+    }
+
+    .beta-modal-backdrop {
+        display: none;
+        position: fixed;
+        inset: 0;
+        z-index: 9999;
+        background: rgba(0, 0, 0, 0.6);
+        backdrop-filter: blur(4px);
+        -webkit-backdrop-filter: blur(4px);
+        align-items: center;
+        justify-content: center;
+    }
+    .beta-modal-backdrop.open { display: flex; }
+    .beta-modal {
+        background: var(--bg-surface);
+        border: 1px solid var(--myc-node-border);
+        border-radius: var(--radius-lg);
+        max-width: 440px;
+        width: 90%;
+        padding: 2.5rem 2rem 2rem;
+        text-align: center;
+        box-shadow: var(--shadow-lg), 0 0 60px rgba(139, 92, 246, 0.15);
+        position: relative;
+        animation: beta-modal-in 0.25s ease-out;
+    }
+    @keyframes beta-modal-in {
+        from { opacity: 0; transform: scale(0.92) translateY(12px); }
+        to { opacity: 1; transform: scale(1) translateY(0); }
+    }
+    .beta-modal-emoji { font-size: 2.5rem; margin-bottom: 1rem; }
+    .beta-modal h3 {
+        font-size: 1.25rem;
+        color: var(--text-primary);
+        margin-bottom: 0.75rem;
+    }
+    .beta-modal p {
+        color: var(--text-secondary);
+        font-size: 0.95rem;
+        line-height: 1.7;
         margin-bottom: 1.5rem;
     }
+    .beta-modal-close {
+        display: inline-block;
+        padding: 0.5rem 1.5rem;
+        background: linear-gradient(135deg, #8B5CF6, #6f42c1);
+        border: none;
+        border-radius: 100px;
+        color: #fff;
+        font-size: 0.85rem;
+        font-weight: 600;
+        cursor: pointer;
+        transition: transform 0.15s ease, box-shadow 0.15s ease;
+    }
+    .beta-modal-close:hover {
+        transform: scale(1.04);
+        box-shadow: 0 0 14px rgba(139, 92, 246, 0.4);
+    }
 
     .hero h1 {
         background: linear-gradient(135deg, var(--primary-light) 0%, #C084FC 50%, #F5A9B8 100%);
         -webkit-background-clip: text;
         -webkit-text-fill-color: transparent;
         background-clip: text;
+        margin-bottom: 0.5rem;
+        font-size: clamp(2.5rem, 5vw, 3.75rem);
+    }
+
+    /* ---- Typewriter rotating line ---- */
+    .hero-rotating-line {
+        font-size: clamp(1.15rem, 2.2vw, 1.5rem);
+        color: var(--text-secondary);
         margin-bottom: 1.25rem;
+        min-height: 2.2em;
+        line-height: 1.5;
+    }
+    .hero-rotating-line .tw-static {
+        color: var(--text-secondary);
+    }
+    .hero-rotating-line .tw-word {
+        color: var(--primary-light);
+        font-weight: 700;
+        border-right: 2px solid var(--primary-light);
+        padding-right: 2px;
+        animation: blink-cursor 0.75s step-end infinite;
+    }
+    @keyframes blink-cursor {
+        50% { border-color: transparent; }
     }
 
     .hero-subtitle {
         color: var(--text-secondary);
-        font-size: clamp(1rem, 2vw, 1.2rem);
-        max-width: 640px;
-        margin: 0 auto 2rem;
+        font-size: clamp(0.95rem, 1.8vw, 1.1rem);
+        max-width: 540px;
+        margin: 0 0 1.5rem;
         line-height: 1.7;
     }
 
     .hero-cta {
         display: flex;
-        gap: 1rem;
-        justify-content: center;
+        gap: 0.75rem;
         flex-wrap: wrap;
-        margin-bottom: 2.5rem;
+        margin-bottom: 1.5rem;
     }
 
-    /* Search */
-    .hero-search {
+    /* ---- Feature pills ---- */
+    .hero-pills {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 0.5rem;
+        margin-bottom: 1.5rem;
+    }
+    .hero-pill {
+        display: inline-flex;
+        align-items: center;
+        gap: 0.35rem;
+        padding: 0.3rem 0.75rem;
+        background: var(--myc-node-bg);
+        border: 1px solid var(--myc-node-border);
+        border-radius: 100px;
+        color: var(--text-secondary);
+        font-size: 0.72rem;
+        font-weight: 500;
+        letter-spacing: 0.01em;
+        opacity: 0;
+        transform: translateY(8px);
+        transition: opacity 0.4s ease, transform 0.4s ease, background 0.2s ease;
+    }
+    .hero-pill.visible {
+        opacity: 1;
+        transform: translateY(0);
+    }
+    .hero-pill:hover {
+        background: rgba(139, 92, 246, 0.15);
+        color: var(--primary-light);
+        text-decoration: none;
+    }
+    .hero-pill .pill-icon {
+        font-size: 0.82rem;
+        line-height: 1;
+    }
+
+    /* ---- Feature showcase (right column) ---- */
+    .hero-showcase {
         position: relative;
-        max-width: 520px;
-        margin: 0 auto 3rem;
+        width: 100%;
+        aspect-ratio: 16 / 9.5;
+        perspective: 1200px;
+    }
+
+    .showcase-card {
+        position: absolute;
+        inset: 0;
+        border: 1px solid var(--border-color);
+        border-radius: var(--radius-lg);
+        display: flex;
+        flex-direction: column;
+        opacity: 0;
+        transform: rotateY(8deg) translateX(30px) scale(0.95);
+        transition: opacity 0.6s ease, transform 0.6s ease;
+        pointer-events: none;
+        overflow: hidden;
+    }
+    .showcase-card.active {
+        opacity: 1;
+        transform: rotateY(0deg) translateX(0) scale(1);
+        pointer-events: auto;
+        border-color: var(--myc-node-border);
+        box-shadow: 0 0 30px rgba(139, 92, 246, 0.12), var(--shadow-lg);
+    }
+    .showcase-card.exiting {
+        opacity: 0;
+        transform: rotateY(-8deg) translateX(-30px) scale(0.95);
+    }
+
+    /* Screenshot image fills the card */
+    .showcase-card-img {
+        width: 100%;
+        height: 100%;
+        object-fit: cover;
+        object-position: top left;
+        display: block;
+    }
+
+    /* Caption overlay at bottom */
+    .showcase-card-caption {
+        position: absolute;
+        bottom: 0;
+        left: 0;
+        right: 0;
+        padding: 2.5rem 1.25rem 1rem;
+        background: linear-gradient(to top, rgba(15, 23, 42, 0.95) 0%, rgba(15, 23, 42, 0.75) 50%, transparent 100%);
+        display: flex;
+        align-items: flex-end;
+        gap: 0.75rem;
+    }
+    [data-theme="light"] .showcase-card-caption {
+        background: linear-gradient(to top, rgba(255, 255, 255, 0.97) 0%, rgba(255, 255, 255, 0.8) 50%, transparent 100%);
+    }
+    .showcase-card-icon {
+        width: 36px;
+        height: 36px;
+        border-radius: 8px;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        font-size: 1.1rem;
+        flex-shrink: 0;
+        backdrop-filter: blur(4px);
+        -webkit-backdrop-filter: blur(4px);
+    }
+    .showcase-card-title {
+        font-size: 0.95rem;
+        font-weight: 700;
+        color: #F1F5F9;
+        line-height: 1.3;
+    }
+    [data-theme="light"] .showcase-card-title {
+        color: #0F172A;
+    }
+    .showcase-card-subtitle {
+        font-size: 0.72rem;
+        color: #94A3B8;
+        margin-top: 0.1rem;
+    }
+    [data-theme="light"] .showcase-card-subtitle {
+        color: #64748B;
+    }
+
+    /* Showcase progress dots */
+    .showcase-dots {
+        display: flex;
+        justify-content: center;
+        gap: 0.5rem;
+        margin-top: 0.75rem;
+    }
+    .showcase-dot {
+        width: 8px;
+        height: 8px;
+        border-radius: 50%;
+        background: var(--text-muted);
+        opacity: 0.3;
+        cursor: pointer;
+        transition: opacity 0.3s ease, transform 0.3s ease, background 0.3s ease;
+    }
+    .showcase-dot.active {
+        opacity: 1;
+        background: var(--primary-light);
+        transform: scale(1.3);
+    }
+    .showcase-dot:hover {
+        opacity: 0.7;
+    }
+
+    /* ---- Particle canvas ---- */
+    .hero-particles {
+        position: absolute;
+        inset: 0;
+        z-index: 0;
+        pointer-events: none;
+    }
+
+    /* ---- Quick deploy terminal ---- */
+    .hero-terminal {
+        margin: 0.75rem 0 0;
+        background: #0D1117;
+        border: 1px solid rgba(139, 92, 246, 0.2);
+        border-radius: var(--radius);
+        opacity: 0;
+        transform: translateY(8px);
+        animation: fadeSlideIn 0.6s ease 1.4s forwards;
+    }
+    @keyframes fadeSlideIn {
+        to { opacity: 1; transform: translateY(0); }
+    }
+    [data-theme="light"] .hero-terminal {
+        background: #1E293B;
+    }
+    .hero-terminal-bar {
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+        padding: 0.5rem 0.85rem;
+        background: rgba(255, 255, 255, 0.04);
+        border-bottom: 1px solid rgba(255, 255, 255, 0.06);
+        border-radius: var(--radius) var(--radius) 0 0;
+    }
+    .hero-terminal-dot {
+        width: 8px;
+        height: 8px;
+        border-radius: 50%;
+    }
+    .hero-terminal-title {
+        font-size: 0.65rem;
+        color: #64748B;
+        font-family: 'SF Mono', 'Fira Code', 'Cascadia Code', monospace;
+        margin-left: auto;
+    }
+    .hero-terminal-body {
+        padding: 0.6rem 0.85rem;
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+    }
+    .hero-terminal-prompt {
+        color: #34D399;
+        font-family: 'SF Mono', 'Fira Code', 'Cascadia Code', monospace;
+        font-size: 0.82rem;
+        font-weight: 600;
+        flex-shrink: 0;
+        user-select: none;
+    }
+    .hero-terminal-cmd {
+        color: #E2E8F0;
+        font-family: 'SF Mono', 'Fira Code', 'Cascadia Code', monospace;
+        font-size: 0.82rem;
+        white-space: nowrap;
+        overflow-x: auto;
+        overflow-y: hidden;
+        flex: 1;
+        min-width: 0;
+        scrollbar-width: none;
+        -ms-overflow-style: none;
+    }
+    .hero-terminal-cmd::-webkit-scrollbar { display: none; }
+    .hero-terminal-cmd .cmd-highlight {
+        color: var(--primary-light);
+    }
+    .hero-terminal-copy {
+        background: none;
+        border: 1px solid rgba(148, 163, 184, 0.2);
+        border-radius: 6px;
+        color: #94A3B8;
+        font-size: 0.7rem;
+        padding: 0.25rem 0.55rem;
+        cursor: pointer;
+        font-family: inherit;
+        transition: color 0.2s ease, border-color 0.2s ease, background 0.2s ease;
+        flex-shrink: 0;
+        display: flex;
+        align-items: center;
+        gap: 0.3rem;
+    }
+    .hero-terminal-copy:hover {
+        color: #E2E8F0;
+        border-color: rgba(148, 163, 184, 0.4);
+        background: rgba(255, 255, 255, 0.05);
+    }
+    .hero-terminal-copy.copied {
+        color: #34D399;
+        border-color: rgba(52, 211, 153, 0.3);
+    }
+
+    /* Search (moved out of hero, kept for search functionality) */
+    .hero-search {
+        display: none;
     }
 
     .search-input-wrap {
@@ -699,8 +1096,14 @@
         display: grid;
         grid-template-columns: repeat(4, 1fr);
         gap: 1.5rem;
-        max-width: 640px;
+        max-width: 800px;
         margin: 0 auto;
+        padding: 1.25rem 2rem;
+        background: var(--bg-card);
+        border: 1px solid var(--border-color);
+        border-radius: var(--radius);
+        backdrop-filter: blur(8px);
+        -webkit-backdrop-filter: blur(8px);
     }
 
     .hero-stat {
@@ -708,9 +1111,10 @@
     }
 
     .hero-stat-value {
-        font-size: 1.5rem;
+        font-size: 1.6rem;
         font-weight: 800;
         color: var(--primary-light);
+        font-variant-numeric: tabular-nums;
     }
 
     .hero-stat-label {
@@ -719,6 +1123,24 @@
         margin-top: 0.25rem;
     }
 
+    .hero-trust {
+        text-align: center;
+        margin-top: 1rem;
+        color: var(--text-muted);
+        font-size: 0.78rem;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        gap: 0.5rem;
+        opacity: 0;
+        animation: fadeIn 1s ease 1.5s forwards;
+    }
+    .hero-trust svg {
+        width: 14px;
+        height: 14px;
+        color: var(--primary-light);
+    }
+
     /* ============================================
        PROBLEMS SECTION
        ============================================ */
@@ -1746,16 +2168,41 @@
     @media (max-width: 768px) {
         .nav-links { display: none; }
         .nav-right .btn-primary { display: none; }
+        .nav-right .btn-demo { display: none; }
         .hamburger { display: block; }
         .logo-tagline { display: none; }
 
         .section { padding: 4rem 0; }
 
-        .hero { min-height: auto; padding-top: calc(var(--header-height) + 2rem); padding-bottom: 3rem; }
+        .hero { min-height: auto; padding-top: calc(var(--header-height) + 1.5rem); padding-bottom: 1.5rem; overflow-x: hidden; }
         .hero h1 { font-size: 2rem; }
         .hero-root-glow { width: 250px; height: 250px; top: 50%; bottom: auto; }
         .hero-root-svg { top: 50%; bottom: auto; transform: translate(-50%, -50%); width: 250px; height: 250px; }
 
+        .hero-content {
+            display: flex;
+            flex-direction: column;
+            max-width: 100%;
+            width: 100%;
+            overflow: hidden;
+        }
+        .hero-left { text-align: center; padding-top: 0; }
+        .hero-right { margin-top: 1.5rem; overflow: hidden; width: 100%; }
+        .hero-right > div { max-width: 100%; overflow: hidden; width: 100%; }
+        .hero-showcase { width: 100%; max-width: 100%; }
+        .hero-terminal { width: 100%; max-width: 100%; box-sizing: border-box; }
+        .hero-showcase { aspect-ratio: 16 / 10; }
+        .hero-cta { justify-content: center; }
+        .hero-pills { justify-content: center; }
+        .hero-terminal { max-width: 100%; overflow: hidden; }
+        .hero-terminal-body { padding: 0.5rem 0.7rem; gap: 0.4rem; }
+        .hero-terminal-prompt { font-size: 0.7rem; }
+        .hero-terminal-cmd { font-size: 0.65rem; }
+        .hero-terminal-copy { font-size: 0.62rem; padding: 0.2rem 0.4rem; }
+        .hero-terminal-copy .copy-label { display: none; }
+        .hero-rotating-line { text-align: center; }
+        .hero-subtitle { margin-left: auto; margin-right: auto; }
+
         .hero-stats {
             grid-template-columns: repeat(2, 1fr);
             gap: 1rem;
@@ -1798,6 +2245,8 @@
             flex-direction: column;
             align-items: center;
         }
+        .hero-pills { gap: 0.4rem; }
+        .hero-pill { font-size: 0.68rem; padding: 0.25rem 0.6rem; }
 
         .cta-buttons {
             flex-direction: column;
@@ -1818,7 +2267,15 @@
         .hero { padding-left: 1rem; padding-right: 1rem; }
         .section { padding: 3rem 0; }
         .section-header { margin-bottom: 2.5rem; }
-        .hero-stats { grid-template-columns: repeat(2, 1fr); }
+        .hero-stats { grid-template-columns: repeat(2, 1fr); padding: 1rem; }
+        .hero-showcase { aspect-ratio: 16 / 11; }
+        .showcase-card-title { font-size: 0.85rem; }
+        .showcase-card-subtitle { font-size: 0.65rem; }
+        .showcase-card-caption { padding: 1.5rem 1rem 0.75rem; }
+        .hero-terminal-cmd { font-size: 0.58rem; }
+        .hero-terminal-prompt { font-size: 0.6rem; }
+        .hero-terminal-title { font-size: 0.55rem; }
+        .hero-terminal-dot { width: 6px; height: 6px; }
         .live-stats { grid-template-columns: 1fr; }
     }
 
@@ -2115,72 +2572,175 @@
      HERO
      ============================================ -->
 
    
+    
+    
+
     
     
    
         
    
         
-        
     
    
 
     
    
-        
    Self-Hosted Campaign Infrastructure
    
-        
    Grow Power.
    Don't Rent It.
    
-        
    
-            Run your campaigns, canvassing, fundraising, team chat, media, and more — all on your own infrastructure.
-            No corporate surveillance. No foreign interference. No monthly ransoms.
-            A free* and open source toolkit built for growing political movements.
-        
    
-        
    
-            Explore the Demo 
-            Schedule a Chat
-            Source Code
+        
+        
    
+            
+            
    Self-Hosted Campaign Infrastructure
    
+            
    Grow Power.
    Don't Rent It.
    
+
+            
    
+                Your  — on your own infrastructure.
+            
    
+
+            
    
+                No corporate surveillance. No foreign interference. No monthly ransoms.
+                A free* and open source toolkit built for growing political movements.
+            
    
+
+            
    
+                Explore the Demo 
+                Schedule a Chat
+                Source Code
+            
    
+
+            
+            
+
         
    
 
-        
-        
    
-            
    
-                
-                
-                
-            
    
-            
    
-                
    
-                    
-                    
+        
+        
    
+            
    
+                
    
+                    
+                    
    
+                        Advocacy campaigns dashboard showing campaign list with status badges, email counts, and response tracking
+                        
    
+                            
    ✉
    
+                            
    
+                                
    Advocacy Campaigns
    
+                                
    Email your representatives in 3 clicks
    
+                            
    
+                        
    
+                    
    
+
+                    
+                    
    
+                        Canvassing dashboard with live volunteer map, cut progress tracking, and activity feed
+                        
    
+                            
    🌎
    
+                            
    
+                                
    GPS Canvassing
    
+                                
    Track door-to-door outreach in real time
    
+                            
    
+                        
    
+                    
    
+
+                    
+                    
    
+                        Media library with video thumbnails, filters, and publishing controls
+                        
    
+                            
    🎥
    
+                            
    
+                                
    Media Library
    
+                                
    Host, schedule, and share your campaign videos
    
+                            
    
+                        
    
+                    
    
+
+                    
+                    
    
+                        Shift management dashboard with stats, table view, and volunteer signups
+                        
    
+                            
    📅
    
+                            
    
+                                
    Volunteer Management
    
+                                
    Coordinate shifts, track attendance, grow your team
    
+                            
    
+                        
    
+                    
    
+                
    
+                
    
+                    
+                    
+                    
+                    
+                
    
+
+                
+                
    
+                    
    
+                        
+                        
+                        
+                        Quick Deploy on Linux w/ Docker
+                    
    
+                    
    
+                        $
+                        curl -fsSL gitea.bnkops.com/admin/changemaker.lite/raw/branch/main/scripts/install.sh | bash
+                        
+                    
    
                 
    
-                
    
             
    
         
    
 
-        
    
-            
    
-                
    100%
    
-                
    Data Ownership
    
+        
+        
    
+            
    
+                
    
+                    
    0%
    
+                    
    Data Ownership
    
+                
    
+                
    
+                    
    $0
    
+                    
    Self-Hosted
    
+                
    
+                
    
+                    
    0+
    
+                    
    Integrated Tools
    
+                
    
+                
    
+                    
    FOSS
    
+                    
    Open Source
    
+                
    
             
    
-            
    
-                
    $0
    
-                
    Self-Hosted
    
-            
    
-            
    
-                
    45+
    
-                
    Integrated Tools
    
-            
    
-            
    
-                
    FOSS
    
-                
    Open Source
    
+            
    
+                
+                Self-hosted by community organizers across Canada
             
    
         
    
     
    
 
    
 
+
+
    
+    
    
+        
    🚧
    
+        
    Now in Beta
    
+        
    Changemaker Lite is under active development and breaking changes are still being pushed. A stable release is expected by June 2026.
    
+        
+    
    
+
    
+
 
@@ -2287,7 +2847,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
    📨
    
                 
    
@@ -2376,7 +2936,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
    🗺
    
                 
    
@@ -2461,7 +3021,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
    🎬
    
                 
    
@@ -2550,7 +3110,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
    📊
    
                 
    
@@ -2621,7 +3181,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
    🛡
    
                 
    
@@ -2697,7 +3257,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
    💳
    
                 
    
@@ -2768,7 +3328,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
                 
    
@@ -2830,7 +3390,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
    🇨🇦
    
                 
    
@@ -3864,6 +4424,275 @@
         }
     };
 
+    /* ===========================================
+       BETA MODAL
+       =========================================== */
+    const BetaModal = {
+        init() {
+            const pill = document.getElementById('beta-pill');
+            const backdrop = document.getElementById('beta-modal-backdrop');
+            const closeBtn = document.getElementById('beta-modal-close');
+            if (!pill || !backdrop || !closeBtn) return;
+            pill.addEventListener('click', () => backdrop.classList.add('open'));
+            closeBtn.addEventListener('click', () => backdrop.classList.remove('open'));
+            backdrop.addEventListener('click', (e) => { if (e.target === backdrop) backdrop.classList.remove('open'); });
+            document.addEventListener('keydown', (e) => { if (e.key === 'Escape' && backdrop.classList.contains('open')) backdrop.classList.remove('open'); });
+        }
+    };
+
+    /* ===========================================
+       TERMINAL COPY — clipboard for install cmd
+       =========================================== */
+    const TerminalCopy = {
+        init() {
+            const btn = document.getElementById('hero-copy-btn');
+            if (!btn) return;
+            btn.addEventListener('click', () => {
+                const cmd = 'curl -fsSL gitea.bnkops.com/admin/changemaker.lite/raw/branch/main/scripts/install.sh | bash';
+                navigator.clipboard.writeText(cmd).then(() => {
+                    btn.classList.add('copied');
+                    btn.querySelector('.copy-label').textContent = 'Copied!';
+                    setTimeout(() => {
+                        btn.classList.remove('copied');
+                        btn.querySelector('.copy-label').textContent = 'Copy';
+                    }, 2000);
+                });
+            });
+        }
+    };
+
+    /* ===========================================
+       TYPEWRITER — rotating hero words
+       =========================================== */
+    const Typewriter = {
+        words: ['campaigns', 'canvassing', 'fundraising', 'newsletters', 'media library', 'volunteer shifts', 'team chat', 'events'],
+        el: null,
+        wordIdx: 0,
+        charIdx: 0,
+        isDeleting: false,
+        timeout: null,
+
+        init() {
+            this.el = document.getElementById('tw-word');
+            if (!this.el) return;
+            if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+                this.el.textContent = this.words[0];
+                return;
+            }
+            this.tick();
+        },
+
+        tick() {
+            const word = this.words[this.wordIdx];
+
+            if (this.isDeleting) {
+                this.charIdx--;
+            } else {
+                this.charIdx++;
+            }
+
+            this.el.textContent = word.substring(0, this.charIdx);
+
+            let delay = this.isDeleting ? 40 : 80;
+
+            if (!this.isDeleting && this.charIdx === word.length) {
+                delay = 2200;
+                this.isDeleting = true;
+            } else if (this.isDeleting && this.charIdx === 0) {
+                this.isDeleting = false;
+                this.wordIdx = (this.wordIdx + 1) % this.words.length;
+                delay = 400;
+            }
+
+            this.timeout = setTimeout(() => this.tick(), delay);
+        }
+    };
+
+    /* ===========================================
+       FEATURE PILLS — staggered entrance
+       =========================================== */
+    const FeaturePills = {
+        init() {
+            const pills = document.querySelectorAll('.hero-pill');
+            if (!pills.length) return;
+            if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+                pills.forEach(p => p.classList.add('visible'));
+                return;
+            }
+            pills.forEach((pill, i) => {
+                setTimeout(() => pill.classList.add('visible'), 600 + i * 120);
+            });
+        }
+    };
+
+    /* ===========================================
+       FEATURE SHOWCASE — rotating cards
+       =========================================== */
+    const FeatureShowcase = {
+        current: 0,
+        cards: [],
+        dots: [],
+        interval: null,
+        DURATION: 5000,
+
+        init() {
+            this.cards = document.querySelectorAll('.showcase-card');
+            this.dots = document.querySelectorAll('.showcase-dot');
+            if (this.cards.length < 2) return;
+
+            this.dots.forEach(dot => {
+                dot.addEventListener('click', () => {
+                    const idx = parseInt(dot.getAttribute('data-idx'), 10);
+                    if (idx !== this.current) this.goTo(idx);
+                });
+            });
+
+            this.startAutoplay();
+        },
+
+        goTo(idx) {
+            const prev = this.cards[this.current];
+            prev.classList.remove('active');
+            prev.classList.add('exiting');
+            setTimeout(() => prev.classList.remove('exiting'), 600);
+
+            this.current = idx;
+            this.cards[this.current].classList.add('active');
+
+            this.dots.forEach((d, i) => d.classList.toggle('active', i === idx));
+            this.restartAutoplay();
+        },
+
+        next() {
+            this.goTo((this.current + 1) % this.cards.length);
+        },
+
+        startAutoplay() {
+            this.interval = setInterval(() => this.next(), this.DURATION);
+        },
+
+        restartAutoplay() {
+            clearInterval(this.interval);
+            this.startAutoplay();
+        }
+    };
+
+    /* ===========================================
+       COUNT-UP STATS — animated number counters
+       =========================================== */
+    const CountUpStats = {
+        init() {
+            const stats = document.querySelectorAll('.hero-stat-value[data-count]');
+            if (!stats.length) return;
+            if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+                stats.forEach(el => {
+                    const target = parseInt(el.getAttribute('data-count'), 10);
+                    const prefix = el.getAttribute('data-prefix') || '';
+                    const suffix = el.getAttribute('data-suffix') || '';
+                    el.textContent = prefix + target + suffix;
+                });
+                return;
+            }
+
+            const obs = new IntersectionObserver((entries) => {
+                entries.forEach(entry => {
+                    if (entry.isIntersecting) {
+                        this.animate(entry.target);
+                        obs.unobserve(entry.target);
+                    }
+                });
+            }, { threshold: 0.5 });
+
+            stats.forEach(el => obs.observe(el));
+        },
+
+        animate(el) {
+            const target = parseInt(el.getAttribute('data-count'), 10);
+            const prefix = el.getAttribute('data-prefix') || '';
+            const suffix = el.getAttribute('data-suffix') || '';
+            const duration = 1400;
+            const start = performance.now();
+
+            const step = (now) => {
+                const progress = Math.min((now - start) / duration, 1);
+                const eased = 1 - Math.pow(1 - progress, 3);
+                const current = Math.round(eased * target);
+                el.textContent = prefix + current + suffix;
+                if (progress < 1) requestAnimationFrame(step);
+            };
+            requestAnimationFrame(step);
+        }
+    };
+
+    /* ===========================================
+       PARTICLE DRIFT — floating background dots
+       =========================================== */
+    const ParticleDrift = {
+        canvas: null,
+        ctx: null,
+        particles: [],
+        raf: null,
+        COUNT: 35,
+
+        init() {
+            this.canvas = document.getElementById('hero-particles');
+            if (!this.canvas) return;
+            if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return;
+            // Fewer particles on mobile
+            if (window.innerWidth < 768) this.COUNT = 15;
+
+            this.ctx = this.canvas.getContext('2d');
+            this.resize();
+            this.createParticles();
+            this.loop();
+            window.addEventListener('resize', () => this.resize());
+        },
+
+        resize() {
+            const hero = this.canvas.parentElement;
+            this.canvas.width = hero.offsetWidth;
+            this.canvas.height = hero.offsetHeight;
+        },
+
+        createParticles() {
+            this.particles = [];
+            for (let i = 0; i < this.COUNT; i++) {
+                this.particles.push({
+                    x: Math.random() * this.canvas.width,
+                    y: Math.random() * this.canvas.height,
+                    r: Math.random() * 2 + 0.5,
+                    vx: (Math.random() - 0.5) * 0.3,
+                    vy: -(Math.random() * 0.4 + 0.1),
+                    alpha: Math.random() * 0.3 + 0.1,
+                });
+            }
+        },
+
+        loop() {
+            const { ctx, canvas, particles } = this;
+            ctx.clearRect(0, 0, canvas.width, canvas.height);
+
+            const isDark = document.documentElement.getAttribute('data-theme') !== 'light';
+            const baseColor = isDark ? '139, 92, 246' : '111, 66, 193';
+
+            particles.forEach(p => {
+                p.x += p.vx;
+                p.y += p.vy;
+                // Wrap around
+                if (p.y < -5) { p.y = canvas.height + 5; p.x = Math.random() * canvas.width; }
+                if (p.x < -5) p.x = canvas.width + 5;
+                if (p.x > canvas.width + 5) p.x = -5;
+
+                ctx.beginPath();
+                ctx.arc(p.x, p.y, p.r, 0, Math.PI * 2);
+                ctx.fillStyle = `rgba(${baseColor}, ${p.alpha})`;
+                ctx.fill();
+            });
+
+            this.raf = requestAnimationFrame(() => this.loop());
+        }
+    };
+
     /* ===========================================
        BOOT
        =========================================== */
@@ -3877,7 +4706,14 @@
         FloatingElements.init();
         SmoothScroll.init();
         FreeModal.init();
+        BetaModal.init();
         initSearch();
+        TerminalCopy.init();
+        Typewriter.init();
+        FeaturePills.init();
+        FeatureShowcase.init();
+        CountUpStats.init();
+        ParticleDrift.init();
     });
 
 })();
diff --git a/mkdocs/site/main/index.html b/mkdocs/site/main/index.html
index 5f5f84d0..6cbd2263 100644
--- a/mkdocs/site/main/index.html
+++ b/mkdocs/site/main/index.html
@@ -1390,7 +1390,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
 
 
   
-    
+    
       
       
     
@@ -1399,7 +1399,7 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
     
       
     
-    
+    
       
       
     
@@ -1586,6 +1586,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/overrides/lander.html b/mkdocs/site/overrides/lander.html
index 9fbda767..8858003a 100644
--- a/mkdocs/site/overrides/lander.html
+++ b/mkdocs/site/overrides/lander.html
@@ -92,6 +92,10 @@
     /* ============================================
        TYPOGRAPHY
        ============================================ */
+    html {
+        overflow-x: hidden;
+    }
+
     body {
         font-family: 'Inter', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
         color: var(--text-primary);
@@ -482,7 +486,7 @@
         flex-direction: column;
         align-items: center;
         justify-content: flex-start;
-        padding: calc(var(--header-height) + 3rem) 2rem 0;
+        padding: calc(var(--header-height) + 2rem) 2rem 0;
         overflow: hidden;
     }
 
@@ -510,6 +514,22 @@
         background: radial-gradient(circle, rgba(111, 66, 193, 0.08) 0%, rgba(139, 92, 246, 0.03) 40%, transparent 70%);
     }
 
+    [data-theme="light"] .showcase-card {
+        border-color: rgba(100, 116, 139, 0.2);
+    }
+    [data-theme="light"] .showcase-card.active {
+        box-shadow: 0 0 30px rgba(111, 66, 193, 0.08), 0 8px 32px rgba(0, 0, 0, 0.1);
+        border-color: rgba(111, 66, 193, 0.25);
+    }
+    [data-theme="light"] .hero-stats {
+        background: rgba(255, 255, 255, 0.9);
+        border-color: rgba(100, 116, 139, 0.15);
+    }
+    [data-theme="light"] .hero-pill {
+        background: rgba(111, 66, 193, 0.06);
+        border-color: rgba(111, 66, 193, 0.15);
+    }
+
     .hero-root-svg {
         position: absolute;
         top: 65%;
@@ -526,11 +546,38 @@
         to { opacity: 1; }
     }
 
+    /* ---- Two-column hero grid (desktop) ---- */
     .hero-content {
         position: relative;
         z-index: 1;
-        text-align: center;
-        max-width: 800px;
+        width: 100%;
+        max-width: 1400px;
+        display: grid;
+        grid-template-columns: minmax(380px, 1fr) minmax(0, 1.4fr);
+        grid-template-rows: auto auto;
+        gap: 0 2.5rem;
+        align-items: start;
+    }
+
+    .hero-left {
+        text-align: left;
+        padding-top: 1.5rem;
+    }
+
+    .hero-right {
+        display: flex;
+        align-items: flex-start;
+        justify-content: flex-end;
+        padding-top: 0.5rem;
+    }
+    .hero-right > div {
+        width: 100%;
+    }
+
+    /* Spans full width below both columns */
+    .hero-bottom {
+        grid-column: 1 / -1;
+        margin-top: 1.5rem;
     }
 
     .hero-badge {
@@ -543,38 +590,388 @@
         font-size: 0.8rem;
         font-weight: 600;
         letter-spacing: 0.02em;
+        margin-bottom: 1rem;
+    }
+
+    .beta-pill {
+        display: inline-block;
+        padding: 0.35rem 1.1rem;
+        background: linear-gradient(135deg, #EC4899, #8B5CF6);
+        border: none;
+        border-radius: 100px;
+        color: #fff;
+        font-size: 0.78rem;
+        font-weight: 700;
+        letter-spacing: 0.04em;
+        cursor: pointer;
+        margin-bottom: 0.75rem;
+        box-shadow: 0 0 16px rgba(236, 72, 153, 0.4), 0 0 40px rgba(139, 92, 246, 0.2);
+        transition: transform 0.2s ease, box-shadow 0.2s ease;
+        animation: beta-pulse 3s ease-in-out infinite;
+    }
+    .beta-pill:hover {
+        transform: scale(1.06);
+        box-shadow: 0 0 22px rgba(236, 72, 153, 0.55), 0 0 50px rgba(139, 92, 246, 0.35);
+    }
+    @keyframes beta-pulse {
+        0%, 100% { box-shadow: 0 0 16px rgba(236, 72, 153, 0.4), 0 0 40px rgba(139, 92, 246, 0.2); }
+        50% { box-shadow: 0 0 24px rgba(236, 72, 153, 0.6), 0 0 55px rgba(139, 92, 246, 0.35); }
+    }
+
+    .beta-modal-backdrop {
+        display: none;
+        position: fixed;
+        inset: 0;
+        z-index: 9999;
+        background: rgba(0, 0, 0, 0.6);
+        backdrop-filter: blur(4px);
+        -webkit-backdrop-filter: blur(4px);
+        align-items: center;
+        justify-content: center;
+    }
+    .beta-modal-backdrop.open { display: flex; }
+    .beta-modal {
+        background: var(--bg-surface);
+        border: 1px solid var(--myc-node-border);
+        border-radius: var(--radius-lg);
+        max-width: 440px;
+        width: 90%;
+        padding: 2.5rem 2rem 2rem;
+        text-align: center;
+        box-shadow: var(--shadow-lg), 0 0 60px rgba(139, 92, 246, 0.15);
+        position: relative;
+        animation: beta-modal-in 0.25s ease-out;
+    }
+    @keyframes beta-modal-in {
+        from { opacity: 0; transform: scale(0.92) translateY(12px); }
+        to { opacity: 1; transform: scale(1) translateY(0); }
+    }
+    .beta-modal-emoji { font-size: 2.5rem; margin-bottom: 1rem; }
+    .beta-modal h3 {
+        font-size: 1.25rem;
+        color: var(--text-primary);
+        margin-bottom: 0.75rem;
+    }
+    .beta-modal p {
+        color: var(--text-secondary);
+        font-size: 0.95rem;
+        line-height: 1.7;
         margin-bottom: 1.5rem;
     }
+    .beta-modal-close {
+        display: inline-block;
+        padding: 0.5rem 1.5rem;
+        background: linear-gradient(135deg, #8B5CF6, #6f42c1);
+        border: none;
+        border-radius: 100px;
+        color: #fff;
+        font-size: 0.85rem;
+        font-weight: 600;
+        cursor: pointer;
+        transition: transform 0.15s ease, box-shadow 0.15s ease;
+    }
+    .beta-modal-close:hover {
+        transform: scale(1.04);
+        box-shadow: 0 0 14px rgba(139, 92, 246, 0.4);
+    }
 
     .hero h1 {
         background: linear-gradient(135deg, var(--primary-light) 0%, #C084FC 50%, #F5A9B8 100%);
         -webkit-background-clip: text;
         -webkit-text-fill-color: transparent;
         background-clip: text;
+        margin-bottom: 0.5rem;
+        font-size: clamp(2.5rem, 5vw, 3.75rem);
+    }
+
+    /* ---- Typewriter rotating line ---- */
+    .hero-rotating-line {
+        font-size: clamp(1.15rem, 2.2vw, 1.5rem);
+        color: var(--text-secondary);
         margin-bottom: 1.25rem;
+        min-height: 2.2em;
+        line-height: 1.5;
+    }
+    .hero-rotating-line .tw-static {
+        color: var(--text-secondary);
+    }
+    .hero-rotating-line .tw-word {
+        color: var(--primary-light);
+        font-weight: 700;
+        border-right: 2px solid var(--primary-light);
+        padding-right: 2px;
+        animation: blink-cursor 0.75s step-end infinite;
+    }
+    @keyframes blink-cursor {
+        50% { border-color: transparent; }
     }
 
     .hero-subtitle {
         color: var(--text-secondary);
-        font-size: clamp(1rem, 2vw, 1.2rem);
-        max-width: 640px;
-        margin: 0 auto 2rem;
+        font-size: clamp(0.95rem, 1.8vw, 1.1rem);
+        max-width: 540px;
+        margin: 0 0 1.5rem;
         line-height: 1.7;
     }
 
     .hero-cta {
         display: flex;
-        gap: 1rem;
-        justify-content: center;
+        gap: 0.75rem;
         flex-wrap: wrap;
-        margin-bottom: 2.5rem;
+        margin-bottom: 1.5rem;
     }
 
-    /* Search */
-    .hero-search {
+    /* ---- Feature pills ---- */
+    .hero-pills {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 0.5rem;
+        margin-bottom: 1.5rem;
+    }
+    .hero-pill {
+        display: inline-flex;
+        align-items: center;
+        gap: 0.35rem;
+        padding: 0.3rem 0.75rem;
+        background: var(--myc-node-bg);
+        border: 1px solid var(--myc-node-border);
+        border-radius: 100px;
+        color: var(--text-secondary);
+        font-size: 0.72rem;
+        font-weight: 500;
+        letter-spacing: 0.01em;
+        opacity: 0;
+        transform: translateY(8px);
+        transition: opacity 0.4s ease, transform 0.4s ease, background 0.2s ease;
+    }
+    .hero-pill.visible {
+        opacity: 1;
+        transform: translateY(0);
+    }
+    .hero-pill:hover {
+        background: rgba(139, 92, 246, 0.15);
+        color: var(--primary-light);
+        text-decoration: none;
+    }
+    .hero-pill .pill-icon {
+        font-size: 0.82rem;
+        line-height: 1;
+    }
+
+    /* ---- Feature showcase (right column) ---- */
+    .hero-showcase {
         position: relative;
-        max-width: 520px;
-        margin: 0 auto 3rem;
+        width: 100%;
+        aspect-ratio: 16 / 9.5;
+        perspective: 1200px;
+    }
+
+    .showcase-card {
+        position: absolute;
+        inset: 0;
+        border: 1px solid var(--border-color);
+        border-radius: var(--radius-lg);
+        display: flex;
+        flex-direction: column;
+        opacity: 0;
+        transform: rotateY(8deg) translateX(30px) scale(0.95);
+        transition: opacity 0.6s ease, transform 0.6s ease;
+        pointer-events: none;
+        overflow: hidden;
+    }
+    .showcase-card.active {
+        opacity: 1;
+        transform: rotateY(0deg) translateX(0) scale(1);
+        pointer-events: auto;
+        border-color: var(--myc-node-border);
+        box-shadow: 0 0 30px rgba(139, 92, 246, 0.12), var(--shadow-lg);
+    }
+    .showcase-card.exiting {
+        opacity: 0;
+        transform: rotateY(-8deg) translateX(-30px) scale(0.95);
+    }
+
+    /* Screenshot image fills the card */
+    .showcase-card-img {
+        width: 100%;
+        height: 100%;
+        object-fit: cover;
+        object-position: top left;
+        display: block;
+    }
+
+    /* Caption overlay at bottom */
+    .showcase-card-caption {
+        position: absolute;
+        bottom: 0;
+        left: 0;
+        right: 0;
+        padding: 2.5rem 1.25rem 1rem;
+        background: linear-gradient(to top, rgba(15, 23, 42, 0.95) 0%, rgba(15, 23, 42, 0.75) 50%, transparent 100%);
+        display: flex;
+        align-items: flex-end;
+        gap: 0.75rem;
+    }
+    [data-theme="light"] .showcase-card-caption {
+        background: linear-gradient(to top, rgba(255, 255, 255, 0.97) 0%, rgba(255, 255, 255, 0.8) 50%, transparent 100%);
+    }
+    .showcase-card-icon {
+        width: 36px;
+        height: 36px;
+        border-radius: 8px;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        font-size: 1.1rem;
+        flex-shrink: 0;
+        backdrop-filter: blur(4px);
+        -webkit-backdrop-filter: blur(4px);
+    }
+    .showcase-card-title {
+        font-size: 0.95rem;
+        font-weight: 700;
+        color: #F1F5F9;
+        line-height: 1.3;
+    }
+    [data-theme="light"] .showcase-card-title {
+        color: #0F172A;
+    }
+    .showcase-card-subtitle {
+        font-size: 0.72rem;
+        color: #94A3B8;
+        margin-top: 0.1rem;
+    }
+    [data-theme="light"] .showcase-card-subtitle {
+        color: #64748B;
+    }
+
+    /* Showcase progress dots */
+    .showcase-dots {
+        display: flex;
+        justify-content: center;
+        gap: 0.5rem;
+        margin-top: 0.75rem;
+    }
+    .showcase-dot {
+        width: 8px;
+        height: 8px;
+        border-radius: 50%;
+        background: var(--text-muted);
+        opacity: 0.3;
+        cursor: pointer;
+        transition: opacity 0.3s ease, transform 0.3s ease, background 0.3s ease;
+    }
+    .showcase-dot.active {
+        opacity: 1;
+        background: var(--primary-light);
+        transform: scale(1.3);
+    }
+    .showcase-dot:hover {
+        opacity: 0.7;
+    }
+
+    /* ---- Particle canvas ---- */
+    .hero-particles {
+        position: absolute;
+        inset: 0;
+        z-index: 0;
+        pointer-events: none;
+    }
+
+    /* ---- Quick deploy terminal ---- */
+    .hero-terminal {
+        margin: 0.75rem 0 0;
+        background: #0D1117;
+        border: 1px solid rgba(139, 92, 246, 0.2);
+        border-radius: var(--radius);
+        opacity: 0;
+        transform: translateY(8px);
+        animation: fadeSlideIn 0.6s ease 1.4s forwards;
+    }
+    @keyframes fadeSlideIn {
+        to { opacity: 1; transform: translateY(0); }
+    }
+    [data-theme="light"] .hero-terminal {
+        background: #1E293B;
+    }
+    .hero-terminal-bar {
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+        padding: 0.5rem 0.85rem;
+        background: rgba(255, 255, 255, 0.04);
+        border-bottom: 1px solid rgba(255, 255, 255, 0.06);
+        border-radius: var(--radius) var(--radius) 0 0;
+    }
+    .hero-terminal-dot {
+        width: 8px;
+        height: 8px;
+        border-radius: 50%;
+    }
+    .hero-terminal-title {
+        font-size: 0.65rem;
+        color: #64748B;
+        font-family: 'SF Mono', 'Fira Code', 'Cascadia Code', monospace;
+        margin-left: auto;
+    }
+    .hero-terminal-body {
+        padding: 0.6rem 0.85rem;
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+    }
+    .hero-terminal-prompt {
+        color: #34D399;
+        font-family: 'SF Mono', 'Fira Code', 'Cascadia Code', monospace;
+        font-size: 0.82rem;
+        font-weight: 600;
+        flex-shrink: 0;
+        user-select: none;
+    }
+    .hero-terminal-cmd {
+        color: #E2E8F0;
+        font-family: 'SF Mono', 'Fira Code', 'Cascadia Code', monospace;
+        font-size: 0.82rem;
+        white-space: nowrap;
+        overflow-x: auto;
+        overflow-y: hidden;
+        flex: 1;
+        min-width: 0;
+        scrollbar-width: none;
+        -ms-overflow-style: none;
+    }
+    .hero-terminal-cmd::-webkit-scrollbar { display: none; }
+    .hero-terminal-cmd .cmd-highlight {
+        color: var(--primary-light);
+    }
+    .hero-terminal-copy {
+        background: none;
+        border: 1px solid rgba(148, 163, 184, 0.2);
+        border-radius: 6px;
+        color: #94A3B8;
+        font-size: 0.7rem;
+        padding: 0.25rem 0.55rem;
+        cursor: pointer;
+        font-family: inherit;
+        transition: color 0.2s ease, border-color 0.2s ease, background 0.2s ease;
+        flex-shrink: 0;
+        display: flex;
+        align-items: center;
+        gap: 0.3rem;
+    }
+    .hero-terminal-copy:hover {
+        color: #E2E8F0;
+        border-color: rgba(148, 163, 184, 0.4);
+        background: rgba(255, 255, 255, 0.05);
+    }
+    .hero-terminal-copy.copied {
+        color: #34D399;
+        border-color: rgba(52, 211, 153, 0.3);
+    }
+
+    /* Search (moved out of hero, kept for search functionality) */
+    .hero-search {
+        display: none;
     }
 
     .search-input-wrap {
@@ -699,8 +1096,14 @@
         display: grid;
         grid-template-columns: repeat(4, 1fr);
         gap: 1.5rem;
-        max-width: 640px;
+        max-width: 800px;
         margin: 0 auto;
+        padding: 1.25rem 2rem;
+        background: var(--bg-card);
+        border: 1px solid var(--border-color);
+        border-radius: var(--radius);
+        backdrop-filter: blur(8px);
+        -webkit-backdrop-filter: blur(8px);
     }
 
     .hero-stat {
@@ -708,9 +1111,10 @@
     }
 
     .hero-stat-value {
-        font-size: 1.5rem;
+        font-size: 1.6rem;
         font-weight: 800;
         color: var(--primary-light);
+        font-variant-numeric: tabular-nums;
     }
 
     .hero-stat-label {
@@ -719,6 +1123,24 @@
         margin-top: 0.25rem;
     }
 
+    .hero-trust {
+        text-align: center;
+        margin-top: 1rem;
+        color: var(--text-muted);
+        font-size: 0.78rem;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        gap: 0.5rem;
+        opacity: 0;
+        animation: fadeIn 1s ease 1.5s forwards;
+    }
+    .hero-trust svg {
+        width: 14px;
+        height: 14px;
+        color: var(--primary-light);
+    }
+
     /* ============================================
        PROBLEMS SECTION
        ============================================ */
@@ -1746,16 +2168,41 @@
     @media (max-width: 768px) {
         .nav-links { display: none; }
         .nav-right .btn-primary { display: none; }
+        .nav-right .btn-demo { display: none; }
         .hamburger { display: block; }
         .logo-tagline { display: none; }
 
         .section { padding: 4rem 0; }
 
-        .hero { min-height: auto; padding-top: calc(var(--header-height) + 2rem); padding-bottom: 3rem; }
+        .hero { min-height: auto; padding-top: calc(var(--header-height) + 1.5rem); padding-bottom: 1.5rem; overflow-x: hidden; }
         .hero h1 { font-size: 2rem; }
         .hero-root-glow { width: 250px; height: 250px; top: 50%; bottom: auto; }
         .hero-root-svg { top: 50%; bottom: auto; transform: translate(-50%, -50%); width: 250px; height: 250px; }
 
+        .hero-content {
+            display: flex;
+            flex-direction: column;
+            max-width: 100%;
+            width: 100%;
+            overflow: hidden;
+        }
+        .hero-left { text-align: center; padding-top: 0; }
+        .hero-right { margin-top: 1.5rem; overflow: hidden; width: 100%; }
+        .hero-right > div { max-width: 100%; overflow: hidden; width: 100%; }
+        .hero-showcase { width: 100%; max-width: 100%; }
+        .hero-terminal { width: 100%; max-width: 100%; box-sizing: border-box; }
+        .hero-showcase { aspect-ratio: 16 / 10; }
+        .hero-cta { justify-content: center; }
+        .hero-pills { justify-content: center; }
+        .hero-terminal { max-width: 100%; overflow: hidden; }
+        .hero-terminal-body { padding: 0.5rem 0.7rem; gap: 0.4rem; }
+        .hero-terminal-prompt { font-size: 0.7rem; }
+        .hero-terminal-cmd { font-size: 0.65rem; }
+        .hero-terminal-copy { font-size: 0.62rem; padding: 0.2rem 0.4rem; }
+        .hero-terminal-copy .copy-label { display: none; }
+        .hero-rotating-line { text-align: center; }
+        .hero-subtitle { margin-left: auto; margin-right: auto; }
+
         .hero-stats {
             grid-template-columns: repeat(2, 1fr);
             gap: 1rem;
@@ -1798,6 +2245,8 @@
             flex-direction: column;
             align-items: center;
         }
+        .hero-pills { gap: 0.4rem; }
+        .hero-pill { font-size: 0.68rem; padding: 0.25rem 0.6rem; }
 
         .cta-buttons {
             flex-direction: column;
@@ -1818,7 +2267,15 @@
         .hero { padding-left: 1rem; padding-right: 1rem; }
         .section { padding: 3rem 0; }
         .section-header { margin-bottom: 2.5rem; }
-        .hero-stats { grid-template-columns: repeat(2, 1fr); }
+        .hero-stats { grid-template-columns: repeat(2, 1fr); padding: 1rem; }
+        .hero-showcase { aspect-ratio: 16 / 11; }
+        .showcase-card-title { font-size: 0.85rem; }
+        .showcase-card-subtitle { font-size: 0.65rem; }
+        .showcase-card-caption { padding: 1.5rem 1rem 0.75rem; }
+        .hero-terminal-cmd { font-size: 0.58rem; }
+        .hero-terminal-prompt { font-size: 0.6rem; }
+        .hero-terminal-title { font-size: 0.55rem; }
+        .hero-terminal-dot { width: 6px; height: 6px; }
         .live-stats { grid-template-columns: 1fr; }
     }
 
@@ -2102,72 +2559,175 @@
      HERO
      ============================================ -->
 
    
+    
+    
+
     
     
    
         
    
         
-        
     
    
 
     
    
-        
    Self-Hosted Campaign Infrastructure
    
-        
    Grow Power.
    Don't Rent It.
    
-        
    
-            Run your campaigns, canvassing, fundraising, team chat, media, and more — all on your own infrastructure.
-            No corporate surveillance. No foreign interference. No monthly ransoms.
-            A free* and open source toolkit built for growing political movements.
-        
    
-        
    
-            Explore the Demo 
-            Schedule a Chat
-            Source Code
+        
+        
    
+            
+            
    Self-Hosted Campaign Infrastructure
    
+            
    Grow Power.
    Don't Rent It.
    
+
+            
    
+                Your  — on your own infrastructure.
+            
    
+
+            
    
+                No corporate surveillance. No foreign interference. No monthly ransoms.
+                A free* and open source toolkit built for growing political movements.
+            
    
+
+            
    
+                Explore the Demo 
+                Schedule a Chat
+                Source Code
+            
    
+
+            
+            
+
         
    
 
-        
-        
    
-            
    
-                
-                
-                
-            
    
-            
    
-                
    
-                    
-                    
+        
+        
    
+            
    
+                
    
+                    
+                    
    
+                        Advocacy campaigns dashboard showing campaign list with status badges, email counts, and response tracking
+                        
    
+                            
    ✉
    
+                            
    
+                                
    Advocacy Campaigns
    
+                                
    Email your representatives in 3 clicks
    
+                            
    
+                        
    
+                    
    
+
+                    
+                    
    
+                        Canvassing dashboard with live volunteer map, cut progress tracking, and activity feed
+                        
    
+                            
    🌎
    
+                            
    
+                                
    GPS Canvassing
    
+                                
    Track door-to-door outreach in real time
    
+                            
    
+                        
    
+                    
    
+
+                    
+                    
    
+                        Media library with video thumbnails, filters, and publishing controls
+                        
    
+                            
    🎥
    
+                            
    
+                                
    Media Library
    
+                                
    Host, schedule, and share your campaign videos
    
+                            
    
+                        
    
+                    
    
+
+                    
+                    
    
+                        Shift management dashboard with stats, table view, and volunteer signups
+                        
    
+                            
    📅
    
+                            
    
+                                
    Volunteer Management
    
+                                
    Coordinate shifts, track attendance, grow your team
    
+                            
    
+                        
    
+                    
    
+                
    
+                
    
+                    
+                    
+                    
+                    
+                
    
+
+                
+                
    
+                    
    
+                        
+                        
+                        
+                        Quick Deploy on Linux w/ Docker
+                    
    
+                    
    
+                        $
+                        curl -fsSL gitea.bnkops.com/admin/changemaker.lite/raw/branch/main/scripts/install.sh | bash
+                        
+                    
    
                 
    
-                
    
             
    
         
    
 
-        
    
-            
    
-                
    100%
    
-                
    Data Ownership
    
+        
+        
    
+            
    
+                
    
+                    
    0%
    
+                    
    Data Ownership
    
+                
    
+                
    
+                    
    $0
    
+                    
    Self-Hosted
    
+                
    
+                
    
+                    
    0+
    
+                    
    Integrated Tools
    
+                
    
+                
    
+                    
    FOSS
    
+                    
    Open Source
    
+                
    
             
    
-            
    
-                
    $0
    
-                
    Self-Hosted
    
-            
    
-            
    
-                
    45+
    
-                
    Integrated Tools
    
-            
    
-            
    
-                
    FOSS
    
-                
    Open Source
    
+            
    
+                
+                Self-hosted by community organizers across Canada
             
    
         
    
     
    
 
    
 
+
+
    
+    
    
+        
    🚧
    
+        
    Now in Beta
    
+        
    Changemaker Lite is under active development and breaking changes are still being pushed. A stable release is expected by June 2026.
    
+        
+    
    
+
    
+
 
@@ -2274,7 +2834,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
    📨
    
                 
    
@@ -2363,7 +2923,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
    🗺
    
                 
    
@@ -2448,7 +3008,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
    🎬
    
                 
    
@@ -2537,7 +3097,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
    📊
    
                 
    
@@ -2608,7 +3168,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
    🛡
    
                 
    
@@ -2684,7 +3244,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
    💳
    
                 
    
@@ -2755,7 +3315,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
                 
    
@@ -2817,7 +3377,7 @@
         
    
 
         
-        
    
+        
    
             
    
                 
    🇨🇦
    
                 
    
@@ -3851,6 +4411,275 @@
         }
     };
 
+    /* ===========================================
+       BETA MODAL
+       =========================================== */
+    const BetaModal = {
+        init() {
+            const pill = document.getElementById('beta-pill');
+            const backdrop = document.getElementById('beta-modal-backdrop');
+            const closeBtn = document.getElementById('beta-modal-close');
+            if (!pill || !backdrop || !closeBtn) return;
+            pill.addEventListener('click', () => backdrop.classList.add('open'));
+            closeBtn.addEventListener('click', () => backdrop.classList.remove('open'));
+            backdrop.addEventListener('click', (e) => { if (e.target === backdrop) backdrop.classList.remove('open'); });
+            document.addEventListener('keydown', (e) => { if (e.key === 'Escape' && backdrop.classList.contains('open')) backdrop.classList.remove('open'); });
+        }
+    };
+
+    /* ===========================================
+       TERMINAL COPY — clipboard for install cmd
+       =========================================== */
+    const TerminalCopy = {
+        init() {
+            const btn = document.getElementById('hero-copy-btn');
+            if (!btn) return;
+            btn.addEventListener('click', () => {
+                const cmd = 'curl -fsSL gitea.bnkops.com/admin/changemaker.lite/raw/branch/main/scripts/install.sh | bash';
+                navigator.clipboard.writeText(cmd).then(() => {
+                    btn.classList.add('copied');
+                    btn.querySelector('.copy-label').textContent = 'Copied!';
+                    setTimeout(() => {
+                        btn.classList.remove('copied');
+                        btn.querySelector('.copy-label').textContent = 'Copy';
+                    }, 2000);
+                });
+            });
+        }
+    };
+
+    /* ===========================================
+       TYPEWRITER — rotating hero words
+       =========================================== */
+    const Typewriter = {
+        words: ['campaigns', 'canvassing', 'fundraising', 'newsletters', 'media library', 'volunteer shifts', 'team chat', 'events'],
+        el: null,
+        wordIdx: 0,
+        charIdx: 0,
+        isDeleting: false,
+        timeout: null,
+
+        init() {
+            this.el = document.getElementById('tw-word');
+            if (!this.el) return;
+            if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+                this.el.textContent = this.words[0];
+                return;
+            }
+            this.tick();
+        },
+
+        tick() {
+            const word = this.words[this.wordIdx];
+
+            if (this.isDeleting) {
+                this.charIdx--;
+            } else {
+                this.charIdx++;
+            }
+
+            this.el.textContent = word.substring(0, this.charIdx);
+
+            let delay = this.isDeleting ? 40 : 80;
+
+            if (!this.isDeleting && this.charIdx === word.length) {
+                delay = 2200;
+                this.isDeleting = true;
+            } else if (this.isDeleting && this.charIdx === 0) {
+                this.isDeleting = false;
+                this.wordIdx = (this.wordIdx + 1) % this.words.length;
+                delay = 400;
+            }
+
+            this.timeout = setTimeout(() => this.tick(), delay);
+        }
+    };
+
+    /* ===========================================
+       FEATURE PILLS — staggered entrance
+       =========================================== */
+    const FeaturePills = {
+        init() {
+            const pills = document.querySelectorAll('.hero-pill');
+            if (!pills.length) return;
+            if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+                pills.forEach(p => p.classList.add('visible'));
+                return;
+            }
+            pills.forEach((pill, i) => {
+                setTimeout(() => pill.classList.add('visible'), 600 + i * 120);
+            });
+        }
+    };
+
+    /* ===========================================
+       FEATURE SHOWCASE — rotating cards
+       =========================================== */
+    const FeatureShowcase = {
+        current: 0,
+        cards: [],
+        dots: [],
+        interval: null,
+        DURATION: 5000,
+
+        init() {
+            this.cards = document.querySelectorAll('.showcase-card');
+            this.dots = document.querySelectorAll('.showcase-dot');
+            if (this.cards.length < 2) return;
+
+            this.dots.forEach(dot => {
+                dot.addEventListener('click', () => {
+                    const idx = parseInt(dot.getAttribute('data-idx'), 10);
+                    if (idx !== this.current) this.goTo(idx);
+                });
+            });
+
+            this.startAutoplay();
+        },
+
+        goTo(idx) {
+            const prev = this.cards[this.current];
+            prev.classList.remove('active');
+            prev.classList.add('exiting');
+            setTimeout(() => prev.classList.remove('exiting'), 600);
+
+            this.current = idx;
+            this.cards[this.current].classList.add('active');
+
+            this.dots.forEach((d, i) => d.classList.toggle('active', i === idx));
+            this.restartAutoplay();
+        },
+
+        next() {
+            this.goTo((this.current + 1) % this.cards.length);
+        },
+
+        startAutoplay() {
+            this.interval = setInterval(() => this.next(), this.DURATION);
+        },
+
+        restartAutoplay() {
+            clearInterval(this.interval);
+            this.startAutoplay();
+        }
+    };
+
+    /* ===========================================
+       COUNT-UP STATS — animated number counters
+       =========================================== */
+    const CountUpStats = {
+        init() {
+            const stats = document.querySelectorAll('.hero-stat-value[data-count]');
+            if (!stats.length) return;
+            if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+                stats.forEach(el => {
+                    const target = parseInt(el.getAttribute('data-count'), 10);
+                    const prefix = el.getAttribute('data-prefix') || '';
+                    const suffix = el.getAttribute('data-suffix') || '';
+                    el.textContent = prefix + target + suffix;
+                });
+                return;
+            }
+
+            const obs = new IntersectionObserver((entries) => {
+                entries.forEach(entry => {
+                    if (entry.isIntersecting) {
+                        this.animate(entry.target);
+                        obs.unobserve(entry.target);
+                    }
+                });
+            }, { threshold: 0.5 });
+
+            stats.forEach(el => obs.observe(el));
+        },
+
+        animate(el) {
+            const target = parseInt(el.getAttribute('data-count'), 10);
+            const prefix = el.getAttribute('data-prefix') || '';
+            const suffix = el.getAttribute('data-suffix') || '';
+            const duration = 1400;
+            const start = performance.now();
+
+            const step = (now) => {
+                const progress = Math.min((now - start) / duration, 1);
+                const eased = 1 - Math.pow(1 - progress, 3);
+                const current = Math.round(eased * target);
+                el.textContent = prefix + current + suffix;
+                if (progress < 1) requestAnimationFrame(step);
+            };
+            requestAnimationFrame(step);
+        }
+    };
+
+    /* ===========================================
+       PARTICLE DRIFT — floating background dots
+       =========================================== */
+    const ParticleDrift = {
+        canvas: null,
+        ctx: null,
+        particles: [],
+        raf: null,
+        COUNT: 35,
+
+        init() {
+            this.canvas = document.getElementById('hero-particles');
+            if (!this.canvas) return;
+            if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return;
+            // Fewer particles on mobile
+            if (window.innerWidth < 768) this.COUNT = 15;
+
+            this.ctx = this.canvas.getContext('2d');
+            this.resize();
+            this.createParticles();
+            this.loop();
+            window.addEventListener('resize', () => this.resize());
+        },
+
+        resize() {
+            const hero = this.canvas.parentElement;
+            this.canvas.width = hero.offsetWidth;
+            this.canvas.height = hero.offsetHeight;
+        },
+
+        createParticles() {
+            this.particles = [];
+            for (let i = 0; i < this.COUNT; i++) {
+                this.particles.push({
+                    x: Math.random() * this.canvas.width,
+                    y: Math.random() * this.canvas.height,
+                    r: Math.random() * 2 + 0.5,
+                    vx: (Math.random() - 0.5) * 0.3,
+                    vy: -(Math.random() * 0.4 + 0.1),
+                    alpha: Math.random() * 0.3 + 0.1,
+                });
+            }
+        },
+
+        loop() {
+            const { ctx, canvas, particles } = this;
+            ctx.clearRect(0, 0, canvas.width, canvas.height);
+
+            const isDark = document.documentElement.getAttribute('data-theme') !== 'light';
+            const baseColor = isDark ? '139, 92, 246' : '111, 66, 193';
+
+            particles.forEach(p => {
+                p.x += p.vx;
+                p.y += p.vy;
+                // Wrap around
+                if (p.y < -5) { p.y = canvas.height + 5; p.x = Math.random() * canvas.width; }
+                if (p.x < -5) p.x = canvas.width + 5;
+                if (p.x > canvas.width + 5) p.x = -5;
+
+                ctx.beginPath();
+                ctx.arc(p.x, p.y, p.r, 0, Math.PI * 2);
+                ctx.fillStyle = `rgba(${baseColor}, ${p.alpha})`;
+                ctx.fill();
+            });
+
+            this.raf = requestAnimationFrame(() => this.loop());
+        }
+    };
+
     /* ===========================================
        BOOT
        =========================================== */
@@ -3864,7 +4693,14 @@
         FloatingElements.init();
         SmoothScroll.init();
         FreeModal.init();
+        BetaModal.init();
         initSearch();
+        TerminalCopy.init();
+        Typewriter.init();
+        FeaturePills.init();
+        FeatureShowcase.init();
+        CountUpStats.init();
+        ParticleDrift.init();
     });
 
 })();
diff --git a/mkdocs/site/search/search_index.json b/mkdocs/site/search/search_index.json
index 1b81ae08..99e3b73f 100644
--- a/mkdocs/site/search/search_index.json
+++ b/mkdocs/site/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\u200b\\-_,:!=\\[\\]()\"`/]+|\\.(?!\\d)|&[lg]t;|(?!\\b)(?=[A-Z][a-z])","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"blog/","title":"Blog","text":""},{"location":"blog/2026/03/22/introducing-changemaker-lite-v2/","title":"Introducing Changemaker Lite v2","text":"
    Changemaker Lite v2 is a ground-up rebuild of the platform \u2014 same mission, entirely new architecture. After 14 phases of development, the platform is ready for production use.
    ","tags":["v2","release","self-hosted","FOSS"]},{"location":"blog/2026/03/22/introducing-changemaker-lite-v2/#what-changed","title":"What Changed","text":"
    V1 was two independent Express apps stitched together with NocoDB as a data layer. It worked, but scaling features meant fighting the architecture at every turn.
     
    V2 is a unified TypeScript stack:
     
       
    • Dual API architecture \u2014 Express.js for the main platform, Fastify for the media library, sharing a single PostgreSQL 16 database via Prisma ORM
      •  
    • React admin GUI \u2014 Vite + Ant Design + Zustand, serving admin, public, and volunteer interfaces from one build
      •  
    • 30+ Docker services \u2014 from core infrastructure to monitoring, communication, and developer tools
      •  
    • JWT authentication with refresh token rotation, role-based access control (11 roles), and a comprehensive security audit
      •  
    ","tags":["v2","release","self-hosted","FOSS"]},{"location":"blog/2026/03/22/introducing-changemaker-lite-v2/#whats-new","title":"What's New","text":"
    The feature set has grown substantially:
     
       
    • Advocacy campaigns with postal code \u2192 representative lookup, email sending, response walls, and moderation
      •  
    • Map & canvassing with multi-provider geocoding, polygon territories, GPS-tracked volunteer sessions, and walking route generation
      •  
    • Media manager with video upload, FFprobe metadata extraction, scheduled publishing, analytics, and a public gallery
      •  
    • Landing page builder powered by GrapesJS with drag-and-drop editing
      •  
    • Payments via encrypted Stripe integration \u2014 products, donations, and subscription plans
      •  
    • SMS campaigns via a Termux Android bridge
      •  
    • Team communication with self-hosted Rocket.Chat and Jitsi Meet
      •  
    • People CRM aggregating contacts across all modules with duplicate detection and merge
      •  
    • Volunteer social features \u2014 friend system, achievements, leaderboards, and a personal calendar
      •  
    • One-command install \u2014 curl | bash pulls a release tarball and runs the config wizard
      •  
    ","tags":["v2","release","self-hosted","FOSS"]},{"location":"blog/2026/03/22/introducing-changemaker-lite-v2/#why-self-hosted","title":"Why Self-Hosted","text":"
    Every subscription to corporate campaign software funds infrastructure you don't control. Your voter lists, canvassing outcomes, and communication patterns become assets on someone else's balance sheet.
     
    Changemaker Lite costs roughly the price of a VPS \u2014 often under $50/month for the full stack. But the real value isn't cost savings. It's control. No vendor can cut off your access. No acquisition can change your terms.
     
    Read more in our Philosophy page.
    ","tags":["v2","release","self-hosted","FOSS"]},{"location":"blog/2026/03/22/introducing-changemaker-lite-v2/#get-started","title":"Get Started","text":"
    curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/v2/scripts/install.sh | bash\n
     
    Or follow the Getting Started guide for a walkthrough.
    ","tags":["v2","release","self-hosted","FOSS"]},{"location":"blog/2026/03/22/introducing-changemaker-lite-v2/#whats-next","title":"What's Next","text":"
    Phase 15 (Testing & Polish) is underway. We're also working on:
     
       
    • Social Calendar Phase B (shared views, availability finder)
      •  
    • Expanded test coverage
      •  
    • Performance optimization for large location datasets
      •  
     
    Follow this blog for updates, or subscribe to the newsletter.
    ","tags":["v2","release","self-hosted","FOSS"]},{"location":"comments/callback/","title":"Signing in...","text":"
    Completing sign in...
     
    You will be redirected back to the page you were on.
    "},{"location":"docs/","title":"Documentation","text":"
    Welcome to the Changemaker Lite documentation. Whether you're a campaign volunteer, an admin managing operations, or a sysadmin deploying the platform \u2014 start here.
    ","tags":["guide","getting-started"],"boost":2},{"location":"docs/#use-the-platform","title":"Use the Platform","text":"
       
    •  
       Getting Started
       
      Install Changemaker Lite, create your first admin account, and explore the dashboard.
       
       Getting Started
       
      •  
    •  
       Feature Guides
       
      Campaigns, email advocacy, response walls, map locations, landing pages, and media.
       
       Feature Guides
       
      •  
    •  
       Administration
       
      User management, roles and permissions, site settings, email templates, and newsletters.
       
       Administration
       
      •  
    •  
       Volunteer Guide
       
      Sign up for shifts, use the canvassing map, record visits, and track your activity.
       
       Volunteer Guide
       
      •  
    ","tags":["guide","getting-started"],"boost":2},{"location":"docs/#deploy-operate","title":"Deploy & Operate","text":"
       
    •  
       Deployment
       
      Docker Compose setup, environment variables, SSL/TLS, backups, and production checklist.
       
       Deployment
       
      •  
    •  
       Architecture
       
      Dual API design, database schema, authentication flow, and system diagram.
       
       Architecture
       
      •  
    •  
       Services
       
      Nginx routing, Redis, PostgreSQL, Listmonk, MkDocs, Gitea, NocoDB, and more.
       
       Services
       
      •  
    •  
       Monitoring
       
      Prometheus metrics, Grafana dashboards, Alertmanager rules, and health checks.
       
       Monitoring
       
      •  
    ","tags":["guide","getting-started"],"boost":2},{"location":"docs/#reference","title":"Reference","text":"
       
    •  
       API Reference
       
      REST endpoints for auth, campaigns, locations, shifts, media, and more.
       
       API Reference
       
      •  
    •  
       Troubleshooting
       
      Common errors, CORS issues, database problems, tunnel debugging, and FAQ.
       
       Troubleshooting
       
      •  
    •  
       Security
       
      Password policy, rate limiting, token rotation, encryption, and audit report.
       
       Security See Deployment
       
      •  
    •  
       Contributing
       
      Development setup, code style, git workflow, and pull request guidelines.
       
       Contributing
       
      •  
    ","tags":["guide","getting-started"],"boost":2},{"location":"docs/#platform-at-a-glance","title":"Platform at a Glance","text":"Component Technology Purpose Main API Express.js + Prisma Auth, campaigns, map, shifts, pages, email Media API Fastify + Prisma Video library, analytics, upload, scheduling Admin GUI React + Ant Design + Zustand Dashboard for admins and organizers Database PostgreSQL 16 Single shared database for both APIs Cache Redis Rate limiting, BullMQ jobs, geocoding queue Proxy Nginx Subdomain routing, security headers, SSL Tunnel Pangolin + Newt Expose services without port forwarding Monitoring Prometheus + Grafana Metrics, dashboards, alerts 
    New here?
     
    Start with the Getting Started guide to have the platform running in under 30 minutes.
     
    Looking for the source?
     
    Changemaker Lite is 100% open source. Browse the code on Gitea.
    ","tags":["guide","getting-started"],"boost":2},{"location":"docs/phil/","title":"Philosophy","text":"","tags":["concept","philosophy","FOSS"]},{"location":"docs/phil/#software-is-political","title":"Software Is Political","text":"
    Every tool your movement adopts shapes how you organize. Proprietary platforms reinforce hierarchy \u2014 the vendor decides what features you get, what data you can export, and what happens when you stop paying. Community-controlled tools support democratic autonomy because the people using them decide how they work.
     
    If you do politics, who is reading your secrets? Corporate platforms harvest political intelligence systematically. Facebook chat data has been used in criminal prosecutions. Social media platforms are leveraged for political coordination and surveillance. When you organize on corporate infrastructure, you hand your strategies, your voter data, and your movement's internal conversations to entities that may have every reason to work against you.
     
    Changemaker Lite exists because we believe organizational independence requires technological independence.
    ","tags":["concept","philosophy","FOSS"]},{"location":"docs/phil/#the-extractive-model","title":"The Extractive Model","text":"
    Most campaign and political software is extractive by design. The pattern is familiar:
     
       
    1. Free trial hooks you in
      2.  
    2. Paid features gate the tools you actually need
      3.  
    3. Data export becomes difficult or impossible
      4.  
    4. Pricing escalates as you grow and become dependent
      5.  
    5. Your usage patterns are monetized through data partnerships, behavioral analytics, and enterprise contracts
      6.  
     
    This isn't a side effect \u2014 it's the business model. You pay with money and with data. Your voter lists, canvassing outcomes, donor records, and communication patterns become assets on someone else's balance sheet.
     
    Every subscription to corporate software funds the machine you're fighting.
    ","tags":["concept","philosophy","FOSS"]},{"location":"docs/phil/#the-alternative-grow-power-dont-rent-it","title":"The Alternative: Grow Power, Don't Rent It","text":"
    Changemaker asks a different question than most political tech: instead of \"how do we extract more data from a community?\" we ask \"what tools are needed to grow change in a community?\"
     
    Growing change means:
     
       
    • Making real connections between organizers, volunteers, and community members \u2014 not just collecting their contact info
      •  
    • Providing access to the same caliber of tools that well-funded campaigns use \u2014 without the price tag or the surveillance
      •  
    • Deeply understanding the wants and needs of your movement \u2014 on infrastructure you control, with data you own
      •  
    ","tags":["concept","philosophy","FOSS"]},{"location":"docs/phil/#distributed-organizing-is-the-way-out","title":"Distributed Organizing Is The Way Out","text":"
    Socialist movements will never outspend capital. Progressive organizations cannot compete financially with well-funded conservative movements, and chasing big-donor dollars leads to mission drift and organizational capture \u2014 what some call the Political Industrial Complex.
     
    A thousand neighborhood mailing lists has more potential impact than any single organization. When organizing knowledge and digital tools are widely distributed \u2014 not gatekept by leadership or locked behind vendor paywalls \u2014 movements become genuinely resilient.
     
    The historical pattern is clear: worker victories occurred when organizing knowledge was widely distributed, not concentrated at the top. Changemaker Lite is built on this premise \u2014 provide the tools freely, train people to use them, and get out of the way.
     
    Workers, with the right tools, will build the future.
    ","tags":["concept","philosophy","FOSS"]},{"location":"docs/phil/#de-corp-your-stack","title":"De-Corp Your Stack","text":"
    The practical work of digital sovereignty starts with replacing corporate services one at a time:
     Corporate Tool Changemaker Alternative What You Gain Mailchimp Listmonk Unlimited subscribers, no per-send charges, your data stays local NationBuilder Changemaker Lite Full campaign platform without the $50-500/month ransom Google Docs Gitea + Code Server Version control, collaboration, no algorithmic scanning Slack Rocket.Chat Team chat with SSO, no message limits, no corporate eavesdropping SurveyMonkey Response Wall Supporter voices on your terms, with moderation you control Google Maps Self-hosted Leaflet No API fees, no tracking, offline-capable canvassing 
    The cost reduction is dramatic. Organizations spending thousands monthly on SaaS tools can replace them with a single self-hosted server running Changemaker Lite for roughly the cost of hosting \u2014 often under $50/month.
     
    But the real value isn't cost savings. It's control. No vendor can cut off your access. No acquisition can change your terms. No government can compel a foreign company to hand over your data. Your movement's digital infrastructure belongs to your movement.
    ","tags":["concept","philosophy","FOSS"]},{"location":"docs/phil/#security-culture-starts-with-infrastructure","title":"Security Culture Starts With Infrastructure","text":"
    Security culture isn't just about who knows what \u2014 it's about who can know what. When your communications run through corporate servers, you've made a structural decision about who has access before you've even thought about operational security.
     
    Key principles:
     
       
    • Compartmentalization by design \u2014 Self-hosted systems let you control exactly who has access to what, at the infrastructure level
      •  
    • No third-party access \u2014 No corporate subpoenas for your data, no partnership agreements sharing your information
      •  
    • Audit everything \u2014 When you run the servers, you can verify that your security promises are real, not just marketing
      •  
    • Consent and autonomy \u2014 Your community sets its own security boundaries rather than accepting whatever a vendor's privacy policy allows
      •  
     
    You wouldn't hold a sensitive strategy meeting in a room wired by someone else. Why would you plan your campaign on someone else's servers?
    ","tags":["concept","philosophy","FOSS"]},{"location":"docs/phil/#our-principles","title":"Our Principles","text":"
    Liberation First Technology should center marginalized voices. The tools we build reflect the values we hold, and they shape the movements that use them.
     
    Community Over Profit Changemaker Lite is free and open source software, built by a cooperative \u2014 not a startup looking for an exit. There are no shareholders to satisfy, no venture capitalists to answer to. The software serves the community because that's the only thing it's designed to do.
     
    Data Sovereignty Communities should own their complete digital infrastructure. Not just the content \u2014 the servers, the databases, the encryption keys, and the ability to pack up and leave at any time.
     
    Radical Accessibility Self-hosted doesn't have to mean self-excluding. Changemaker Lite is designed for organizers, not sysadmins. If you can follow a guide to set up a WordPress site, you can run this platform.
    ","tags":["concept","philosophy","FOSS"]},{"location":"docs/phil/#further-reading","title":"Further Reading","text":"
    These articles explore the ideas behind Changemaker Lite in depth:
     
       
    • If You Do Politics, Who Is Reading Your Secrets? \u2014 Why you should de-corp your software stack
      •  
    • Distributed Digital Organizing Is The Way Out \u2014 Why decentralized power structures outperform centralized ones
      •  
    • How Not To Get Got Making Content \u2014 Platform independence for political content creators
      •  
    • What Is Security Culture? \u2014 The foundations of security culture for movements
      •  
    ","tags":["concept","philosophy","FOSS"]},{"location":"docs/admin/","title":"Admin Guide","text":"
    The admin panel at /app is your command center for managing the entire platform. Use the sidebar to navigate between modules, or press Ctrl+K to open the command palette for quick access to any page, setting, or action.
    ","tags":["guide","admin"]},{"location":"docs/admin/#sections","title":"Sections","text":"
       
    •  
       Dashboard
       
      Live overview of platform activity, upcoming shifts, email stats, and service health.
       
      •  
    •  
       People & Access
       
      User management, roles, the People CRM, and contact merging.
       
      •  
    •  
       Advocacy
       
      Campaigns, response moderation, representative lookup, and email queue monitoring.
       
      •  
    •  
       Broadcast
       
      Newsletter sync, email templates, and SMS campaigns.
       
      •  
    •  
       Web Content
       
      Landing pages, homepage, navigation menu, and documentation management.
       
      •  
    •  
       Map & Canvassing
       
      Locations, areas, shifts, canvassing dashboard, data quality, and map settings.
       
      •  
    •  
       Media
       
      Video/photo library, analytics, playlists, comment moderation, and gallery ads.
       
      •  
    •  
       Payments
       
      Products, donations, subscription plans, and Stripe configuration.
       
      •  
    •  
       Services
       
      Tunnel management, monitoring, and third-party integrations.
       
      •  
    •  
       Settings
       
      Organization branding, theme colors, email config, feature toggles, and notifications.
       
      •  
    ","tags":["guide","admin"]},{"location":"docs/admin/#roles-reference","title":"Roles Reference","text":"Role Access Level SUPER_ADMIN Full platform access \u2014 implicitly bypasses all role checks INFLUENCE_ADMIN Campaigns, responses, representatives, email queue MAP_ADMIN Locations, areas, shifts, canvassing, data quality BROADCAST_ADMIN Newsletter sync, email templates CONTENT_ADMIN Landing pages, homepage, navigation, documentation MEDIA_ADMIN Video library, analytics, gallery, moderation, ads PAYMENTS_ADMIN Products, donations, plans, Stripe configuration EVENTS_ADMIN Gancio event sync and calendar management SOCIAL_ADMIN Social connections, achievements, calendar layers USER Volunteer portal only TEMP Limited volunteer access (auto-created on shift signup)","tags":["guide","admin"]},{"location":"docs/admin/dashboard/","title":"Dashboard","text":"
    The admin dashboard (/app) provides a real-time overview of platform activity.
     
    ","tags":["guide","admin"]},{"location":"docs/admin/dashboard/#dashboard-cards","title":"Dashboard Cards","text":"
       
    • Platform Stats \u2014 active campaigns, total emails sent, registered users, and location count
      •  
    • Activity Feed \u2014 recent events across all modules (signups, emails, visits, responses)
      •  
    • Upcoming Shifts \u2014 next scheduled volunteer shifts with signup counts
      •  
    • Newsletter Stats \u2014 Listmonk subscriber counts and recent campaign performance
      •  
    • Chat Activity \u2014 Rocket.Chat channel activity and online users (when chat is enabled)
      •  
    • Service Health \u2014 connectivity status for integrated services (Gitea, Gancio, Vaultwarden, etc.)
      •  
     
    All cards auto-refresh and gracefully degrade when their associated module is disabled.
    ","tags":["guide","admin"]},{"location":"docs/admin/people-access/","title":"People & Access","text":"
    Manage platform user accounts and roles, and use the People CRM to get a unified view of every supporter, donor, and volunteer across all modules.
     
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#user-management","title":"User Management","text":"","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#creating-users","title":"Creating Users","text":"
    Navigate to Users (/app/users) and click Add User. Fill in name, email, and role. The user will receive a welcome email with login instructions.
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#roles","title":"Roles","text":"Role Access Use Case SUPER_ADMIN Full platform access Campaign managers INFLUENCE_ADMIN Campaigns, responses, email queue Advocacy coordinators MAP_ADMIN Locations, areas, shifts, canvassing Field organizers USER Volunteer portal only Active volunteers TEMP Limited volunteer access Shift signups (auto-created)","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#password-policy","title":"Password Policy","text":"
    Passwords must be at least 12 characters with uppercase, lowercase, and a digit. This is enforced at the API schema level.
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#deactivating-users","title":"Deactivating Users","text":"
    Edit a user from the Users page and toggle their active status. Deactivated users cannot log in but their data is preserved. Banned users have their sessions invalidated immediately.
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#service-accounts-panel","title":"Service Accounts Panel","text":"
    When editing a user, the Service Accounts panel shows provisioning status for each integrated service (Rocket.Chat, Gitea, Vaultwarden, Listmonk). You can provision, deprovision, or re-sync individual services per user.
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#people-crm","title":"People CRM","text":"
    Enable with enablePeople in Settings. The People module serves as the platform's CRM, aggregating data from all other modules into a unified view.
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#virtual-aggregation","title":"Virtual Aggregation","text":"
    The People page does not store a separate \"people\" table. Instead, it aggregates records in real time from seven data sources:
     Source Data Users Platform accounts (name, email, phone, last login) Address Occupants Named residents from the map/canvassing module Campaign Senders People who sent advocacy emails Shift Signups Volunteer shift registrants SMS Contacts Contacts from SMS campaign lists Donations/Orders Buyers from the payments module Manual Contacts created directly in the CRM 
    Records are deduplicated by normalized email or phone number, with Users taking highest priority.
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#managed-contacts","title":"Managed Contacts","text":"
    Any virtual person can be \"promoted\" to a managed Contact record. This creates a persistent Contact entity in the database with:
     
       
    • Display name, first/last name \u2014 editable independently of the source
      •  
    • Tags \u2014 custom CRM tags for segmentation and filtering
      •  
    • Notes \u2014 free-text notes field
      •  
    • Support level \u2014 LEVEL_1 (Strong) through LEVEL_4 (Opposition)
      •  
    • Opt-out flags \u2014 email opt-out, SMS opt-out, and do-not-contact
      •  
    • Sign requested \u2014 track yard sign status
      •  
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#contact-details","title":"Contact Details","text":"
    Each managed contact supports multiple structured data entries:
     
       
    • Addresses \u2014 link to map locations with optional unit numbers and primary flag; new addresses can be auto-added to the map for geocoding
      •  
    • Emails \u2014 multiple email addresses with labels (e.g., Personal, Work) and primary designation
      •  
    • Phones \u2014 multiple phone numbers with labels and primary designation
      •  
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#activity-timeline","title":"Activity Timeline","text":"
    View a chronological timeline of all interactions for a person, across every module:
     
       
    • Advocacy emails sent and responses submitted
      •  
    • Shift signups and canvass visits
      •  
    • Donations and product purchases
      •  
    • SMS messages sent and received
      •  
    • Video views
      •  
    • Notes added and contact merges
      •  
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#duplicate-detection-and-merge","title":"Duplicate Detection and Merge","text":"
    The platform identifies potential duplicates by matching normalized email addresses and phone numbers across sources. The merge workflow lets you:
     
       
    • Select which fields to keep from the source vs. target contact
      •  
    • Merge tags, addresses, emails, and phones
      •  
    • Preserve the full audit trail (merged contacts are soft-linked, not deleted)
      •  
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#connection-graph","title":"Connection Graph","text":"
    Build a relationship graph between contacts using typed connections:
     
       
    • Connection types \u2014 Household, Family, Colleague, Referred By, and Custom
      •  
    • Bidirectional \u2014 connections can be one-way or mutual
      •  
    • Visual graph \u2014 interactive force-directed graph visualization showing contacts as nodes and connections as edges
      •  
    • Configurable depth \u2014 explore up to 3 degrees of separation
      •  
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#profile-links","title":"Profile Links","text":"
    Generate shareable public profile pages for contacts:
     
       
    • Unique token URLs at /profile/:token
      •  
    • Configurable expiration \u2014 24 hours, 7 days, 30 days, 90 days, 1 year, or never
      •  
    • Optional password protection \u2014 require a PIN or password to view
      •  
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#household-detection","title":"Household Detection","text":"
    The Household panel groups contacts who share the same physical address, making it easy to see all members of a household and their combined engagement.
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#create-user-from-contact","title":"Create User from Contact","text":"
    Promote a CRM contact to a full platform user account directly from the People interface, with role assignment and optional welcome email.
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#admin-routes","title":"Admin Routes","text":"
       
    • /app/users \u2014 user CRUD, role assignment, service accounts
      •  
    • /app/people \u2014 contact list with search, filters, source/tag filtering, and bulk actions
      •  
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/settings/","title":"Platform Settings","text":"
    Centralized configuration for organization identity, theming, email delivery, feature modules, and automated notifications.
     
    ","tags":["guide","admin","configuration"]},{"location":"docs/admin/settings/#settings-tabs","title":"Settings Tabs","text":"","tags":["guide","admin","configuration"]},{"location":"docs/admin/settings/#organization","title":"Organization","text":"
    Configure your organization's public identity:
     
       
    • Organization Name \u2014 displayed in the admin sidebar, public pages, and emails
      •  
    • Short Name \u2014 shown when the admin sidebar is collapsed (max 10 characters)
      •  
    • Logo URL \u2014 displayed on the login page, homepage hero, and public navigation
      •  
    • Favicon URL \u2014 browser tab icon
      •  
    • Footer Text \u2014 shown in public page footers
      •  
    • Login Subtitle \u2014 displayed below the organization name on the login page
      •  
    ","tags":["guide","admin","configuration"]},{"location":"docs/admin/settings/#theme-colors","title":"Theme Colors","text":"
    Customize the look of admin and public interfaces:
     
    Admin theme:
     
       
    • Primary color (accent color for buttons, links, active states)
      •  
    • Background color (page background)
      •  
     
    Public theme:
     
       
    • Primary color
      •  
    • Background color
      •  
    • Container color (card and section backgrounds)
      •  
    • Header gradient (CSS gradient string for the public navigation bar)
      •  
     
    A live preview panel shows color swatches and a gradient preview as you configure.
    ","tags":["guide","admin","configuration"]},{"location":"docs/admin/settings/#email","title":"Email","text":"
    Configure how the platform sends emails:
     
       
    • Sender \u2014 from name and from address for all outgoing emails
      •  
    • Active SMTP provider \u2014 toggle between MailHog (testing) and Production SMTP with a single click
      •  
    • Production SMTP \u2014 host, port, username, and password (collapsible panel, disabled when MailHog is active)
      •  
    • Test mode \u2014 when enabled, all emails redirect to a single test recipient address
      •  
    • Test actions \u2014 \"Test Connection\" verifies SMTP connectivity; \"Send Test Email\" delivers a test message through the active provider
      •  
     
    A configuration summary card at the top displays the current provider, server, authentication status, and test mode state.
    ","tags":["guide","admin","configuration"]},{"location":"docs/admin/settings/#feature-toggles","title":"Feature Toggles","text":"
    Enable or disable platform modules. Disabling a module hides it from navigation but does not delete data.
     Category Flag Description Core Platform enableInfluence Advocacy campaigns, email sending, response wall enableMap Map, locations, canvassing, volunteer shifts enableNewsletter Listmonk newsletter sync enableLandingPages GrapesJS landing page builder Media & Content enableMediaFeatures Video library, public gallery, analytics enableGalleryAds Promotional cards in the video gallery enableEvents Gancio event calendar integration Communication enableChat Rocket.Chat team coordination enableMeet Jitsi video meetings (integrates with Rocket.Chat) enableSms Termux Android SMS campaigns People & Engagement enablePeople Unified contacts CRM enableSocial Volunteer social connections and activity feeds autoSyncPeopleToMap Auto-create map locations from contact addresses Commerce enablePayments Stripe subscriptions, products, and donations","tags":["guide","admin","configuration"]},{"location":"docs/admin/settings/#notifications","title":"Notifications","text":"
    Control which automated email notifications the platform sends. Disabling a notification stops future emails but does not affect already-queued jobs.
     
    Admin alerts:
     
       
    • New shift signup
      •  
    • Response wall submission
      •  
    • Yard sign request (from canvassing)
      •  
    • Shift cancellation
      •  
     
    Volunteer emails:
     
       
    • Canvass session summary (sent after completing a session)
      •  
    • Signup cancellation confirmation
      •  
    • 24-hour pre-shift reminder
      •  
    • Post-shift thank-you (sent 2 hours after shift ends)
      •  
     
    Re-engagement:
     
       
    • Re-engagement emails for inactive volunteers
      •  
    • Configurable inactivity threshold (days without activity)
      •  
    • Configurable cooldown period (minimum days between re-engagement emails)
      •  
    ","tags":["guide","admin","configuration"]},{"location":"docs/admin/settings/#admin-routes","title":"Admin Routes","text":"
       
    • /app/settings \u2014 multi-tab settings page (supports deep-linking to a specific tab via router state)
      •  
    ","tags":["guide","admin","configuration"]},{"location":"docs/admin/advocacy/","title":"Advocacy","text":"
    The advocacy module helps supporters contact their elected representatives through email campaigns.
    ","tags":["guide","admin","influence"]},{"location":"docs/admin/advocacy/#in-this-section","title":"In This Section","text":"
       
    • Campaigns \u2014 create and publish advocacy campaigns with postal code lookup and response tracking
      •  
    • Responses \u2014 moderate the public response wall where supporters share representative replies
      •  
    • Representatives \u2014 manage the representative lookup cache powered by the Represent API
      •  
    • Email Queue \u2014 monitor outgoing advocacy emails, retry failures, and view delivery stats
      •  
    ","tags":["guide","admin","influence"]},{"location":"docs/admin/advocacy/campaigns/","title":"Advocacy Campaigns","text":"
    Help supporters contact their elected representatives through email campaigns.
     
    ","tags":["guide","admin","influence","campaigns"]},{"location":"docs/admin/advocacy/campaigns/#how-it-works","title":"How It Works","text":"
       
    1. An admin creates a campaign \u2014 writes the email subject and body, selects which government levels to target (federal, provincial, municipal, school board), and publishes it.
      2.  
    2. A supporter visits the campaign page \u2014 enters their postal code to look up their representatives.
      3.  
    3. The supporter sends the email \u2014 either directly through the platform (\"Send Now\") or by opening it in their own email app (Gmail, Outlook, etc.).
      4.  
    4. Responses get tracked \u2014 supporters and admins can share representative responses on the Response Wall, with upvoting and moderation.
      5.  
    ","tags":["guide","admin","influence","campaigns"]},{"location":"docs/admin/advocacy/campaigns/#key-features","title":"Key Features","text":"
       
    • Postal code lookup \u2014 powered by the Represent API, returns representatives at all government levels
      •  
    • Two send methods \u2014 server-sent SMTP (tracked) or mailto link (opens user's email app)
      •  
    • Email editing \u2014 optionally let supporters personalize the email before sending
      •  
    • Response Wall \u2014 public wall where people share how their representatives responded, with moderation and verification
      •  
    • Campaign stats \u2014 track emails sent, responses received, and upvotes
      •  
    • Featured campaigns \u2014 highlight important campaigns on the public listing page
      •  
    ","tags":["guide","admin","influence","campaigns"]},{"location":"docs/admin/advocacy/campaigns/#user-submitted-campaigns","title":"User-Submitted Campaigns","text":"
    Registered (non-temporary) users can create their own advocacy campaigns and submit them for admin review.
     
       
    • Public submission route \u2014 users visit /campaigns/create to draft a campaign through a guided wizard
      •  
    • 3-step wizard \u2014 the submission flow walks users through campaign details (title, description, government levels), email template (subject and body), and a final review step before submitting
      •  
    • My campaigns dashboard \u2014 users can view and manage their submitted campaigns at /campaigns/mine, including checking moderation status and editing campaigns that have been sent back for changes
      •  
    • Restricted fields \u2014 user-submitted campaigns have limited options compared to admin-created ones (no SMTP sending, no highlight, no custom recipients); only the mailto link fallback is enabled by default
      •  
    • Auto-moderation status \u2014 newly submitted campaigns start in PENDING_REVIEW status and remain in DRAFT until an admin approves them
      •  
    • Edit restrictions \u2014 users can only edit their own campaigns, and only when the moderation status is PENDING_REVIEW or CHANGES_REQUESTED; editing automatically resets the status back to PENDING_REVIEW
      •  
    • Rate limiting \u2014 campaign submissions are rate-limited to 5 per hour per IP to prevent abuse
      •  
    • XSS protection \u2014 all user-supplied text (title, description, email subject, email body) is HTML-escaped before storage
      •  
    ","tags":["guide","admin","influence","campaigns"]},{"location":"docs/admin/advocacy/campaigns/#campaign-moderation","title":"Campaign Moderation","text":"
    Admins review user-submitted campaigns before they go live.
     
       
    • Moderation queue \u2014 accessible at /app/campaign-moderation, showing all user-generated campaigns filtered by moderation status (pending, approved, rejected, changes requested)
      •  
    • Moderation actions \u2014 for each campaign in the queue, admins can:
         
      • Approve \u2014 sets the moderation status to APPROVED and the campaign status to ACTIVE, making it publicly visible
        •  
      • Reject \u2014 marks the campaign as REJECTED with an optional reason visible to the submitter
        •  
      • Request changes \u2014 sets the status to CHANGES_REQUESTED with feedback, allowing the user to revise and resubmit
        •  
       
      •  
    • Moderation stats \u2014 the queue page displays counters for total user-generated campaigns, pending reviews, approved, rejected, and changes-requested counts
      •  
    • Reviewer tracking \u2014 each moderation action records the reviewer's user ID and timestamp
      •  
    • Search and filter \u2014 the moderation queue supports searching by campaign title, submitter name, or email, and filtering by moderation status
      •  
    ","tags":["guide","admin","influence","campaigns"]},{"location":"docs/admin/advocacy/campaigns/#campaign-analytics","title":"Campaign Analytics","text":"
    The Campaign Effectiveness dashboard provides cross-campaign performance analytics at /app/influence/effectiveness.
     
       
    • Performance tab \u2014 per-campaign KPIs including total emails sent, email delivery status breakdown, response counts, response rates, and call counts; top campaigns visualized as a horizontal bar chart
      •  
    • Representatives tab \u2014 tracks individual representative responsiveness across all campaigns; shows emails received, responses given, verified response count, and response rate per representative; sortable by response count, response rate, or name; includes government level distribution
      •  
    • Geography tab \u2014 engagement breakdown by geographic area; group results by postal code, city, or province; enriched with city/province data from the postal code cache
      •  
    • Funnel tab \u2014 conversion funnel visualization showing progression from emails sent to unique participants to responses received to verified responses, plus calls made; includes percentage-of-first and stage-to-stage dropoff rates
      •  
    • Trends tab \u2014 time-series activity chart showing daily or weekly email and response volumes; default view covers the last 30 days; merged email and response series for side-by-side comparison
      •  
    • Global filters \u2014 all tabs share campaign and date range filters; select a specific campaign or view aggregate data across all campaigns
      •  
    ","tags":["guide","admin","influence","campaigns"]},{"location":"docs/admin/advocacy/campaigns/#admin-routes","title":"Admin Routes","text":"
       
    • /app/campaigns \u2014 create, edit, and manage campaigns
      •  
    • /app/campaign-moderation \u2014 review and moderate user-submitted campaigns
      •  
    • /app/influence/effectiveness \u2014 campaign effectiveness analytics dashboard
      •  
    • /app/responses \u2014 moderate submitted responses
      •  
    • /app/email-queue \u2014 monitor outgoing email delivery
      •  
    ","tags":["guide","admin","influence","campaigns"]},{"location":"docs/admin/advocacy/campaigns/#public-routes","title":"Public Routes","text":"
       
    • /campaigns \u2014 browse active campaigns
      •  
    • /campaigns/create \u2014 submit a new user-generated campaign (requires login)
      •  
    • /campaigns/mine \u2014 view and manage your submitted campaigns (requires login)
      •  
    • /campaign/:slug \u2014 take action on a specific campaign
      •  
    • /campaign/:slug/responses \u2014 view the response wall
      •  
    ","tags":["guide","admin","influence","campaigns"]},{"location":"docs/admin/advocacy/email-queue/","title":"Email Queue","text":"
    Monitor outgoing advocacy emails processed through the BullMQ queue.
     
    ","tags":["guide","admin","influence","email"]},{"location":"docs/admin/advocacy/email-queue/#key-features","title":"Key Features","text":"
       
    • Queue dashboard \u2014 view pending, active, completed, and failed jobs at /app/email-queue
      •  
    • Job details \u2014 inspect individual email jobs with recipient, subject, status, and timestamps
      •  
    • Retry failed jobs \u2014 re-queue emails that failed due to SMTP errors or timeouts
      •  
    • Clear completed \u2014 bulk-remove completed jobs to keep the queue clean
      •  
    • Stats \u2014 total sent, delivery rate, and average processing time
      •  
    ","tags":["guide","admin","influence","email"]},{"location":"docs/admin/advocacy/email-queue/#admin-routes","title":"Admin Routes","text":"
       
    • /app/email-queue \u2014 email queue monitoring and management
      •  
    ","tags":["guide","admin","influence","email"]},{"location":"docs/admin/advocacy/representatives/","title":"Representatives","text":"
    The platform uses the Represent API to look up elected representatives by postal code across all government levels.
     
    ","tags":["guide","admin","influence"]},{"location":"docs/admin/advocacy/representatives/#how-it-works","title":"How It Works","text":"
       
    • Postal code lookup \u2014 enter a Canadian postal code to retrieve federal, provincial, municipal, and school board representatives
      •  
    • Redis cache \u2014 lookup results are cached to reduce API calls and improve response times
      •  
    • Cache management \u2014 view cache status and clear entries from /app/representatives
      •  
    • Government levels \u2014 campaigns can target specific levels (federal, provincial, municipal, school board)
      •  
    ","tags":["guide","admin","influence"]},{"location":"docs/admin/advocacy/representatives/#admin-routes","title":"Admin Routes","text":"
       
    • /app/representatives \u2014 representative cache management and lookup testing
      •  
    ","tags":["guide","admin","influence"]},{"location":"docs/admin/advocacy/responses/","title":"Response Moderation","text":"
    Review and moderate representative responses submitted by supporters on the public response wall.
     
    ","tags":["guide","admin","influence","moderation"]},{"location":"docs/admin/advocacy/responses/#key-features","title":"Key Features","text":"
       
    • Moderation queue \u2014 review submissions at /app/responses with filtering by campaign and status
      •  
    • Verification \u2014 mark responses as verified to display a trust badge on the public wall
      •  
    • Upvoting \u2014 supporters can upvote responses; counts are visible on the public wall
      •  
    • Approve / reject \u2014 control which responses appear publicly
      •  
    • Response stats \u2014 track response counts per campaign and per representative
      •  
    ","tags":["guide","admin","influence","moderation"]},{"location":"docs/admin/advocacy/responses/#admin-routes","title":"Admin Routes","text":"
       
    • /app/responses \u2014 response moderation dashboard
      •  
    ","tags":["guide","admin","influence","moderation"]},{"location":"docs/admin/broadcast/","title":"Broadcast","text":"
    Reach supporters through multiple channels \u2014 email newsletters, templated campaigns, and SMS text messages.
    ","tags":["guide","admin","broadcast"]},{"location":"docs/admin/broadcast/#in-this-section","title":"In This Section","text":"
       
    • Newsletter \u2014 Listmonk integration with automatic subscriber sync from shifts, campaigns, and contacts
      •  
    • Email Templates \u2014 reusable templates with variable substitution, version history, and test sending
      •  
    • SMS \u2014 text message campaigns via a Termux Android bridge with contact lists and response tracking
      •  
    ","tags":["guide","admin","broadcast"]},{"location":"docs/admin/broadcast/email-templates/","title":"Email Templates","text":"
    Create reusable email templates with variable substitution for campaign communications. Templates are used by advocacy campaigns, shift confirmations, volunteer re-engagement emails, and other automated communications.
     
    ","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/email-templates/#template-categories","title":"Template Categories","text":"
    Each template belongs to a category that determines where it can be used:
     
       
    • INFLUENCE -- advocacy campaign emails sent to representatives
      •  
    • MAP -- shift confirmation, volunteer thank-you, and canvassing-related emails
      •  
    • SYSTEM -- account verification, password reset, and platform notifications
      •  
    • PAYMENT -- donation receipts, subscription confirmations, and purchase orders
      •  
    ","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/email-templates/#variable-system","title":"Variable System","text":"
    Templates use Handlebars-style {{VARIABLE_NAME}} placeholders that are replaced at send time. Variables must use uppercase letters and underscores (e.g., {{RECIPIENT_NAME}}, {{CAMPAIGN_TITLE}}).
     
       
    • Text variables -- simple string substitution for names, dates, URLs, and other text
      •  
    • Video variables -- embed a media library video by referencing its ID
      •  
    • Conditional blocks -- show or hide content with {{#if VARIABLE}}...{{/if}} syntax
      •  
    • Required vs optional -- each variable can be marked as required, with sample values for test emails
      •  
     
    The template validator automatically extracts all variables from the HTML, text, and subject line content and checks for unmatched conditional blocks.
    ","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/email-templates/#version-history","title":"Version History","text":"
    Every change to a template's subject line, HTML content, or text content creates a new version. The full version history is preserved, and any previous version can be restored:
     
       
    • Version browsing -- view the subject, HTML, and text content of any past version
      •  
    • Rollback -- restore a previous version (creates a new version entry, preserving the audit trail)
      •  
    • Change notes -- each version includes a description of what changed
      •  
    • Author tracking -- versions record which admin made each change
      •  
    ","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/email-templates/#test-emails","title":"Test Emails","text":"
    Before activating a template, send a test email to verify rendering:
     
       
    • Variable substitution -- provide test data for each variable to preview the final output
      •  
    • Recipient selection -- send the test to any email address
      •  
    • Test log -- all test sends are logged with success/failure status and message IDs
      •  
    • Rate limited -- 10 test emails per 15 minutes per user to prevent abuse
      •  
    ","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/email-templates/#template-caching","title":"Template Caching","text":"
    Rendered templates are cached in memory for performance. The cache is automatically cleared when a template is created, updated, or deleted. Admins can also manually clear the cache from the admin interface.
    ","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/email-templates/#admin-routes","title":"Admin Routes","text":"
       
    • /app/email-templates -- create and manage email templates with a visual editor
      •  
    ","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/newsletter/","title":"Newsletter (Listmonk)","text":"
    Integrated with Listmonk for opt-in mailing lists and newsletter campaigns. Enable with LISTMONK_SYNC_ENABLED=true.
     
    ","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/newsletter/#managed-lists","title":"Managed Lists","text":"
    The platform automatically creates and maintains 13 subscriber lists in Listmonk:
     List Name Source Tags All Contacts All synced records v2 Campaign Participants Users who sent advocacy emails v2, influence Locations - All Address occupants with email v2, map Support Level 1-4 Addresses by canvass support level v2, map, support Has Campaign Sign Addresses with a yard sign v2, map, signs Users Active non-temp platform accounts v2, users Volunteers Shift signups v2, map, shifts Canvassers Users who completed canvass sessions v2, map, canvass Subscribers Active paid subscribers v2, payments Donors Users who completed a donation v2, payments","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/newsletter/#bulk-sync","title":"Bulk Sync","text":"
    The admin panel provides a manual \"Sync All\" action that synchronizes four data sources to Listmonk:
     
       
    1. Campaign participants -- distinct email senders from advocacy campaigns
      2.  
    2. Location contacts -- address occupants with email, mapped to support level and sign lists
      3.  
    3. Users -- active platform accounts (excludes TEMP users)
      4.  
    4. CRM tags -- contacts tagged in the People module, synced to tag-linked Listmonk lists
      5.  
     
    Each source upserts subscribers (creates new or merges into existing), preserving existing list memberships and merging metadata attributes.
    ","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/newsletter/#event-driven-sync","title":"Event-Driven Sync","text":"
    In addition to bulk sync, the platform fires real-time subscriber upserts on application events:
     
       
    • Shift signup -- adds to Volunteers list
      •  
    • Canvass session completed -- adds to Canvassers list
      •  
    • Campaign email sent -- adds to Campaign Participants list
      •  
    • Subscription activated -- adds to Subscribers list
      •  
    • Donation completed -- adds to Donors list
      •  
    • Product purchased -- adds to Donors list
      •  
    • Address updated (canvass visit) -- updates support level list membership
      •  
    • Re-engagement email sent -- updates Volunteers list metadata
      •  
    • CRM tag changed -- adds/removes from tag-linked Listmonk lists
      •  
     
    All event-driven syncs are fire-and-forget and silently fail if Listmonk is unreachable.
    ","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/newsletter/#admin-routes","title":"Admin Routes","text":"
       
    • /app/listmonk (sidebar: \"Newsletter\") -- sync status, subscriber counts, campaign stats, and manual sync trigger
      •  
    ","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/sms/","title":"SMS Campaigns","text":"
    Text message outreach via a Termux Android bridge. Uses a real Android phone to send and receive SMS \u2014 no third-party SMS gateway or Twilio account needed.
     
     
    Enable with ENABLE_SMS=true or via the setup wizard.
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#architecture-overview","title":"Architecture Overview","text":"
    The SMS system uses a three-tier architecture where your server communicates with a lightweight Python Flask API running on an Android phone:
     
    graph LR\n    A[Admin Dashboard<br/>Campaign UI] -->|API calls| B[Express API<br/>BullMQ Queue]\n    B -->|HTTP + API Key| C[Android Phone<br/>Flask on Termux]\n    C -->|termux-sms-send| D[Android SMS]\n    D -->|Carrier Network| E[Recipients]\n    E -->|Reply SMS| D\n    D -->|termux-sms-list| C\n    C -->|HTTP response| B
     
    Why this approach?
     
       
    • No SaaS dependency \u2014 your phone is the SMS gateway, no Twilio/MessageBird/etc.
      •  
    • Real phone number \u2014 recipients see a real number, not a short code
      •  
    • Two-way messaging \u2014 incoming replies sync automatically
      •  
    • Low cost \u2014 just your phone plan's SMS allowance
      •  
    • Full control \u2014 FOSS stack end-to-end
      •  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#prerequisites","title":"Prerequisites","text":"
    Before starting setup, you'll need:
     Item Details Android phone Any Android 7+ device with an active SIM card and SMS plan Termux Terminal emulator \u2014 install from F-Droid (not Play Store) Termux:API Termux plugin for SMS/contacts/battery \u2014 install from F-Droid Tailscale (recommended) VPN mesh for stable IP \u2014 install from Play Store Network access Phone must be reachable from the server (Tailscale, LAN, or port forwarding) 
    Both Apps MUST Come from F-Droid
     
    The Play Store version of Termux is abandoned and incompatible with the API plugin. If you install Termux from the Play Store and Termux:API from F-Droid (or vice versa), SMS commands will fail with:
     
    Termux:API is not yet available on Google Play
     
    Fix: Uninstall both apps, then reinstall both from F-Droid. They must come from the same source because Android verifies matching app signatures for inter-process communication.
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#phone-setup","title":"Phone Setup","text":"","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#step-1-install-apps-from-f-droid","title":"Step 1: Install Apps from F-Droid","text":"
    On your Android phone:
     
       
    1. Install F-Droid \u2014 download from f-droid.org if you don't have it
      2.  
    2. Install Termux \u2014 search in F-Droid and install
      3.  
    3. Install Termux:API \u2014 search in F-Droid and install
      4.  
    4. Install Termux:Boot (optional) \u2014 for auto-start on phone reboot. Open once after install to register.
      5.  
    5. Install Tailscale (recommended) \u2014 from Play Store, connect to your tailnet for a stable IP
      6.  
     
    termux-api package
     
    You need two things called \"termux-api\": the F-Droid app (Termux:API) and the Termux package (pkg install termux-api). The setup script installs the package automatically, but the F-Droid app must be installed manually.
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#step-2-generate-api-key","title":"Step 2: Generate API Key","text":"
    Go to the admin dashboard SMS Setup page (/app/sms/setup) and click Generate API Key. Copy the key \u2014 you'll paste it into the setup command.
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#step-3-run-the-setup-script","title":"Step 3: Run the Setup Script","text":"
    Open Termux on the phone and run:
     
    # Clone the SMS server (first time only)\npkg install -y git && git clone https://gitea.bnkops.com/admin/campaign_connector.git ~/sms-server\n\n# Run the setup script \u2014 paste your API key at the end\nbash ~/sms-server/android/setup.sh YOUR_API_KEY_HERE\n
     
    The setup script automatically:
     
       
    • Installs Python, Flask, termux-api, and openssh
      •  
    • Saves the API key to ~/.bashrc
      •  
    • Requests SMS and Contacts permissions (tap Allow when prompted)
      •  
    • Creates a Termux:Boot auto-start script (if Termux:Boot is installed)
      •  
    • Starts the SMS server
      •  
     
    When done, note the Phone URL displayed (e.g. http://100.64.0.5:5001).
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#recommended-install-service-supervisor","title":"Recommended: Install Service Supervisor","text":"
    After initial setup, install termux-services for reliable process management. This uses runit, a proper UNIX service supervisor that automatically restarts the server if it crashes:
     
    cd ~/sms-server && bash android/setup-services.sh\n
     
    This registers two supervised services:
     
       
    • sms-api \u2014 Flask SMS API server (port 5001)
      •  
    • sshd-custom \u2014 SSH daemon for remote management (port 8022)
      •  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#step-4-prevent-android-from-killing-termux","title":"Step 4: Prevent Android from Killing Termux","text":"
    This is required for the server to run reliably in the background:
     
       
    1. Open Android Settings \u2192 Apps \u2192 Termux \u2192 Battery \u2192 set to Unrestricted
      2.  
    2. Lock Termux in the recent apps view (long-press the app card \u2192 Lock/Pin)
      3.  
    3. Samsung phones: also add Termux to Settings \u2192 Device Care \u2192 Battery \u2192 Never Sleeping Apps
      4.  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#updating","title":"Updating","text":"
    To pull the latest server code and re-run setup:
     
    cd ~/sms-server && git pull && bash android/setup.sh YOUR_API_KEY_HERE\n
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#service-management","title":"Service Management","text":"
    If you installed termux-services (recommended):
     
    # Check status\nsv status sms-api\n\n# Restart\nsv restart sms-api\n\n# Stop\nsv down sms-api\n\n# Start\nsv up sms-api\n\n# View logs\ntail -f ~/logs/sms-api.log\n\n# Health check\ncurl http://127.0.0.1:5001/health\n
     
    Without termux-services (legacy watchdog):
     
    # Check if the server is running\ncurl http://127.0.0.1:5001/health\n\n# Restart manually\ncd ~/sms-server/android && bash sms-watchdog.sh\n
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#accessing-the-phone","title":"Accessing the Phone","text":"
    There are several ways to run commands on the phone:
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#direct-on-phone","title":"Direct (on phone)","text":"
    Simply open the Termux app and type commands. Best for initial setup.
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#ssh-remote-access","title":"SSH (remote access)","text":"
    Start the SSH server in Termux, then connect from your computer:
     
    # On the phone (first time only):\npkg install openssh\npasswd  # Set a password\nsshd    # Start SSH server on port 8022\n\n# From your computer:\nssh -p 8022 your-phone-ip\n# Or with Tailscale:\nssh -p 8022 100.x.x.x\n
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#scrcpy-screen-mirror","title":"scrcpy (screen mirror)","text":"
    Mirror the phone screen to your computer \u2014 great for setup:
     
    # Install scrcpy on your computer (Ubuntu)\nsudo apt install scrcpy\n\n# Connect via USB\nscrcpy\n\n# Or wireless (phone must be on same network)\nscrcpy --tcpip=phone-ip:5555\n
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#setup-wizard","title":"Setup Wizard","text":"
    The admin panel provides a guided three-step wizard at /app/sms/setup:
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#step-1-prepare-phone","title":"Step 1: Prepare Phone","text":"
    Walks you through installing apps, cloning the server, setting the API key, and starting the Flask server. Generates a shared API key that both the server and phone use for authentication.
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#step-2-connect","title":"Step 2: Connect","text":"
    Choose how to find your phone's IP address:
     Tailscale Auto-Discovery (Recommended)Manual URL Entry 
       
    1. Enter your Tailscale API key (tskey-api-...)
      2.  
    2. Click Discover Devices
      3.  
    3. The wizard queries the Tailscale API and lists all devices on your tailnet
      4.  
    4. Select your Android phone \u2014 the URL auto-fills with its stable 100.x.x.x IP
      5.  
     
    Getting a Tailscale API Key
     
    Go to Tailscale Admin Console \u2192 Settings \u2192 Keys \u2192 Generate auth key or API access token.
     
    Enter the phone's URL directly:
     
       
    • With Tailscale: http://100.x.x.x:5001 (stable IP, works across networks)
      •  
    • On same LAN: http://192.168.x.x:5001 (changes if phone reconnects)
      •  
    • Via port forward: http://your-public-ip:5001 (requires router config)
      •  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#step-3-test-save","title":"Step 3: Test & Save","text":"
       
    1. Click Test Connection \u2014 the wizard calls the phone's /health endpoint
      2.  
    2. On success, you'll see device uptime and message count
      3.  
    3. Click Save Configuration \u2014 stores the URL and key encrypted in the database
      4.  
    4. The enableSms feature flag is automatically enabled
      5.  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#how-it-works","title":"How It Works","text":"","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#sending-messages","title":"Sending Messages","text":"
       
    1. Admin creates an SMS campaign with a message template and contact list
      2.  
    2. Campaign is started \u2192 messages are queued in BullMQ (one at a time, serial delivery)
      3.  
    3. For each message, the Express API calls POST /api/sms/send on the phone
      4.  
    4. The Flask server on the phone executes termux-sms-send to send via Android's native SMS
      5.  
    5. A notification appears on the phone for each sent message
      6.  
    6. Results are tracked in the database (success/failure per recipient)
      7.  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#receiving-responses","title":"Receiving Responses","text":"
    A background service (sms-response-sync.service.ts) polls the phone's inbox at a configurable interval:
     
       
    1. Calls GET /api/sms/inbox?since=<last_sync_timestamp> on the phone
      2.  
    2. The Flask server runs termux-sms-list to get new messages
      3.  
    3. Incoming messages are matched to contacts and classified by keyword
      4.  
    4. Threaded conversations are maintained per contact
      5.  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#device-monitoring","title":"Device Monitoring","text":"
    A background service (sms-device-monitor.service.ts) checks phone health periodically:
     
       
    • Battery level, charging status, temperature
      •  
    • Server uptime and total messages sent
      •  
    • Connection status (available/unreachable)
      •  
    • Results displayed on the SMS Dashboard
      •  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#key-features","title":"Key Features","text":"
       
    • Contact lists \u2014 import, tag, and segment contacts for targeted outreach
      •  
    • Message templates \u2014 reusable templates with {name} variable placeholders
      •  
    • BullMQ queue \u2014 serial delivery with configurable delays between messages
      •  
    • Response sync \u2014 incoming SMS replies synced and classified automatically
      •  
    • Device monitoring \u2014 battery, uptime, and connectivity reported in real-time
      •  
    • Conversation view \u2014 threaded message history per contact
      •  
    • Retry logic \u2014 configurable retry attempts for failed deliveries
      •  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#admin-routes","title":"Admin Routes","text":"Route Description /app/sms/setup Guided setup wizard with Tailscale auto-discovery /app/sms SMS dashboard \u2014 campaign overview and device status /app/sms/contacts Manage contact lists and entries /app/sms/campaigns Create and monitor SMS campaigns /app/sms/conversations View threaded conversations with contacts","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#configuration","title":"Configuration","text":"","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#environment-variables","title":"Environment Variables","text":"Variable Default Description ENABLE_SMS false Feature flag (also set via setup wizard) TERMUX_API_URL \u2014 Phone URL, e.g. http://100.x.x.x:5001 TERMUX_API_KEY \u2014 Shared API key for authentication SMS_DELAY_BETWEEN_MS 1000 Delay between messages in a campaign (ms) SMS_MAX_RETRIES 3 Retry attempts for failed sends SMS_RESPONSE_SYNC_INTERVAL_MS 10000 How often to check for incoming replies (ms) SMS_DEVICE_MONITOR_INTERVAL_MS 30000 How often to check device health (ms) TAILSCALE_API_KEY \u2014 Tailscale API key for auto-discovery TAILSCALE_TAILNET \u2014 Tailscale tailnet name (optional) 
    Note
     
    When you use the setup wizard, configuration is stored in the database and takes priority over environment variables. You don't need to set env vars if you use the wizard.
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#phone-side-configuration","title":"Phone-Side Configuration","text":"
    On the phone, only one environment variable is needed:
     
    export SMS_API_SECRET='your-64-char-hex-key'\n
     
    The Flask server also accepts TERMUX_API_KEY as an alias for backwards compatibility.
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#phone-api-endpoints","title":"Phone API Endpoints","text":"
    The Flask server running on the phone exposes these endpoints on port 5001:
     Method Endpoint Auth Description GET /health No Server status, uptime, messages sent GET / No Web dashboard with endpoint documentation POST /api/sms/send Yes Send an SMS message POST /api/sms/send-reply Yes Send a reply with conversation tracking GET /api/sms/inbox No Get incoming messages (with since filter) GET /api/sms/list No List messages with pagination GET /api/sms/history No Get SMS history for a phone number GET /api/device/battery No Battery level, health, temperature GET /api/device/location No GPS coordinates (requires permission) GET /api/device/info No Device info + battery + uptime GET /api/contacts/list No Phone address book (with search) POST /api/campaign/notify No Push notification to device 
    Authentication uses the X-API-Key header with the shared secret.
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#troubleshooting","title":"Troubleshooting","text":"","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#phone-cant-be-reached","title":"Phone can't be reached","text":"
    Symptoms: Test connection fails, \"Connection refused\" or timeout.
     
    Checks:
     
       
    1. Is the Flask server running? Check Termux \u2014 you should see the startup banner
      2.  
    2. Is the IP correct? Run ifconfig in Termux to find the current IP
      3.  
    3. Are they on the same network? If not using Tailscale, both must be on the same LAN
      4.  
    4. Is Tailscale connected? Check the Tailscale app on the phone \u2014 it should show \"Connected\"
      5.  
    5. Firewall? Android rarely blocks incoming connections on Termux, but check if any firewall app is installed
      6.  
     
    # Quick test from your server\ncurl http://PHONE_IP:5001/health\n
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#authentication-required-errors","title":"\"Authentication required\" errors","text":"
    Symptoms: API calls return 401 with \"Authentication required\".
     
    Fix: The API key on the phone doesn't match the one in the admin panel.
     
    # On the phone, check the current key\necho $SMS_API_SECRET\n\n# If it doesn't match, update it\nexport SMS_API_SECRET='correct-key-from-admin-panel'\necho 'export SMS_API_SECRET=\"correct-key-from-admin-panel\"' >> ~/.bashrc\n\n# Restart the server\nsv restart sms-api\n# Or without termux-services: pkill -f termux-sms-api-server.py && cd ~/sms-server/android && python termux-sms-api-server.py\n
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#sms-not-sending","title":"SMS not sending","text":"
    Symptoms: Server responds successfully but messages don't arrive.
     
    Checks:
     
       
    1. SMS permissions granted? Go to Android Settings \u2192 Apps \u2192 Termux:API \u2192 Permissions \u2192 SMS
      2.  
    2. Active SIM card? The phone needs a working SIM with SMS capability
      3.  
    3. Message too long? Maximum 1600 characters per message
      4.  
    4. Rate limited? Minimum 1 second between messages (carrier may enforce longer delays)
      5.  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#termux-keeps-getting-killed","title":"Termux keeps getting killed","text":"
    Symptoms: Server stops after some time, especially when phone screen is off.
     
    Fix:
     
       
    1. Install termux-services (if not already): bash ~/sms-server/android/setup-services.sh \u2014 this uses runit, a proper service supervisor that auto-restarts the server immediately if it crashes
      2.  
    2. Disable battery optimization: Android Settings \u2192 Apps \u2192 Termux \u2192 Battery \u2192 Unrestricted
      3.  
    3. Lock Termux in recent apps \u2014 long-press the app card \u2192 Lock/Pin
      4.  
    4. Samsung: also add Termux, Termux:API, and Termux:Boot to Settings \u2192 Device Care \u2192 Battery \u2192 Never Sleeping Apps
      5.  
    5. Acquire wake lock: Run termux-wake-lock in Termux (included in boot script)
      6.  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#server-wont-start-missing-sms_api_secret","title":"Server won't start \u2014 \"Missing SMS_API_SECRET\"","text":"
    Symptoms: Server exits immediately with a security error.
     
    Fix: Set the API key environment variable:
     
    # Generate a new key if you don't have one\npython -c \"import secrets; print(secrets.token_hex(32))\"\n\n# Set it\nexport SMS_API_SECRET='your-generated-key'\necho 'export SMS_API_SECRET=\"your-key\"' >> ~/.bashrc\n
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#rcs-chat-features-interfering-with-replies","title":"RCS / Chat Features interfering with replies","text":"
    Symptoms: You send SMS messages successfully but some or all replies never appear in the system. Recipients say they replied, but the conversation shows no inbound messages.
     
    Cause: Google Messages enables RCS (Rich Communication Services) by default. When RCS is active, replies from recipients who also have RCS may be sent over data/Wi-Fi instead of the carrier SMS channel. The Termux server only reads the SMS inbox via termux-sms-list, so RCS messages are invisible to it.
     
    Fix: Disable RCS on the SMS phone:
     
       
    1. Open Google Messages on the phone
      2.  
    2. Tap the profile icon (top right) \u2192 Messages settings
      3.  
    3. Tap RCS chats (or \"Chat features\")
      4.  
    4. Turn off \"Turn on RCS chats\"
      5.  
     
    This must be done on the phone running the SMS server
     
    Disabling RCS on the server phone forces all outgoing messages to use plain SMS, and ensures replies also come back as SMS. You do not need recipients to change anything on their end \u2014 when the server phone sends a plain SMS, the reply will be plain SMS as well (unless the recipient's carrier forces RCS-only, which is rare).
     
    Additional checks:
     
       
    • Some carriers (e.g. Google Fi, Jio) enable RCS at the carrier level. If disabling in the app doesn't help, contact the carrier to disable RCS on the SIM.
      •  
    • If the phone has Samsung Messages instead of Google Messages, go to Samsung Messages \u2192 Settings \u2192 Chat settings \u2192 turn off.
      •  
    • After disabling RCS, restart the phone and verify by sending a test message \u2014 the send button should show an SMS label, not \"Chat\".
      •  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#updating-the-sms-server","title":"Updating the SMS server","text":"
    To pull the latest version of the server code:
     
    cd ~/sms-server\ngit pull\n\n# Restart the server\nsv restart sms-api\n# Or without termux-services: pkill -f termux-sms-api-server.py && cd android && python termux-sms-api-server.py\n
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/map/","title":"Map & Canvassing","text":"
    Manage locations, organize canvassing territories, schedule volunteer shifts, and coordinate door-to-door outreach.
    ","tags":["guide","admin","map"]},{"location":"docs/admin/map/#in-this-section","title":"In This Section","text":"
       
    • Locations \u2014 import addresses via CSV or NAR, geocode with multiple providers, and manage the location database
      •  
    • Areas \u2014 draw polygon territories on the map to organize canvassing regions
      •  
    • Shifts \u2014 schedule volunteer time slots with recurring patterns and calendar views
      •  
    • Canvassing \u2014 canvass dashboard, walk sheets, contact export, and session management
      •  
    • Data Quality \u2014 geocoding quality metrics, provider distribution, and confidence analysis
      •  
    • Map Settings \u2014 configure map center, zoom level, and QR code links
      •  
    ","tags":["guide","admin","map"]},{"location":"docs/admin/map/areas/","title":"Areas (Cuts)","text":"
    Draw polygon regions on the map to define canvassing territories. Areas organize locations into manageable chunks for volunteers.
     
    ","tags":["guide","admin","map","canvassing"]},{"location":"docs/admin/map/areas/#key-features","title":"Key Features","text":"
       
    • Polygon drawing \u2014 use the map editor at /app/map/cuts to draw, edit, and delete area boundaries
      •  
    • Automatic association \u2014 locations within an area's polygon boundary are automatically linked
      •  
    • Area stats \u2014 total addresses, visited count, coverage percentage per area
      •  
    • Color coding \u2014 assign colors to visually distinguish areas on the map
      •  
    ","tags":["guide","admin","map","canvassing"]},{"location":"docs/admin/map/areas/#area-import-wizard","title":"Area Import Wizard","text":"
    Bulk-import addresses into an area from multiple data sources:
     
       
    • OpenStreetMap (OSM) \u2014 pull building addresses from Nominatim within the area
      •  
    • NAR (National Address Register) \u2014 import from the Canadian federal address dataset
      •  
    • Reverse geocode grid \u2014 generate a grid of points and reverse-geocode to discover addresses
      •  
    • Deduplication \u2014 imported addresses are checked against existing locations to avoid duplicates
      •  
    • Progress tracking \u2014 real-time status per source during import
      •  
    ","tags":["guide","admin","map","canvassing"]},{"location":"docs/admin/map/areas/#admin-routes","title":"Admin Routes","text":"
       
    • /app/map/cuts \u2014 draw and manage canvassing areas
      •  
    • /app/map/cuts/:id/export \u2014 printable location report for a cut
      •  
    ","tags":["guide","admin","map","canvassing"]},{"location":"docs/admin/map/canvassing/","title":"Canvassing","text":"
    Coordinate and monitor volunteer door-to-door outreach with the canvass dashboard, walk sheets, and contact export tools.
     
    ","tags":["guide","admin","map","canvassing"]},{"location":"docs/admin/map/canvassing/#canvass-dashboard","title":"Canvass Dashboard","text":"
    From /app/map/canvass:
     
       
    • Active sessions \u2014 see which volunteers are currently canvassing and their real-time positions
      •  
    • Leaderboard \u2014 volunteer rankings by visit count
      •  
    • Activity feed \u2014 recent visit outcomes across all areas
      •  
    • Stats \u2014 total sessions, visits recorded, and outcome breakdowns
      •  
    ","tags":["guide","admin","map","canvassing"]},{"location":"docs/admin/map/canvassing/#walk-sheets-exports","title":"Walk Sheets & Exports","text":"
       
    • Walk sheet \u2014 printable form at /app/map/walk-sheet with space for recording visit outcomes; includes up to 3 configurable QR codes
      •  
    • Cut export \u2014 printable location report at /app/map/cuts/:id/export for a specific canvassing area
      •  
    ","tags":["guide","admin","map","canvassing"]},{"location":"docs/admin/map/canvassing/#canvass-contact-export","title":"Canvass Contact Export","text":"
    Bridge canvassing data with advocacy campaigns:
     
       
    • Filter by outcome \u2014 include specific visit outcomes (spoke with, left literature, come back later)
      •  
    • Support level range \u2014 filter by recorded support level
      •  
    • Area selection \u2014 limit export to specific areas
      •  
    • Campaign targeting \u2014 export contacts as recipients for an advocacy campaign
      •  
    ","tags":["guide","admin","map","canvassing"]},{"location":"docs/admin/map/canvassing/#admin-routes","title":"Admin Routes","text":"
       
    • /app/map/canvass \u2014 canvass dashboard
      •  
    • /app/map/walk-sheet \u2014 printable walk sheet
      •  
    ","tags":["guide","admin","map","canvassing"]},{"location":"docs/admin/map/data-quality/","title":"Data Quality","text":"
    Monitor geocoding accuracy and coverage from /app/map/data-quality.
     
    ","tags":["guide","admin","map","analytics"]},{"location":"docs/admin/map/data-quality/#key-metrics","title":"Key Metrics","text":"
       
    • Geocoding success rate \u2014 percentage of locations with valid coordinates
      •  
    • Provider distribution \u2014 breakdown of which geocoding provider was used per location
      •  
    • Confidence scores \u2014 distribution of geocoding confidence levels across the dataset
      •  
    • Missing data \u2014 locations without coordinates, postal codes, or province assignments
      •  
    • Bulk re-geocode \u2014 re-process failed or low-confidence locations with a different provider
      •  
    ","tags":["guide","admin","map","analytics"]},{"location":"docs/admin/map/data-quality/#admin-routes","title":"Admin Routes","text":"
       
    • /app/map/data-quality \u2014 geocoding quality dashboard
      •  
    ","tags":["guide","admin","map","analytics"]},{"location":"docs/admin/map/locations/","title":"Locations","text":"
    Import addresses via CSV or the Canadian National Address Register (NAR), geocode them with multiple providers, and manage the location database.
     
    ","tags":["guide","admin","map","locations"]},{"location":"docs/admin/map/locations/#adding-locations","title":"Adding Locations","text":"
       
    • Click-to-add \u2014 click on the admin map to drop a new location marker
      •  
    • Form entry \u2014 manually enter address details
      •  
    • CSV import \u2014 upload a CSV with address columns; the system geocodes each row
      •  
    • NAR import \u2014 import Canadian National Address Register data with province, city, postal code, and residential-only filters
      •  
    ","tags":["guide","admin","map","locations"]},{"location":"docs/admin/map/locations/#geocoding","title":"Geocoding","text":"
    Locations are geocoded automatically using a multi-provider system supporting Nominatim, ArcGIS, Photon, Mapbox, Google, and LocationIQ. Failed entries can be re-geocoded individually or in bulk.
    ","tags":["guide","admin","map","locations"]},{"location":"docs/admin/map/locations/#bulk-operations","title":"Bulk Operations","text":"
    Select multiple locations for:
     
       
    • Re-geocoding with a different provider
      •  
    • Tagging or re-tagging
      •  
    • Deletion
      •  
    • CSV export
      •  
    ","tags":["guide","admin","map","locations"]},{"location":"docs/admin/map/locations/#admin-routes","title":"Admin Routes","text":"
       
    • /app/map \u2014 location CRUD, CSV import/export, geocoding, area import wizard
      •  
    ","tags":["guide","admin","map","locations"]},{"location":"docs/admin/map/settings/","title":"Map Settings","text":"
    Configure the default map view and QR code links from /app/map/settings.
     
    ","tags":["guide","admin","map","configuration"]},{"location":"docs/admin/map/settings/#settings","title":"Settings","text":"
       
    • Map center \u2014 latitude and longitude for the default map center point
      •  
    • Default zoom \u2014 initial zoom level when maps load (1-18)
      •  
    • QR code links \u2014 up to 3 configurable URLs that appear as QR codes on printed walk sheets (e.g., campaign page, shift signup, volunteer portal)
      •  
    ","tags":["guide","admin","map","configuration"]},{"location":"docs/admin/map/settings/#admin-routes","title":"Admin Routes","text":"
       
    • /app/map/settings \u2014 map configuration
      •  
    ","tags":["guide","admin","map","configuration"]},{"location":"docs/admin/map/shifts/","title":"Shifts","text":"
    Schedule volunteer time slots and let people sign up through a public page. Shifts can be linked to specific areas so volunteers know where they'll be canvassing.
     
    ","tags":["guide","admin","map","shifts"]},{"location":"docs/admin/map/shifts/#creating-shifts","title":"Creating Shifts","text":"
       
    • Single shifts \u2014 set date, time, location description, and optional area assignment
      •  
    • Recurring shifts \u2014 create series with daily, weekly, or monthly frequency; weekly allows specific day selection
      •  
    • Calendar view \u2014 dedicated calendar tab showing shifts by date; click any date to create a new shift pre-filled
      •  
    ","tags":["guide","admin","map","shifts"]},{"location":"docs/admin/map/shifts/#series-management","title":"Series Management","text":"
       
    • Edit modes \u2014 when editing a recurring shift, choose: this shift only, this and future, or all in series
      •  
    • Date range \u2014 define start and optional end date; generates up to 12 weeks (capped at 100 shifts)
      •  
    • Detach \u2014 remove a shift from its series to edit independently
      •  
    ","tags":["guide","admin","map","shifts"]},{"location":"docs/admin/map/shifts/#signups","title":"Signups","text":"
       
    • Signup drawer \u2014 view all signups for a shift in the admin panel
      •  
    • Capacity \u2014 optionally set maximum volunteer count per shift
      •  
    • Confirmation emails \u2014 automatic email sent when a volunteer signs up or cancels
      •  
    ","tags":["guide","admin","map","shifts"]},{"location":"docs/admin/map/shifts/#admin-routes","title":"Admin Routes","text":"
       
    • /app/map/shifts \u2014 shift CRUD, calendar view, signup management
      •  
    ","tags":["guide","admin","map","shifts"]},{"location":"docs/admin/media/","title":"Media","text":"
    Upload, organize, and share campaign videos and photos with built-in analytics and engagement features. Enable with enableMediaFeatures in Settings.
    ","tags":["guide","admin","media"]},{"location":"docs/admin/media/#in-this-section","title":"In This Section","text":"
       
    • Library \u2014 upload videos and photos, manage metadata, schedule publishing, and generate preview links
      •  
    • Analytics \u2014 view counts, watch time, completion rates, traffic sources, and viewer activity
      •  
    • Curated Gallery \u2014 playlists, shorts feed, and featured content for the public gallery
      •  
    • Moderation \u2014 comment review, word filters, and content moderation tools
      •  
    • Gallery Ads \u2014 promotional cards with audience targeting, scheduling, and click-through analytics
      •  
    ","tags":["guide","admin","media"]},{"location":"docs/admin/media/ads/","title":"Gallery Ads","text":"
    Create promotional cards that appear in the public media gallery and documentation site. Manage from /app/media/ads.
    ","tags":["guide","admin","media"]},{"location":"docs/admin/media/ads/#key-features","title":"Key Features","text":"
       
    • Ad CRUD \u2014 create ads with title, description, image, and click-through URL
      •  
    • Placement targeting \u2014 assign ads to specific placements (gallery sidebar, gallery feed, docs sidebar)
      •  
    • Scheduling \u2014 set start and end dates for time-limited promotions
      •  
    • Click tracking \u2014 view impressions and click-through rates per ad
      •  
    • Priority ordering \u2014 control which ads appear first when multiple are active
      •  
    ","tags":["guide","admin","media"]},{"location":"docs/admin/media/ads/#admin-routes","title":"Admin Routes","text":"
       
    • /app/media/ads \u2014 gallery ad management and analytics
      •  
    ","tags":["guide","admin","media"]},{"location":"docs/admin/media/analytics/","title":"Analytics","text":"
    Track video engagement with GDPR-compliant analytics (IP hashing, 90-day retention).
     
    ","tags":["guide","admin","media","analytics"]},{"location":"docs/admin/media/analytics/#per-video-metrics","title":"Per-Video Metrics","text":"
    Each video tracks:
     
       
    • View count and unique viewers
      •  
    • Average watch time and completion rate
      •  
    • Traffic sources \u2014 direct, embedded, shared
      •  
    • Registered viewer activity (when logged in)
      •  
    ","tags":["guide","admin","media","analytics"]},{"location":"docs/admin/media/analytics/#global-dashboard","title":"Global Dashboard","text":"
    The analytics dashboard at /app/media/analytics provides:
     
       
    • Aggregate view counts across all videos
      •  
    • Top-performing content by views and completion rate
      •  
    • Viewer trends over time
      •  
    • Traffic source breakdown
      •  
    ","tags":["guide","admin","media","analytics"]},{"location":"docs/admin/media/analytics/#tracking","title":"Tracking","text":"
    Public endpoints record engagement:
     
       
    • View initiation
      •  
    • 10-second heartbeat intervals
      •  
    • navigator.sendBeacon for reliable end-of-session reporting
      •  
    ","tags":["guide","admin","media","analytics"]},{"location":"docs/admin/media/analytics/#admin-routes","title":"Admin Routes","text":"
       
    • /app/media/analytics \u2014 global analytics dashboard
      •  
    ","tags":["guide","admin","media","analytics"]},{"location":"docs/admin/media/curated/","title":"Curated Gallery","text":"
    Curate the public gallery experience with playlists, a shorts feed, and featured content.
     
    ","tags":["guide","admin","media","gallery"]},{"location":"docs/admin/media/curated/#playlists","title":"Playlists","text":"
    From /app/media/curated:
     
       
    • Three types \u2014 admin playlists (managed), user playlists (personal), and public playlists (community)
      •  
    • Drag-reorder \u2014 arrange videos within a playlist
      •  
    • Featured carousel \u2014 feature playlists on the gallery homepage
      •  
    • Dedicated viewer \u2014 full playlist playback page with up-next queue
      •  
    ","tags":["guide","admin","media","gallery"]},{"location":"docs/admin/media/curated/#shorts-feed","title":"Shorts Feed","text":"
    TikTok-style vertical video feed for clips under 60 seconds:
     
       
    • Automatic classification \u2014 videos under 60 seconds are flagged as shorts
      •  
    • Vertical feed \u2014 mobile-optimized swipeable interface at /gallery/shorts
      •  
    • Autoplay \u2014 continuous playback as viewers scroll
      •  
    ","tags":["guide","admin","media","gallery"]},{"location":"docs/admin/media/curated/#admin-routes","title":"Admin Routes","text":"
       
    • /app/media/curated \u2014 playlist management
      •  
    ","tags":["guide","admin","media","gallery"]},{"location":"docs/admin/media/library/","title":"Library","text":"
    The media library at /app/media/library is where you upload, organize, and publish video and photo content.
     
    ","tags":["guide","admin","media","videos"]},{"location":"docs/admin/media/library/#video-upload","title":"Video Upload","text":"
       
    • Drag-and-drop \u2014 single or batch upload (up to 10GB per file)
      •  
    • Supported formats \u2014 MP4, MOV, AVI, MKV, WebM, M4V, FLV
      •  
    • Automatic metadata \u2014 FFprobe extracts duration, dimensions, orientation, quality, and audio info
      •  
    • Quick actions \u2014 hover a video card for Edit (E), Preview (P), Analytics (A), Schedule (S) keyboard shortcuts
      •  
    ","tags":["guide","admin","media","videos"]},{"location":"docs/admin/media/library/#photo-management","title":"Photo Management","text":"
       
    • Albums \u2014 organize photos into named collections with cover images
      •  
    • Bulk uploads \u2014 drag-and-drop multiple photos with automatic metadata extraction
      •  
    • Photo picker \u2014 insert photos into landing pages and email templates via a modal picker
      •  
    ","tags":["guide","admin","media","videos"]},{"location":"docs/admin/media/library/#scheduled-publishing","title":"Scheduled Publishing","text":"
       
    • Publish/unpublish dates \u2014 set future dates for automatic state changes
      •  
    • Timezone support \u2014 11 supported timezones
      •  
    • Calendar view \u2014 visualize scheduled items on the Calendar tab
      •  
    • BullMQ automation \u2014 jobs fire at scheduled times
      •  
    ","tags":["guide","admin","media","videos"]},{"location":"docs/admin/media/library/#preview-links","title":"Preview Links","text":"
    Generate 24-hour JWT-authenticated preview links for unpublished videos \u2014 useful for stakeholder review before publishing.
    ","tags":["guide","admin","media","videos"]},{"location":"docs/admin/media/library/#admin-routes","title":"Admin Routes","text":"
       
    • /app/media/library \u2014 video and photo management
      •  
    • /app/media/jobs \u2014 processing job queue monitoring
      •  
    ","tags":["guide","admin","media","videos"]},{"location":"docs/admin/media/moderation/","title":"Moderation","text":"
    Admin tools for reviewing and managing comments across all media content at /app/media/moderation.
    ","tags":["guide","admin","media","moderation"]},{"location":"docs/admin/media/moderation/#moderation-dashboard","title":"Moderation Dashboard","text":"
       
    • Filter by status \u2014 pending, safe, flagged, hidden
      •  
    • Status counts \u2014 summary stats showing total, pending, flagged, hidden, and safe comments
      •  
    • Search \u2014 filter by video, date range, or text content
      •  
    ","tags":["guide","admin","media","moderation"]},{"location":"docs/admin/media/moderation/#moderation-actions","title":"Moderation Actions","text":"
    For each comment, admins can:
     
       
    • Approve \u2014 mark as safe and unhide if previously hidden
      •  
    • Hide \u2014 remove from public view with a reason (manual, word filter, spam, or link)
      •  
    • Unhide \u2014 restore a previously hidden comment
      •  
    • Delete \u2014 permanently remove
      •  
    • Add notes \u2014 internal moderation notes (not visible to users)
      •  
    ","tags":["guide","admin","media","moderation"]},{"location":"docs/admin/media/moderation/#word-filter","title":"Word Filter","text":"
    A configurable list of words with severity levels:
     Severity Action High Auto-blocks the comment Medium Auto-hides for review Low Flags for moderator attention Custom User-defined severity 
    The filter list is cached with a 1-minute TTL and invalidated on changes.
    ","tags":["guide","admin","media","moderation"]},{"location":"docs/admin/media/moderation/#admin-routes","title":"Admin Routes","text":"
       
    • /app/media/moderation \u2014 comment moderation and word filter management
      •  
    ","tags":["guide","admin","media","moderation"]},{"location":"docs/admin/payments/","title":"Payments","text":"
    Accept memberships, product sales, and donations through Stripe. Enable with enablePayments in Settings.
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/#in-this-section","title":"In This Section","text":"
       
    • Products \u2014 manage merchandise and one-time purchase items with inventory tracking
      •  
    • Donations \u2014 donation pages with goals, suggested amounts, and branded thank-you messages
      •  
    • Plans \u2014 recurring subscription plans with monthly and yearly billing
      •  
    • Settings \u2014 Stripe API key configuration with encrypted storage
      •  
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/#how-it-works","title":"How It Works","text":"
       
    1. Enable payments in Settings or .env (ENABLE_PAYMENTS=true)
      2.  
    2. Configure Stripe API keys in Settings > Payments (stored encrypted with ENCRYPTION_KEY)
      3.  
    3. Payment widgets become available on landing pages and MkDocs pages
      4.  
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/donations/","title":"Donations","text":"
    Create custom branded donation landing pages with independent branding and goals.
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/donations/#donation-pages","title":"Donation Pages","text":"
    From /app/donation-pages:
     
       
    • Custom branding \u2014 each page has its own title, description, and cover image
      •  
    • Configurable amounts \u2014 set suggested donation amounts per page
      •  
    • Thank-you messages \u2014 customizable post-donation confirmation
      •  
    • Public slugs \u2014 shareable URL at /donate/:slug
      •  
    • Goal tracking \u2014 fundraising goals with progress indicators
      •  
    • Multiple campaigns \u2014 run several pages simultaneously with independent tracking
      •  
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/donations/#donation-management","title":"Donation Management","text":"
    From /app/donations:
     
       
    • View all donations with date, amount, donor info, and status
      •  
    • Filter by donation page, date range, or amount
      •  
    • Export to CSV for accounting and tax receipts
      •  
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/donations/#admin-routes","title":"Admin Routes","text":"
       
    • /app/donations \u2014 donation management
      •  
    • /app/donation-pages \u2014 donation page CRUD
      •  
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/plans/","title":"Plans","text":"
    Create and manage recurring subscription plans for campaign supporters at /app/plans.
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/plans/#key-features","title":"Key Features","text":"
       
    • Tiered plans \u2014 multiple subscription tiers with different pricing and benefits
      •  
    • Billing cycles \u2014 monthly and yearly billing options
      •  
    • Stripe integration \u2014 subscriptions managed through Stripe for reliable recurring payments
      •  
    • Subscriber tracking \u2014 view active subscribers, MRR, and churn metrics
      •  
    • Public pricing page \u2014 plans displayed at /pricing
      •  
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/plans/#admin-routes","title":"Admin Routes","text":"
       
    • /app/plans \u2014 subscription plan management
      •  
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/products/","title":"Products","text":"
    Manage campaign merchandise and one-time purchase items at /app/products.
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/products/#key-features","title":"Key Features","text":"
       
    • Product CRUD \u2014 create products with title, description, price, and images
      •  
    • Inventory management \u2014 track stock levels and set low-stock alerts
      •  
    • Stripe checkout \u2014 seamless payment flow via Stripe
      •  
    • Public shop \u2014 products displayed at /shop for public browsing and purchase
      •  
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/products/#admin-routes","title":"Admin Routes","text":"
       
    • /app/products \u2014 product management
      •  
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/settings/","title":"Payment Settings","text":"
    Configure Stripe integration from Settings > Payments.
    ","tags":["guide","admin","payments","configuration"]},{"location":"docs/admin/payments/settings/#stripe-configuration","title":"Stripe Configuration","text":"
       
    • Publishable key \u2014 used by the frontend for Stripe Elements and Checkout
      •  
    • Secret key \u2014 used by the API for creating charges and managing subscriptions
      •  
    • Encrypted storage \u2014 both keys are stored encrypted in the database using the ENCRYPTION_KEY environment variable (AES encryption)
      •  
    ","tags":["guide","admin","payments","configuration"]},{"location":"docs/admin/payments/settings/#webhook","title":"Webhook","text":"
    Stripe webhooks are automatically configured to handle:
     
       
    • Successful payments and subscription renewals
      •  
    • Failed payments and subscription cancellations
      •  
    • Refunds and disputes
      •  
    ","tags":["guide","admin","payments","configuration"]},{"location":"docs/admin/payments/settings/#admin-routes","title":"Admin Routes","text":"
       
    • /app/settings (Payments tab) \u2014 Stripe key configuration
      •  
    ","tags":["guide","admin","payments","configuration"]},{"location":"docs/admin/services/","title":"Services","text":"
    Manage the platform's infrastructure services, monitoring stack, and third-party integrations.
    ","tags":["guide","admin","services"]},{"location":"docs/admin/services/#in-this-section","title":"In This Section","text":"
       
    • Tunnel \u2014 Pangolin tunnel management for public access without port forwarding
      •  
    • CrowdSec & Security \u2014 CrowdSec Manager, Tinyauth forward-auth, ISP whitelisting, and Turnstile captcha on the Pangolin server
      •  
    • Monitoring \u2014 Prometheus metrics, Grafana dashboards, and Alertmanager
      •  
    • Integrations \u2014 Chat, video conferencing, password manager, whiteboard, Git hosting, automation, and QR codes
      •  
    • User Provisioning \u2014 automatic account sync across integrated services
      •  
    ","tags":["guide","admin","services"]},{"location":"docs/admin/services/crowdsec/","title":"CrowdSec Manager & Security Configuration","text":"
    This page covers the CrowdSec Manager web UI on the Pangolin server, protected behind Tinyauth authentication, along with tuning of CrowdSec security rules and enabling Cloudflare Turnstile captcha for the CrowdSec bouncer.
    ","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#architecture","title":"Architecture","text":"
    graph LR\n    User -->|HTTPS| Traefik\n    Traefik -->|forwardAuth| Tinyauth\n    Tinyauth -->|authenticated| Traefik\n    Traefik -->|proxy| CrowdSec-Manager\n    CrowdSec-Manager -->|API| CrowdSec\n    Traefik -->|bouncer plugin| CrowdSec\n    CrowdSec -->|captcha decision| Turnstile[Cloudflare Turnstile]
     
    All services run on the same Docker Compose stack and share the pangolin network. Traefik reaches them through Gerbil's network namespace.
    ","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#components-added","title":"Components Added","text":"","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#crowdsec-manager","title":"CrowdSec Manager","text":"
    Image: hhftechnology/crowdsec-manager:1.1.0
     
    A web UI for managing CrowdSec operations \u2014 viewing alerts, decisions, managing bouncers, and configuring scenarios. It has read-only access to Traefik and CrowdSec configs and read-write access to its own data and backups.
     
    Accessible at: https://crowdsec.bnkserve.org
    ","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#tinyauth","title":"Tinyauth","text":"
    Image: ghcr.io/steveiliop56/tinyauth:v4
     
    A lightweight forward-auth middleware that protects the CrowdSec Manager dashboard with a login screen. Traefik's forwardAuth middleware checks every request to the manager against Tinyauth before allowing access.
     
    Login page at: https://auth.bnkserve.org
     
    User credentials are stored in a users file (/data/users) mounted from the host, using bcrypt-hashed passwords.
     
    Special Characters in Passwords
     
    Tinyauth v4 has a known issue where special characters (@, !, etc.) in passwords can cause login failures through the browser, even though the bcrypt hash verifies correctly via the CLI. Use alphanumeric passwords to avoid this.
    ","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#traefik-routing","title":"Traefik Routing","text":"","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#routers","title":"Routers","text":"Router Domain Middleware Purpose crowdsec-manager-router crowdsec.bnkserve.org security-headers, tinyauth Dashboard (HTTPS) crowdsec-manager-redirect crowdsec.bnkserve.org redirect-to-https HTTP \u2192 HTTPS redirect tinyauth-router auth.bnkserve.org security-headers Auth login page (HTTPS) tinyauth-redirect auth.bnkserve.org redirect-to-https HTTP \u2192 HTTPS redirect 
    No tinyauth middleware on the tinyauth router
     
    The tinyauth-router must not have the tinyauth forwardAuth middleware applied \u2014 this would create an infinite redirect loop.
    ","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#middleware","title":"Middleware","text":"
    The tinyauth forwardAuth middleware forwards every request to http://tinyauth:3000/api/auth/traefik. If the user has a valid session cookie (scoped to .bnkserve.org), the request passes through. Otherwise, the user is redirected to the Tinyauth login page.
     
    tinyauth:\n  forwardAuth:\n    address: http://tinyauth:3000/api/auth/traefik\n    trustForwardHeader: true\n    authResponseHeaders:\n      - X-Forwarded-User\n
    ","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#crowdsec-tuning","title":"CrowdSec Tuning","text":"","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#relaxed-crawl-detection","title":"Relaxed Crawl Detection","text":"
    The crowdsecurity/http-crawl-non_statics scenario was triggering on legitimate Canadian users browsing the site. The local override at /etc/crowdsec/scenarios/http-crawl-non_statics.yaml (replacing the hub symlink) has relaxed thresholds:
     Parameter Before After Effect capacity 40 80 Twice as many distinct pages before triggering leakspeed 0.5s 0.25s Bucket drains twice as fast 
    Combined effect: 4x more lenient \u2014 a user must hit 80+ distinct non-static pages faster than 1 every 0.25 seconds to trigger a captcha.
    ","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#canadian-isp-whitelist","title":"Canadian ISP Whitelist","text":"
    A whitelist expression in /etc/crowdsec/parsers/s02-enrich/mywhitelists.yaml exempts traffic from major Canadian ISPs from all CrowdSec scenarios:
     
    expression:\n  - evt.Meta.ASNNumber in ['812', '852', '6327', '5645', '20365', '25668', '577']\n
     AS Number ISP 812 Rogers Communications 852 TELUS Communications 6327 Shaw Communications 5645 TekSavvy 20365 Freedom Mobile 25668 CipherKey 577 Bell Canada 
    Field name
     
    The GeoIP enricher populates evt.Meta.ASNNumber (not ASNumber). This can be verified by inspecting /etc/crowdsec/parsers/s02-enrich/geoip-enrich.yaml.
    ","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#cloudflare-turnstile-captcha","title":"Cloudflare Turnstile Captcha","text":"
    Previously, CrowdSec captcha decisions resulted in a hard 403 block because no captcha provider was configured. Now, users with a captcha decision see a Cloudflare Turnstile challenge page and can proceed after solving it.
     
    Configuration added to the CrowdSec bouncer plugin in dynamic_config.yml:
     
    captchaProvider: turnstile\ncaptchaSiteKey: <site-key>\ncaptchaSecretKey: <secret-key>\ncaptchaHTMLFilePath: /etc/traefik/captcha.html\n
     
    Captcha HTML template path
     
    The captcha.html template is copied from the plugin source to /etc/traefik/captcha.html (the mounted config volume). Do not reference the /plugins-storage/ path directly \u2014 the hash in that path changes on every Traefik restart.
    ","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#dns-records","title":"DNS Records","text":"
    Two A records pointing to 72.11.155.21:
     Record Purpose crowdsec.bnkserve.org CrowdSec Manager dashboard auth.bnkserve.org Tinyauth login page","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#verification","title":"Verification","text":"
    # Check containers are running and healthy\ndocker ps --filter name=crowdsec-manager --filter name=tinyauth\n\n# Check both are on the pangolin network\ndocker network inspect pangolin --format '{{range .Containers}}{{.Name}} {{end}}'\n\n# Verify no Canadian ISPs in active decisions\ndocker exec crowdsec cscli decisions list | grep \"CA\"\n\n# Check CrowdSec whitelist is loaded\ndocker exec crowdsec cscli parsers inspect mywhitelists\n\n# Check Traefik logs for captcha errors\ndocker logs traefik 2>&1 | grep -i captcha\n
    ","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/integrations/","title":"Integrations","text":"
    Changemaker Lite integrates with several self-hosted services. Each runs as a Docker container and can be enabled independently.
    ","tags":["guide","admin","services","integrations"]},{"location":"docs/admin/services/integrations/#team-chat-rocketchat","title":"Team Chat (Rocket.Chat)","text":"
    Self-hosted team chat for volunteer coordination. Enable with enableChat in Settings.
     
       
    • Channels & DMs \u2014 organize conversations by topic, team, or campaign
      •  
    • Iframe integration \u2014 embedded in the admin dashboard and volunteer portal
      •  
    • Floating widget \u2014 minimizable chat FAB on admin pages (toggleable in Settings)
      •  
    • SSO-ready \u2014 iframe authentication for seamless login
      •  
    • Mobile apps \u2014 native Rocket.Chat apps work with your instance
      •  
    • Routes: /app/services/rocketchat, /volunteer/chat
      •  
    ","tags":["guide","admin","services","integrations"]},{"location":"docs/admin/services/integrations/#video-conferencing-jitsi-meet","title":"Video Conferencing (Jitsi Meet)","text":"
    Self-hosted video calls integrated with Rocket.Chat via JWT authentication. Enable with enableMeet in Settings.
     
       
    • One-click calls \u2014 start a call from any Rocket.Chat channel or DM
      •  
    • JWT auth \u2014 participants join automatically with no separate login
      •  
    • 4 containers \u2014 jitsi-web, jitsi-prosody (XMPP/JWT), jitsi-jicofo (conference focus), jitsi-jvb (video bridge)
      •  
    • Setup: Generate secrets, start containers, configure the Jitsi marketplace app in Rocket.Chat, set token expiration to now + 1hour
      •  
     
    Token Expiration
     
    Set the Jitsi app's Token Expiration to now + 1hour. A raw number like 120 is interpreted as Unix timestamp 120 (Jan 1970), causing all tokens to appear expired.
    ","tags":["guide","admin","services","integrations"]},{"location":"docs/admin/services/integrations/#password-manager-vaultwarden","title":"Password Manager (Vaultwarden)","text":"
    Bitwarden-compatible password vault for secure team credential sharing.
     
       
    • Bitwarden client compatible \u2014 use official browser extensions, desktop apps, and mobile apps
      •  
    • Auto-invite \u2014 initial admin user invited on first startup
      •  
    • User provisioning \u2014 new platform users can be auto-invited when provisioning is enabled
      •  
    • Client setup: Point Bitwarden clients to https://vault.DOMAIN
      •  
    ","tags":["guide","admin","services","integrations"]},{"location":"docs/admin/services/integrations/#whiteboard-excalidraw","title":"Whiteboard (Excalidraw)","text":"
    Collaborative whiteboard for brainstorming and campaign planning.
     
       
    • Real-time collaboration \u2014 multi-user drawing with WebSocket support
      •  
    • Embedded in admin \u2014 full-screen iframe at /app/services/excalidraw
      •  
    • Desktop only \u2014 requires a desktop browser for the drawing experience
      •  
    • Route: /app/services/excalidraw
      •  
    ","tags":["guide","admin","services","integrations"]},{"location":"docs/admin/services/integrations/#git-hosting-gitea","title":"Git Hosting (Gitea)","text":"
    Self-hosted Git repository hosting for campaign code and configuration.
     
       
    • Lightweight Git forge \u2014 repositories, issues, pull requests, and wikis
      •  
    • User provisioning \u2014 platform users can be auto-provisioned as Gitea accounts
      •  
    • Embedded \u2014 accessible at git.DOMAIN or embedded in admin at /app/services/gitea
      •  
    ","tags":["guide","admin","services","integrations"]},{"location":"docs/admin/services/integrations/#workflow-automation-n8n","title":"Workflow Automation (n8n)","text":"
    Self-hosted workflow automation for connecting platform events to external services.
     
       
    • Visual workflow editor \u2014 drag-and-drop automation builder
      •  
    • Webhook triggers \u2014 respond to platform events
      •  
    • Embedded \u2014 accessible at n8n.DOMAIN or embedded in admin at /app/services/n8n
      •  
    ","tags":["guide","admin","services","integrations"]},{"location":"docs/admin/services/integrations/#qr-code-generator-mini-qr","title":"QR Code Generator (Mini QR)","text":"
    Built-in QR code generation for walk sheets, volunteer invites, and campaign links.
     
       
    • Public API \u2014 QR code PNG generation at /api/qr
      •  
    • Walk sheet integration \u2014 QR codes embedded in printable walk sheets
      •  
    • Volunteer quick join \u2014 QR codes for instant volunteer onboarding
      •  
    • Embedded \u2014 admin interface at /app/services/qr
      •  
    ","tags":["guide","admin","services","integrations"]},{"location":"docs/admin/services/monitoring/","title":"Monitoring","text":"
    The monitoring stack runs as a Docker Compose profile and provides metrics collection, visualization, and alerting.
     
    ","tags":["guide","admin","services","monitoring"]},{"location":"docs/admin/services/monitoring/#starting-the-stack","title":"Starting the Stack","text":"
    docker compose --profile monitoring up -d\n
     
    This starts Prometheus, Grafana, Alertmanager, cAdvisor, Node Exporter, and Redis Exporter.
    ","tags":["guide","admin","services","monitoring"]},{"location":"docs/admin/services/monitoring/#custom-metrics","title":"Custom Metrics","text":"
    The platform exposes 12 custom cm_* Prometheus metrics:
     
       
    • API request rates and latencies
      •  
    • BullMQ queue sizes (email, SMS, video scheduling)
      •  
    • Active canvass sessions
      •  
    • External service health gauges
      •  
    ","tags":["guide","admin","services","monitoring"]},{"location":"docs/admin/services/monitoring/#grafana-dashboards","title":"Grafana Dashboards","text":"
    Three pre-configured dashboards auto-provisioned from configs/grafana/:
     
       
    • API Performance \u2014 request rates, latencies, error rates
      •  
    • Application Overview \u2014 queue sizes, active sessions, service health
      •  
    • System Health \u2014 container resources, host metrics, Redis stats
      •  
    ","tags":["guide","admin","services","monitoring"]},{"location":"docs/admin/services/monitoring/#alertmanager","title":"Alertmanager","text":"
    Alert rules in configs/prometheus/alerts.yml cover:
     
       
    • API downtime and high error rates
      •  
    • Queue backlogs
      •  
    • Service connectivity failures
      •  
    • Resource utilization thresholds
      •  
    ","tags":["guide","admin","services","monitoring"]},{"location":"docs/admin/services/monitoring/#admin-routes","title":"Admin Routes","text":"
       
    • /app/observability \u2014 embedded Grafana dashboards, alert status, and service health (3 tabs)
      •  
    ","tags":["guide","admin","services","monitoring"]},{"location":"docs/admin/services/monitoring/#direct-access","title":"Direct Access","text":"
       
    • Grafana: localhost:3001 or grafana.DOMAIN
      •  
    • Prometheus: localhost:9090
      •  
    • Alertmanager: localhost:9093
      •  
    ","tags":["guide","admin","services","monitoring"]},{"location":"docs/admin/services/tunnel/","title":"Tunnel (Pangolin)","text":"
    Pangolin provides secure tunneling to expose your self-hosted services to the internet without port forwarding or a static IP.
     
    ","tags":["guide","admin","services","networking"]},{"location":"docs/admin/services/tunnel/#setup","title":"Setup","text":"
    From /app/pangolin:
     
       
    • Automated setup \u2014 one-command deployment that creates the Pangolin site, updates .env with credentials, and restarts the Newt tunnel container
      •  
    • Manual setup \u2014 step-by-step instructions for connecting to an existing Pangolin instance
      •  
    ","tags":["guide","admin","services","networking"]},{"location":"docs/admin/services/tunnel/#resource-management","title":"Resource Management","text":"
    The platform defines 12+ service resources in configs/pangolin/resources.yml:
     
       
    • Each resource maps a subdomain (e.g., api.DOMAIN, app.DOMAIN) to an internal service
      •  
    • Hourly sync \u2014 nginx cron job pushes resource definitions to Pangolin automatically
      •  
    • Status dashboard \u2014 view tunnel connection status and resource health
      •  
    ","tags":["guide","admin","services","networking"]},{"location":"docs/admin/services/tunnel/#newt-container","title":"Newt Container","text":"
    The Newt container runs alongside nginx and tunnels traffic to your services:
     
       
    • Configured via PANGOLIN_NEWT_ID and PANGOLIN_NEWT_SECRET environment variables
      •  
    • Depends on nginx (all resources route through nginx:80)
      •  
    • Auto-restarts on failure
      •  
    ","tags":["guide","admin","services","networking"]},{"location":"docs/admin/services/tunnel/#security","title":"Security","text":"
    The Pangolin server runs CrowdSec for intrusion detection with a web management UI protected by Tinyauth forward-auth. See CrowdSec & Security for details on:
     
       
    • CrowdSec Manager dashboard (crowdsec.bnkserve.org)
      •  
    • Tinyauth authentication (auth.bnkserve.org)
      •  
    • Canadian ISP whitelisting and crawl detection tuning
      •  
    • Cloudflare Turnstile captcha integration
      •  
    ","tags":["guide","admin","services","networking"]},{"location":"docs/admin/services/tunnel/#admin-routes","title":"Admin Routes","text":"
       
    • /app/pangolin \u2014 tunnel status, setup wizard, and resource management
      •  
    ","tags":["guide","admin","services","networking"]},{"location":"docs/admin/services/user-provisioning/","title":"User Provisioning","text":"
    Automatically create and sync user accounts across integrated services when new platform users are registered. Enable with enableUserProvisioning in Settings.
    ","tags":["guide","admin","services"]},{"location":"docs/admin/services/user-provisioning/#supported-services","title":"Supported Services","text":"Service Mode Notes Rocket.Chat Always lazy SSO on first access Gitea Eager or lazy Admin API provisioning Vaultwarden Eager or lazy Invite-based (no password management) Listmonk Eager or lazy Subscriber sync","tags":["guide","admin","services"]},{"location":"docs/admin/services/user-provisioning/#configuration","title":"Configuration","text":"
    From Settings > User Provisioning:
     
       
    • Toggle provisioning per service
      •  
    • Choose eager (create immediately on user registration) or lazy (create on first access)
      •  
    • View provisioning status per user in the Service Accounts panel on the Users page
      •  
    ","tags":["guide","admin","services"]},{"location":"docs/admin/services/user-provisioning/#bulk-sync","title":"Bulk Sync","text":"
    Trigger a bulk sync from /api/users/provisioning/sync to provision all existing users across enabled services. Useful after enabling a new service.
    ","tags":["guide","admin","services"]},{"location":"docs/admin/services/user-provisioning/#admin-routes","title":"Admin Routes","text":"
       
    • /app/users (edit drawer) \u2014 per-user service account status and actions
      •  
    • /app/settings (User Provisioning tab) \u2014 per-service toggle and timing
      •  
    ","tags":["guide","admin","services"]},{"location":"docs/admin/web/","title":"Web Content","text":"
    Manage the public-facing web presence \u2014 landing pages, the dynamic homepage, navigation menu, and documentation site.
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/#in-this-section","title":"In This Section","text":"
       
    • Landing Pages \u2014 build campaign microsites with the GrapesJS drag-and-drop editor
      •  
    • Homepage \u2014 dynamic public landing page aggregating campaigns, shifts, media, and events
      •  
    • Navigation \u2014 customize the public navigation menu with toggles, custom links, and reordering
      •  
    • Documentation \u2014 MkDocs site management, page analytics, and comment moderation
      •  
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/#social-sharing","title":"Social Sharing","text":"
    All public content (campaigns, landing pages, gallery videos) automatically generates Open Graph and Twitter Card meta tags for rich link previews when shared on social media, messaging apps, and search engines. OG responses are cached in Redis for 10 minutes.
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/documentation/","title":"Documentation","text":"
    Manage the MkDocs documentation site, track page engagement, and moderate visitor comments.
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/documentation/#mkdocs-management","title":"MkDocs Management","text":"
    From Docs (/app/docs):
     
       
    • View MkDocs build status and health
      •  
    • Browse the documentation file tree
      •  
    • Export landing pages to MkDocs as Jinja2 Material theme overrides
      •  
    • Configure documentation settings from MkDocs Settings (/app/docs/settings)
      •  
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/documentation/#documentation-analytics","title":"Documentation Analytics","text":"
    Track how visitors interact with documentation pages using the MkDocs Material theme's custom analytics provider and navigation.tracking.
     
       
    • Navigation tracking \u2014 updates the browser URL as users scroll through sections, enabling section-level engagement tracking
      •  
    • Custom provider \u2014 integrates with any third-party analytics tool (Plausible, Umami, Google Analytics) via template overrides in docs/overrides/
      •  
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/documentation/#comments","title":"Comments","text":"
    Visitors can leave comments on documentation pages using a Gitea-backed comment system.
     
       
    • Anonymous posting \u2014 visitors can comment without creating an account
      •  
    • Gitea-backed \u2014 comments stored as Gitea issues (one issue per page) for version control and searchability
      •  
    • Moderation \u2014 admin panel at /app/docs-comments for approving, hiding, or deleting comments
      •  
    • OAuth login \u2014 optional Gitea OAuth for authenticated commenting
      •  
    • Per-page threads \u2014 each documentation page gets its own comment thread
      •  
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/documentation/#admin-routes","title":"Admin Routes","text":"
       
    • /app/docs \u2014 MkDocs management (file tree, config, build triggers)
      •  
    • /app/docs/settings \u2014 documentation configuration
      •  
    • /app/docs-comments \u2014 moderate documentation comments
      •  
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/homepage/","title":"Public Homepage","text":"
    A dynamic public landing page that showcases your organization and aggregates content from across the platform.
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/homepage/#sections","title":"Sections","text":"
    The homepage assembles its content from enabled modules. Sections are only displayed when their corresponding module is active and has data to show.
     
       
    • Hero banner \u2014 organization name, logo, tagline (configurable via Settings), and call-to-action buttons for campaigns and volunteer signups
      •  
    • Stats counters \u2014 active campaigns, total emails sent, and volunteer signups (shown only when counts are greater than zero)
      •  
    • Featured campaigns \u2014 up to 3 active campaigns, sorted by highlight status then creation date, with email counts and descriptions
      •  
    • Upcoming shifts \u2014 up to 3 open shifts with date, time, location, and spots remaining
      •  
    • Latest videos \u2014 up to 4 recently published videos from the media library, displayed in a horizontal scroll strip with thumbnails and durations
      •  
    • Upcoming events \u2014 up to 3 future events from Gancio with date, location, and tags
      •  
    • Recent activity \u2014 a compact activity feed showing the latest platform actions
      •  
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/homepage/#data-caching","title":"Data & Caching","text":"
    All homepage data is fetched from a single API endpoint (/api/homepage) and cached in Redis for 2 minutes. Individual section queries use Promise.allSettled so that a failure in one module (e.g., Gancio being offline) does not prevent the rest of the page from loading.
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/homepage/#configuration","title":"Configuration","text":"
       
    • Organization name and logo \u2014 set via Settings > Organization
      •  
    • Homepage tagline \u2014 set via the homepageTagline field in site settings
      •  
    • Module visibility \u2014 controlled by feature flags (enableInfluence, enableMap, enableMediaFeatures, enableEvents, enablePayments, enableLandingPages)
      •  
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/homepage/#public-routes","title":"Public Routes","text":"
       
    • /home \u2014 public homepage
      •  
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/landing-pages/","title":"Landing Pages","text":"
    Build campaign microsites with a drag-and-drop visual editor.
     
    ","tags":["guide","admin","content","landing-pages"]},{"location":"docs/admin/web/landing-pages/#how-it-works","title":"How It Works","text":"
       
    1. Create a new page from the admin panel
      2.  
    2. Open the GrapesJS visual editor \u2014 drag blocks, edit text, adjust styles
      3.  
    3. Save and publish \u2014 the page goes live at /p/:slug
      4.  
    4. Optionally export to MkDocs for inclusion in the documentation site
      5.  
    ","tags":["guide","admin","content","landing-pages"]},{"location":"docs/admin/web/landing-pages/#admin-routes","title":"Admin Routes","text":"
       
    • /app/pages \u2014 list and manage landing pages
      •  
    • /app/pages/:id/edit \u2014 full-screen GrapesJS editor
      •  
    ","tags":["guide","admin","content","landing-pages"]},{"location":"docs/admin/web/landing-pages/#public-routes","title":"Public Routes","text":"
       
    • /p/:slug \u2014 view a published landing page
      •  
    ","tags":["guide","admin","content","landing-pages"]},{"location":"docs/admin/web/navigation/","title":"Navigation Settings","text":"
    Customize the public-facing navigation menu from the admin panel. The navigation bar appears on all public pages, the admin header, the Gancio events page, and the MkDocs documentation site.
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/navigation/#key-features","title":"Key Features","text":"
       
    • Per-item toggle -- enable or disable each navigation item with a switch
      •  
    • Custom links -- add external links or internal paths to the navigation
      •  
    • Reorder -- move items up and down to arrange them in any order
      •  
    • Editable labels and paths -- rename any item or change its destination
      •  
    • Feature flag awareness -- builtin items tied to a feature flag (e.g., Campaigns requires enableInfluence) are automatically hidden when that feature is disabled
      •  
    • Visitor control -- determine exactly what public visitors can access
      •  
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/navigation/#builtin-items","title":"Builtin Items","text":"
    The platform ships with 11 builtin navigation items that cover the main public routes:
     
    Home, Campaigns, Map, Shifts, Events, Gallery, Pricing, Shop, Donate, Website (landing page), and Docs (documentation site).
     
    Each builtin item has a default icon and path. Some paths use special $ tokens (e.g., $landing, $docs) that are automatically resolved to the correct external URL based on the deployment environment.
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/navigation/#custom-links","title":"Custom Links","text":"
    Add any number of custom links via the \"Add Custom Link\" button. Custom links support:
     
       
    • Internal paths (e.g., /blog)
      •  
    • External URLs (e.g., https://example.com) -- automatically detected and opened in a new tab
      •  
     
    Custom links can be deleted from the navigation; builtin items can only be toggled off.
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/navigation/#mobile-handling","title":"Mobile Handling","text":"
    On mobile devices, the navigation collapses into a hamburger menu that opens a full-height drawer. On desktop, the nav bar also supports a collapse mode that hides labels and shows only icons, toggled via a fold/unfold button. The collapse state is persisted in local storage.
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/navigation/#admin-routes","title":"Admin Routes","text":"
       
    • /app/navigation -- navigation editor with per-item toggle, reorder, label editing, and custom link management
      •  
    ","tags":["guide","admin","content"]},{"location":"docs/api/","title":"API Reference","text":"
    Changemaker Lite exposes two REST APIs sharing a single PostgreSQL database.
     Server Framework Port Purpose Main API Express.js 4000 Auth, campaigns, map, shifts, canvassing, pages, email, settings Media API Fastify 4100 Video library, analytics, playlists, reactions, comments 
    Both APIs use JWT Bearer authentication and return JSON. All request/response bodies are application/json unless noted otherwise.
    ","tags":["reference","developer","API"]},{"location":"docs/api/#authentication","title":"Authentication","text":"","tags":["reference","developer","API"]},{"location":"docs/api/#token-flow","title":"Token Flow","text":"
    sequenceDiagram\n    participant Client\n    participant API\n    participant DB\n\n    Client->>API: POST /api/auth/login {email, password}\n    API->>DB: Verify credentials\n    DB-->>API: User record\n    API-->>Client: {accessToken, refreshToken}\n    Note over Client: Store tokens\n\n    Client->>API: GET /api/campaigns (Authorization: Bearer <accessToken>)\n    API-->>Client: 200 OK\n\n    Note over Client: Access token expires (15 min)\n\n    Client->>API: POST /api/auth/refresh {refreshToken}\n    API->>DB: Rotate token (atomic transaction)\n    DB-->>API: New token pair\n    API-->>Client: {accessToken, refreshToken}
    ","tags":["reference","developer","API"]},{"location":"docs/api/#headers","title":"Headers","text":"
    All authenticated requests require:
     
    Authorization: Bearer <accessToken>\n
     
    The Media API also accepts tokens via query parameter for SSE streams:
     
    GET /api/public/:id/chat-stream?token=<accessToken>\n
    ","tags":["reference","developer","API"]},{"location":"docs/api/#roles","title":"Roles","text":"Role Access Level SUPER_ADMIN Full platform access INFLUENCE_ADMIN Campaign and advocacy management MAP_ADMIN Map, locations, shifts, canvassing USER Volunteer portal, public features TEMP Limited access (auto-created on public shift signup)","tags":["reference","developer","API"]},{"location":"docs/api/#middleware-reference","title":"Middleware Reference","text":"Middleware Effect authenticate Requires valid JWT. Sets req.user with id, email, role. Returns 401 if missing or invalid. optionalAuth Same as authenticate but continues without user if token is absent. requireRole(...roles) Checks user role against allowed list. Returns 403 if not authorized. requireNonTemp Blocks TEMP users. Returns 403. validate(schema, source) Validates request body/query/params against a Zod schema. Returns 400 on failure.","tags":["reference","developer","API"]},{"location":"docs/api/#error-responses","title":"Error Responses","text":"
    All errors follow a consistent format:
     
    {\n  \"error\": {\n    \"message\": \"Human-readable error description\",\n    \"code\": \"ERROR_CODE\",\n    \"statusCode\": 400\n  }\n}\n
     Status Code Meaning 400 VALIDATION_ERROR Request body/query failed schema validation 401 UNAUTHORIZED Missing or invalid access token 403 FORBIDDEN Valid token but insufficient role 404 NOT_FOUND Resource does not exist 429 RATE_LIMITED Too many requests (see Rate Limits) 500 INTERNAL_ERROR Unexpected server error 
    Enumeration Prevention
     
    Auth endpoints (/login, /register, /forgot-password) return generic success messages to prevent user enumeration. A 401 from /api/auth/me does not reveal whether the user exists.
    ","tags":["reference","developer","API"]},{"location":"docs/api/#rate-limits","title":"Rate Limits","text":"
    Rate limits are Redis-backed and keyed by IP address.
     Endpoint Group Window Max Requests Redis Prefix Auth (login, register, refresh) 15 min 10 rl:auth: Email sending 1 hour 30 rl:email: Response submission 1 hour 10 rl:response: Shift signup 1 hour 10 rl:shift-signup: Canvass visits 1 min 30 rl:canvass-visit: Canvass bulk visits 1 min 5 rl:canvass-visit-bulk: GPS tracking 1 min 6 rl:gps-tracking: Canvass geocode 1 min 10 rl:canvass-geocode: Observability 1 min 20 rl:observability: Health/metrics 1 min 30 rl:health-metrics: Global (all other) Configurable Configurable rl:global: 
    When rate-limited, the API returns:
     
    {\n  \"error\": {\n    \"message\": \"Too many requests, please try again later\",\n    \"code\": \"RATE_LIMITED\",\n    \"statusCode\": 429\n  }\n}\n
    ","tags":["reference","developer","API"]},{"location":"docs/api/#main-api-express-port-4000","title":"Main API (Express \u2014 Port 4000)","text":"","tags":["reference","developer","API"]},{"location":"docs/api/#health-metrics","title":"Health & Metrics","text":"Method Path Auth Description GET /api/health Health check \u2014 PostgreSQL + Redis ping GET /api/metrics Prometheus metrics (text/plain) Health response 
    {\n  \"status\": \"healthy\",\n  \"checks\": {\n    \"database\": \"ok\",\n    \"redis\": \"ok\"\n  }\n}\n
    ","tags":["reference","developer","API"]},{"location":"docs/api/#auth","title":"Auth","text":"
    Prefix: /api/auth
     Method Path Auth Rate Limited Description POST /api/auth/login Email + password login POST /api/auth/register Create account (always USER role) POST /api/auth/verify-email Verify email with token POST /api/auth/resend-verification Resend verification email POST /api/auth/forgot-password Send password reset email POST /api/auth/reset-password Set new password with reset token POST /api/auth/refresh Rotate refresh token \u2192 new token pair POST /api/auth/logout Invalidate refresh token GET /api/auth/me Current user profile Login request & response 
    Request: 
    {\n  \"email\": \"admin@example.com\",\n  \"password\": \"SecurePass123!\"\n}\n
     Response: 
    {\n  \"accessToken\": \"eyJhbG...\",\n  \"refreshToken\": \"eyJhbG...\",\n  \"user\": {\n    \"id\": \"uuid\",\n    \"email\": \"admin@example.com\",\n    \"name\": \"Admin\",\n    \"role\": \"SUPER_ADMIN\"\n  }\n}\n
     
    Password Policy
     
    Passwords must be at least 12 characters with at least one uppercase letter, one lowercase letter, and one digit.
    ","tags":["reference","developer","API"]},{"location":"docs/api/#users","title":"Users","text":"
    Prefix: /api/users \u00b7 Auth: All routes require authentication
     Method Path Role Description GET /api/users Admin Paginated user list with search, role, and status filters GET /api/users/:id Admin or self Single user profile POST /api/users Admin Create user PUT /api/users/:id Admin or self Update user (non-admins cannot change role/status) POST /api/users/:id/approve Admin Approve pending user; sends approval email POST /api/users/:id/reject Admin Reject pending user DELETE /api/users/:id Admin Delete user 
    Query parameters for GET /api/users:
     Param Type Description page number Page number (default 1) limit number Items per page (default 20) search string Search by name or email role string Filter by role status string Filter by status","tags":["reference","developer","API"]},{"location":"docs/api/#dashboard","title":"Dashboard","text":"
    Prefix: /api/dashboard \u00b7 Auth: Admin roles required
     Method Path Role Description GET /api/dashboard/summary Any admin Platform-wide counts (users, campaigns, locations, shifts) GET /api/dashboard/system SUPER_ADMIN Hardware + OS info (CPU, memory, disk) GET /api/dashboard/containers SUPER_ADMIN Docker container statuses GET /api/dashboard/weather Any admin Current weather at map center coordinates GET /api/dashboard/api-metrics SUPER_ADMIN Prometheus API performance metrics GET /api/dashboard/time-series SUPER_ADMIN Prometheus time-series data GET /api/dashboard/container-resources SUPER_ADMIN cAdvisor CPU/memory/network per container 
    Query parameters for GET /api/dashboard/time-series:
     Param Type Description metrics string Comma-separated metric keys (whitelist-validated) range string Time range (e.g., 1h, 24h, 7d) step string Sample interval (e.g., 5m, 1h)","tags":["reference","developer","API"]},{"location":"docs/api/#campaigns","title":"Campaigns","text":"","tags":["reference","developer","API"]},{"location":"docs/api/#admin-crud","title":"Admin CRUD","text":"
    Prefix: /api/campaigns \u00b7 Auth: Admin roles
     Method Path Description GET /api/campaigns Paginated campaign list GET /api/campaigns/:id Single campaign detail POST /api/campaigns Create campaign PUT /api/campaigns/:id Update campaign DELETE /api/campaigns/:id Delete campaign","tags":["reference","developer","API"]},{"location":"docs/api/#public","title":"Public","text":"Method Path Auth Description GET /api/campaigns/public List all active campaigns GET /api/campaigns/:slug/details Campaign detail by slug (ACTIVE only)","tags":["reference","developer","API"]},{"location":"docs/api/#user-submissions","title":"User Submissions","text":"
    Auth: Authenticated, non-TEMP users
     Method Path Description POST /api/campaigns/user/submit Submit campaign for moderation (5/hour limit) GET /api/campaigns/user/my-campaigns List own submitted campaigns PUT /api/campaigns/user/:id Edit own pending campaign","tags":["reference","developer","API"]},{"location":"docs/api/#moderation","title":"Moderation","text":"
    Auth: Admin roles
     Method Path Description GET /api/campaigns/moderation/queue Campaigns pending moderation GET /api/campaigns/moderation/stats Moderation queue statistics PATCH /api/campaigns/moderation/:id Approve or reject campaign","tags":["reference","developer","API"]},{"location":"docs/api/#campaign-emails","title":"Campaign Emails","text":"Method Path Auth Description POST /api/campaigns/:slug/send-email Send advocacy email to representatives (rate limited: 30/hour) POST /api/campaigns/:slug/track-mailto Track mailto link click GET /api/campaigns/:id/emails Admin Paginated emails for campaign GET /api/campaigns/:id/email-stats Admin Email statistics","tags":["reference","developer","API"]},{"location":"docs/api/#responses","title":"Responses","text":"
    Prefix: /api/campaigns (public) and /api/responses (admin + actions)
    ","tags":["reference","developer","API"]},{"location":"docs/api/#public_1","title":"Public","text":"Method Path Auth Description GET /api/campaigns/:slug/responses List approved public responses GET /api/campaigns/:slug/response-stats Response statistics POST /api/campaigns/:slug/responses Submit response (rate limited: 10/hour) POST /api/responses/:id/upvote Optional Upvote a response DELETE /api/responses/:id/upvote Optional Remove upvote GET /api/responses/:id/verify/:token Verify response via email link","tags":["reference","developer","API"]},{"location":"docs/api/#admin","title":"Admin","text":"
    Auth: Admin roles
     Method Path Description GET /api/responses All responses with filters PATCH /api/responses/:id/status Approve or reject response POST /api/responses/:id/resend-verification Resend verification email DELETE /api/responses/:id Delete response","tags":["reference","developer","API"]},{"location":"docs/api/#representatives","title":"Representatives","text":"
    Prefix: /api/representatives
     Method Path Auth Description GET /api/representatives/by-postal/:postalCode Lookup representatives by postal code (cache-first) GET /api/representatives/test-connection Represent API health check GET /api/representatives/cache-stats Admin Cache statistics GET /api/representatives Admin Paginated cached representatives GET /api/representatives/:id Admin Single cached representative DELETE /api/representatives/by-postal/:postalCode Admin Clear cache for postal code DELETE /api/representatives/:id Admin Delete cached representative 
    Query parameters for postal code lookup:
     Param Type Description refresh boolean Force API call, bypass cache","tags":["reference","developer","API"]},{"location":"docs/api/#email-queue","title":"Email Queue","text":"
    Prefix: /api/email-queue \u00b7 Auth: Admin roles
     Method Path Description GET /api/email-queue/stats BullMQ queue statistics (waiting, active, completed, failed) POST /api/email-queue/pause Pause email processing POST /api/email-queue/resume Resume email processing POST /api/email-queue/clean Clean completed jobs","tags":["reference","developer","API"]},{"location":"docs/api/#locations","title":"Locations","text":"
    Prefix: /api/map/locations
    ","tags":["reference","developer","API"]},{"location":"docs/api/#public_2","title":"Public","text":"Method Path Description GET /api/map/locations/public All geocoded locations for map (no PII); optional ?bounds=","tags":["reference","developer","API"]},{"location":"docs/api/#admin_1","title":"Admin","text":"
    Auth: SUPER_ADMIN or MAP_ADMIN
     Method Path Description GET /api/map/locations Paginated locations with filters GET /api/map/locations/stats Location statistics GET /api/map/locations/all All geocoded locations for admin map GET /api/map/locations/export-csv CSV export GET /api/map/locations/:id Single location GET /api/map/locations/:id/history Edit history POST /api/map/locations Create location PUT /api/map/locations/:id Update location DELETE /api/map/locations/:id Delete location POST /api/map/locations/bulk-delete Bulk delete POST /api/map/locations/geocode Geocode single address POST /api/map/locations/geocode-missing Batch geocode all ungeocoded POST /api/map/locations/reverse-geocode Reverse geocode lat/lng to address POST /api/map/locations/import-csv Import from CSV (10 MB limit) POST /api/map/locations/import-bulk Bulk NAR or standard CSV import (100 MB limit)","tags":["reference","developer","API"]},{"location":"docs/api/#bulk-geocode","title":"Bulk Geocode","text":"
    Prefix: /api/map/locations/bulk-geocode \u00b7 Auth: Map admins
     Method Path Description POST /api/map/locations/bulk-geocode Start BullMQ bulk geocoding job GET /api/map/locations/bulk-geocode/:jobId Poll job status GET /api/map/locations/bulk-geocode/stats Queue statistics","tags":["reference","developer","API"]},{"location":"docs/api/#nar-import","title":"NAR Import","text":"
    Prefix: /api/map/nar-import \u00b7 Auth: Map admins
     Method Path Description GET /api/map/nar-import/datasets Available NAR datasets by province POST /api/map/nar-import Start province import (fire-and-forget) GET /api/map/nar-import/status/:importId Poll import progress NAR Import body 
    {\n  \"provinceCode\": \"24\",\n  \"filterType\": \"city\",\n  \"filterCity\": \"Edmonton\",\n  \"residentialOnly\": true,\n  \"deduplicateRadius\": 10,\n  \"batchSize\": 500\n}\n
    ","tags":["reference","developer","API"]},{"location":"docs/api/#area-import","title":"Area Import","text":"
    Prefix: /api/map/area-import \u00b7 Auth: Map admins
     Method Path Description POST /api/map/area-import/preview Preview bounds + estimated record counts POST /api/map/area-import Start area import (fire-and-forget) GET /api/map/area-import/status/:importId Poll import progress","tags":["reference","developer","API"]},{"location":"docs/api/#cuts-polygons","title":"Cuts (Polygons)","text":"
    Prefix: /api/map/cuts
     Method Path Auth Description GET /api/map/cuts/public All public cuts as GeoJSON GET /api/map/cuts Map admin Paginated cuts list GET /api/map/cuts/:id Map admin Single cut POST /api/map/cuts Map admin Create cut (polygon GeoJSON) PUT /api/map/cuts/:id Map admin Update cut DELETE /api/map/cuts/:id Map admin Delete cut GET /api/map/cuts/:id/locations Map admin All locations within cut polygon GET /api/map/cuts/:id/statistics Map admin Support level breakdown GET /api/map/cuts/export-geojson Map admin All cuts as GeoJSON FeatureCollection GET /api/map/cuts/:id/export-geojson Map admin Single cut as GeoJSON Feature POST /api/map/cuts/import-geojson Map admin Import cuts from GeoJSON file","tags":["reference","developer","API"]},{"location":"docs/api/#shifts","title":"Shifts","text":"
    Prefix: /api/map/shifts
    ","tags":["reference","developer","API"]},{"location":"docs/api/#public_3","title":"Public","text":"Method Path Description GET /api/map/shifts/public List upcoming public shifts POST /api/map/shifts/public/:id/signup Public signup (creates TEMP user if needed; rate limited: 10/hour)","tags":["reference","developer","API"]},{"location":"docs/api/#volunteer","title":"Volunteer","text":"
    Auth: Any authenticated user
     Method Path Description GET /api/map/shifts/volunteer/upcoming Upcoming shifts with signup status GET /api/map/shifts/volunteer/my-signups Own confirmed signups POST /api/map/shifts/volunteer/:id/signup Sign up for shift DELETE /api/map/shifts/volunteer/:id/signup Cancel signup","tags":["reference","developer","API"]},{"location":"docs/api/#admin_2","title":"Admin","text":"
    Auth: Map admins
     Method Path Description GET /api/map/shifts Paginated shifts with filters GET /api/map/shifts/stats Statistics GET /api/map/shifts/calendar Calendar data (?startDate=&endDate=) GET /api/map/shifts/:id Single shift with signups POST /api/map/shifts Create shift PUT /api/map/shifts/:id Update shift DELETE /api/map/shifts/:id Delete shift POST /api/map/shifts/:id/signups Admin-add volunteer DELETE /api/map/shifts/:id/signups/:signupId Remove volunteer POST /api/map/shifts/:id/email-details Email details to all volunteers","tags":["reference","developer","API"]},{"location":"docs/api/#shift-series","title":"Shift Series","text":"
    Auth: Map admins
     Method Path Description POST /api/map/shifts/series Create recurring shift series GET /api/map/shifts/series/:id Get series PUT /api/map/shifts/series/:id Update series DELETE /api/map/shifts/series/:id Delete series","tags":["reference","developer","API"]},{"location":"docs/api/#canvassing","title":"Canvassing","text":"
    Prefix: /api/map/canvass
    ","tags":["reference","developer","API"]},{"location":"docs/api/#volunteer_1","title":"Volunteer","text":"
    Auth: Any authenticated user
     Method Path Description GET /api/map/canvass/my/assignments Shift assignments GET /api/map/canvass/my/stats Personal canvass statistics GET /api/map/canvass/my/visits Visit history GET /api/map/canvass/my/session Active canvass session POST /api/map/canvass/sessions Start canvass session POST /api/map/canvass/sessions/:id/end End session GET /api/map/canvass/cuts/:cutId/locations Locations in cut with visit annotations GET /api/map/canvass/cuts/:cutId/route Walking route algorithm for cut GET /api/map/canvass/locations All locations with visit annotations PUT /api/map/canvass/locations/:id Edit address (role-gated fields) POST /api/map/canvass/locations Create location POST /api/map/canvass/reverse-geocode Reverse geocode lat/lng POST /api/map/canvass/geocode-search Geocode address for map (rate limited: 10/min) POST /api/map/canvass/visits Record door knock (rate limited: 30/min) POST /api/map/canvass/visits/bulk Record visit for all unvisited units (rate limited: 5/min)","tags":["reference","developer","API"]},{"location":"docs/api/#admin_3","title":"Admin","text":"
    Auth: SUPER_ADMIN or MAP_ADMIN
     Method Path Description GET /api/map/canvass/stats Platform-wide canvass statistics GET /api/map/canvass/stats/cuts/:cutId Statistics for specific cut GET /api/map/canvass/activity Recent activity feed GET /api/map/canvass/volunteers All volunteers with canvass activity GET /api/map/canvass/volunteers/:userId Individual volunteer statistics GET /api/map/canvass/visits All visits with filters","tags":["reference","developer","API"]},{"location":"docs/api/#gps-tracking","title":"GPS Tracking","text":"
    Prefix: /api/map/tracking
    ","tags":["reference","developer","API"]},{"location":"docs/api/#volunteer_2","title":"Volunteer","text":"
    Auth: Any authenticated user
     Method Path Description POST /api/map/tracking/sessions Start GPS tracking session POST /api/map/tracking/sessions/:id/end End tracking session POST /api/map/tracking/sessions/:id/points Submit GPS point batch (rate limited: 6/min) POST /api/map/tracking/sessions/:id/link-canvass Link to canvass session GET /api/map/tracking/my/session Active tracking session GET /api/map/tracking/my/sessions Own historical sessions GET /api/map/tracking/my/sessions/:id/route Full route for own session","tags":["reference","developer","API"]},{"location":"docs/api/#admin_4","title":"Admin","text":"
    Auth: Map admins
     Method Path Description GET /api/map/tracking/live Live volunteer positions + trails GET /api/map/tracking/sessions All historical tracking sessions GET /api/map/tracking/sessions/:id/route Full route for any session","tags":["reference","developer","API"]},{"location":"docs/api/#map-settings","title":"Map Settings","text":"
    Prefix: /api/map/settings
     Method Path Auth Description GET /api/map/settings Public map settings (center, zoom, walk sheet config) PUT /api/map/settings Map admin Update map settings","tags":["reference","developer","API"]},{"location":"docs/api/#geocoding","title":"Geocoding","text":"
    Prefix: /api/map/geocoding \u00b7 Auth: Map admins
     Method Path Description GET /api/map/geocoding/search Geocode address search (?q=&limit=1-10)","tags":["reference","developer","API"]},{"location":"docs/api/#landing-pages","title":"Landing Pages","text":"
    Prefix: /api/pages and /api/page-blocks
    ","tags":["reference","developer","API"]},{"location":"docs/api/#public_4","title":"Public","text":"Method Path Auth Description GET /api/pages/:slug/view Get published page by slug","tags":["reference","developer","API"]},{"location":"docs/api/#admin_5","title":"Admin","text":"
    Auth: Admin roles
     Method Path Description GET /api/pages Paginated landing pages GET /api/pages/:id Single page POST /api/pages Create page PUT /api/pages/:id Update page DELETE /api/pages/:id Delete page POST /api/pages/sync Sync MkDocs overrides from filesystem POST /api/pages/validate Validate and repair MkDocs exports","tags":["reference","developer","API"]},{"location":"docs/api/#block-library","title":"Block Library","text":"
    Auth: Admin roles
     Method Path Description GET /api/page-blocks List blocks GET /api/page-blocks/:id Single block POST /api/page-blocks Create block PUT /api/page-blocks/:id Update block DELETE /api/page-blocks/:id Delete block","tags":["reference","developer","API"]},{"location":"docs/api/#email-templates","title":"Email Templates","text":"
    Prefix: /api/email-templates \u00b7 Auth: Admin roles (seed/cache require SUPER_ADMIN)
     Method Path Description GET /api/email-templates List templates GET /api/email-templates/:id Single template POST /api/email-templates Create template PUT /api/email-templates/:id Update template DELETE /api/email-templates/:id Delete template GET /api/email-templates/:id/versions Version history GET /api/email-templates/:id/versions/:versionNumber Specific version POST /api/email-templates/:id/rollback Rollback to prior version POST /api/email-templates/validate Validate Handlebars syntax POST /api/email-templates/:id/test Send test email (rate limited: 10/15min) GET /api/email-templates/:id/test-logs Test send logs POST /api/email-templates/seed Seed templates from filesystem POST /api/email-templates/clear-cache Clear template cache","tags":["reference","developer","API"]},{"location":"docs/api/#qr-codes","title":"QR Codes","text":"Method Path Auth Description GET /api/qr Generate QR code PNG (?text=&size=50-500) 
    Cached for 1 hour. Returns image/png.
    ","tags":["reference","developer","API"]},{"location":"docs/api/#site-settings","title":"Site Settings","text":"
    Prefix: /api/settings
     Method Path Auth Description GET /api/settings Public site settings (SMTP credentials stripped) GET /api/settings/admin SUPER_ADMIN Full settings including SMTP credentials PUT /api/settings SUPER_ADMIN Update settings POST /api/settings/email/test-connection SUPER_ADMIN Test SMTP connection POST /api/settings/email/test-send SUPER_ADMIN Send test email","tags":["reference","developer","API"]},{"location":"docs/api/#listmonk-newsletter-sync","title":"Listmonk (Newsletter Sync)","text":"
    Prefix: /api/listmonk \u00b7 Auth: SUPER_ADMIN
     Method Path Description GET /api/listmonk Sync status + connection check GET /api/listmonk/stats Subscriber counts from Listmonk POST /api/listmonk/test-connection Health check POST /api/listmonk/sync/participants Sync campaign participants POST /api/listmonk/sync/locations Sync locations POST /api/listmonk/sync/users Sync users POST /api/listmonk/sync/all Run all sync operations POST /api/listmonk/reinitialize Reinitialize Listmonk lists GET /api/listmonk/proxy-url Proxy port + JWT for iframe","tags":["reference","developer","API"]},{"location":"docs/api/#documentation-management","title":"Documentation Management","text":"
    Prefix: /api/docs \u00b7 Auth: Authenticated, non-TEMP (write operations require SUPER_ADMIN)
     Method Path Description GET /api/docs/status MkDocs + Code Server availability GET /api/docs/config Port numbers for iframe URLs GET /api/docs/mkdocs-config Read raw mkdocs.yml PUT /api/docs/mkdocs-config Write mkdocs.yml POST /api/docs/build Trigger MkDocs build POST /api/docs/upload Upload asset (20 MB, whitelisted extensions) GET /api/docs/files File tree (?force=true bypasses cache) POST /api/docs/files/rename Rename or move file GET /api/docs/files/* Read file content PUT /api/docs/files/* Write file content POST /api/docs/files/* Create file or folder DELETE /api/docs/files/* Delete file or empty folder","tags":["reference","developer","API"]},{"location":"docs/api/#services","title":"Services","text":"
    Prefix: /api/services \u00b7 Auth: SUPER_ADMIN
     Method Path Description GET /api/services/status Health check all managed services (NocoDB, n8n, Gitea, MailHog, Mini QR, Excalidraw, Homepage) GET /api/services/config Port numbers + subdomain info","tags":["reference","developer","API"]},{"location":"docs/api/#pangolin-tunnel-management","title":"Pangolin (Tunnel Management)","text":"
    Prefix: /api/pangolin \u00b7 Auth: SUPER_ADMIN
     Method Path Description GET /api/pangolin/status Tunnel health + connection info GET /api/pangolin/config Current env configuration GET /api/pangolin/newt-status Newt container status POST /api/pangolin/newt-restart Restart Newt container GET /api/pangolin/sites List Pangolin sites GET /api/pangolin/exit-nodes Available exit nodes GET /api/pangolin/resource-definitions Resource definitions from YAML GET /api/pangolin/resources List resources POST /api/pangolin/setup Create site + all resources (rate limited: \u2157min) POST /api/pangolin/sync Sync resources (create missing, update changed) PUT /api/pangolin/resource/:id Update resource DELETE /api/pangolin/resource/:id Delete resource GET /api/pangolin/resource/:id/clients Connected clients GET /api/pangolin/certificate/:domainId/:domain Certificate info POST /api/pangolin/certificate/:certId Update certificate","tags":["reference","developer","API"]},{"location":"docs/api/#observability","title":"Observability","text":"
    Prefix: /api/observability \u00b7 Auth: SUPER_ADMIN \u00b7 Rate limited: 20/min
     Method Path Description GET /api/observability/status Check 7 monitoring services GET /api/observability/metrics-summary Key metrics from Prometheus GET /api/observability/alerts Active alerts from Alertmanager","tags":["reference","developer","API"]},{"location":"docs/api/#payments","title":"Payments","text":"
    Prefix: /api/payments
    ","tags":["reference","developer","API"]},{"location":"docs/api/#public_5","title":"Public","text":"Method Path Auth Description GET /api/payments/config Stripe publishable key + donation settings GET /api/payments/plans Active subscription plans GET /api/payments/products Active products (?type=) POST /api/payments/subscribe Create subscription checkout POST /api/payments/purchase Optional Product checkout (guest or logged-in) POST /api/payments/donate Donation checkout GET /api/payments/my-subscription Current subscription POST /api/payments/my-subscription/cancel Cancel subscription POST /api/payments/webhook Stripe webhook (raw body)","tags":["reference","developer","API"]},{"location":"docs/api/#admin_6","title":"Admin","text":"
    Auth: SUPER_ADMIN
     Method Path Description GET /api/payments/admin/settings Payment settings (secrets masked) PUT /api/payments/admin/settings Update payment settings POST /api/payments/admin/settings/test-connection Test Stripe connection GET /api/payments/admin/dashboard Subscription + donation statistics GET /api/payments/admin/plans All subscription plans POST /api/payments/admin/plans Create plan PUT /api/payments/admin/plans/:id Update plan DELETE /api/payments/admin/plans/:id Delete plan POST /api/payments/admin/plans/:id/sync-stripe Sync plan to Stripe GET /api/payments/admin/subscriptions All subscriptions with filters POST /api/payments/admin/subscriptions/:id/cancel Cancel subscription GET /api/payments/admin/products All products POST /api/payments/admin/products Create product PUT /api/payments/admin/products/:id Update product DELETE /api/payments/admin/products/:id Delete product POST /api/payments/admin/products/:id/sync-stripe Sync product to Stripe GET /api/payments/admin/orders List orders POST /api/payments/admin/orders/:id/refund Refund order GET /api/payments/admin/donations List donations GET /api/payments/admin/export CSV export of completed orders","tags":["reference","developer","API"]},{"location":"docs/api/#media-api-fastify-port-4100","title":"Media API (Fastify \u2014 Port 4100)","text":"
    The Media API is a separate Fastify server sharing the same PostgreSQL database. It handles all video-related functionality.
    ","tags":["reference","developer","API"]},{"location":"docs/api/#health","title":"Health","text":"Method Path Auth Description GET /health Media API health check","tags":["reference","developer","API"]},{"location":"docs/api/#videos-admin","title":"Videos (Admin)","text":"
    Prefix: /api/videos \u00b7 Auth: Admin roles
    ","tags":["reference","developer","API"]},{"location":"docs/api/#crud-publishing","title":"CRUD & Publishing","text":"Method Path Description GET /api/videos List videos (?limit=&offset=&search=&orientation=&producers=&isShort=) GET /api/videos/producers Distinct producer list GET /api/videos/health Video count health check GET /api/videos/:id Single video detail PATCH /api/videos/:id Update metadata (title, producer, tags, quality, etc.) POST /api/videos/:id/publish Publish to category POST /api/videos/:id/unpublish Unpublish POST /api/videos/bulk-publish Bulk publish POST /api/videos/bulk-unpublish Bulk unpublish POST /api/videos/:id/lock Lock published video POST /api/videos/:id/unlock Unlock video POST /api/videos/:id/generate-thumbnail Generate thumbnail via FFmpeg POST /api/videos/bulk-generate-thumbnails Bulk thumbnail generation","tags":["reference","developer","API"]},{"location":"docs/api/#upload","title":"Upload","text":"Method Path Description POST /api/videos/upload Single video upload (multipart, 10 GB limit, streams to disk) POST /api/videos/upload/batch Batch upload (returns 207 multi-status)","tags":["reference","developer","API"]},{"location":"docs/api/#actions","title":"Actions","text":"Method Path Description POST /api/videos/:id/duplicate Duplicate video record POST /api/videos/:id/replace Replace video file, keep metadata GET /api/videos/:id/analytics Detailed analytics (?startDate=&endDate=) POST /api/videos/:id/reset-analytics Reset all analytics GET /api/videos/:id/preview-link Generate 24-hour JWT preview link GET /api/videos/analytics/top Top videos (?metric=views|watchTime&limit=) GET /api/videos/analytics/overview Global analytics overview","tags":["reference","developer","API"]},{"location":"docs/api/#scheduling","title":"Scheduling","text":"Method Path Description POST /api/videos/:id/schedule-publish Schedule future publish ({publishAt, timezone?}) POST /api/videos/:id/schedule-unpublish Schedule future unpublish DELETE /api/videos/:id/schedule/:action Cancel scheduled operation GET /api/videos/schedules/upcoming Upcoming scheduled operations GET /api/videos/:id/schedule-history Schedule history for video GET /api/videos/schedules/stats Schedule queue statistics POST /api/videos/schedules/pause Pause schedule queue POST /api/videos/schedules/resume Resume schedule queue POST /api/videos/schedules/cleanup Clean old completed jobs","tags":["reference","developer","API"]},{"location":"docs/api/#video-fetch","title":"Video Fetch","text":"Method Path Description POST /api/videos/fetch Submit fetch job ({urls: string[]}, 1\u201320 URLs) GET /api/videos/fetch/jobs List recent fetch jobs GET /api/videos/fetch/jobs/:jobId Job detail + log GET /api/videos/fetch/jobs/:jobId/log SSE log stream (Redis pub/sub) DELETE /api/videos/fetch/jobs/:jobId Cancel fetch job","tags":["reference","developer","API"]},{"location":"docs/api/#streaming-public","title":"Streaming (Public)","text":"
    Prefix: /api/videos
     Method Path Auth Description GET /api/videos/stream/health Streaming health check GET /api/videos/:id/stream Optional HTTP range-supporting video stream GET /api/videos/:id/thumbnail Optional Serve thumbnail image GET /api/videos/:id/metadata Public video metadata for embedding 
    Note
     
    Admins can stream unpublished videos by providing a valid JWT.
    ","tags":["reference","developer","API"]},{"location":"docs/api/#public-gallery","title":"Public Gallery","text":"
    Prefix: /api/public
     Method Path Auth Description GET /api/public Optional Published videos (?limit=&offset=&search=&sort=recent|popular|oldest&category=) GET /api/public/categories Optional Categories with video counts GET /api/public/producers Optional Published producers GET /api/public/:id Optional Single published video GET /api/public/:id/thumbnail Optional Published thumbnail GET /api/public/:id/stream Optional Published video stream","tags":["reference","developer","API"]},{"location":"docs/api/#tracking","title":"Tracking","text":"
    Prefix: /api/track \u00b7 Auth: None required
     Method Path Description GET /api/track/health Tracking health check POST /api/track/view Record video view (returns {viewId}) POST /api/track/event Record play/pause/seek/complete event POST /api/track/heartbeat Update watch time (10s interval, sendBeacon) POST /api/track/batch Batch up to 50 tracking events Tracking is GDPR-compliant 
    IP addresses are hashed with a daily-rotating salt. Raw IPs are never stored. Tracking data is retained for 90 days.
    ","tags":["reference","developer","API"]},{"location":"docs/api/#reactions","title":"Reactions","text":"
    Prefix: /api/reactions
     Method Path Auth Description GET /api/reactions/config Available reaction types + emoji mappings GET /api/reactions List reactions (?mediaId=&userId=&limit=) GET /api/reactions/:mediaId/chat Reactions in chat timeline format POST /api/reactions Add reaction (30s cooldown per type) 
    Available types: like, love, laugh, wow, sad, angry
    ","tags":["reference","developer","API"]},{"location":"docs/api/#comments-chat","title":"Comments & Chat","text":"","tags":["reference","developer","API"]},{"location":"docs/api/#public-comments","title":"Public Comments","text":"Method Path Auth Description GET /api/public/:id/comments List comments (?limit=&offset=) POST /api/public/:id/comments Optional Create comment (word-filtered; rate limited: 5/min) GET /api/public/:id/chat-stream SSE stream for real-time chat (30s keepalive)","tags":["reference","developer","API"]},{"location":"docs/api/#comment-admin","title":"Comment Admin","text":"
    Prefix: /api/media/admin/comments \u00b7 Auth: Admin roles
     Method Path Description GET /api/media/admin/comments/stats Counts by status GET /api/media/admin/comments All comments with filters PATCH /api/media/admin/comments/:id/approve Approve comment PATCH /api/media/admin/comments/:id/hide Hide comment PATCH /api/media/admin/comments/:id/unhide Unhide comment PUT /api/media/admin/comments/:id/notes Update moderation notes DELETE /api/media/admin/comments/:id Delete comment","tags":["reference","developer","API"]},{"location":"docs/api/#word-filters","title":"Word Filters","text":"
    Prefix: /api/media/admin/word-filters \u00b7 Auth: Admin roles
     Method Path Description GET /api/media/admin/word-filters List filter entries grouped by level POST /api/media/admin/word-filters Add word ({word, level: low|medium|high|custom}) DELETE /api/media/admin/word-filters/:id Remove word","tags":["reference","developer","API"]},{"location":"docs/api/#chat-threads-notifications","title":"Chat Threads & Notifications","text":"
    Auth: Authenticated
     Method Path Description GET /api/media/chat/threads Videos with user's comments + unread counts POST /api/media/chat/threads/:mediaId/read Mark thread as read GET /api/media/notifications/stream Per-user SSE notification stream (?token=)","tags":["reference","developer","API"]},{"location":"docs/api/#shorts","title":"Shorts","text":"Method Path Auth Description GET /api/shorts Optional Shorts feed (?sort=recent|popular|random) POST /api/shorts/scan Admin Auto-classify short videos by duration","tags":["reference","developer","API"]},{"location":"docs/api/#upvotes","title":"Upvotes","text":"Method Path Auth Description POST /api/public/:id/upvote Toggle upvote (session-based via X-Session-ID header) GET /api/public/:id/upvote-status Check upvote status for current session","tags":["reference","developer","API"]},{"location":"docs/api/#playlists","title":"Playlists","text":"","tags":["reference","developer","API"]},{"location":"docs/api/#public_6","title":"Public","text":"
    Prefix: /api/playlists
     Method Path Auth Description GET /api/playlists/featured Optional Featured playlists GET /api/playlists/popular Optional Popular public playlists (?search=) GET /api/playlists/share/:token Optional Playlist by share token GET /api/playlists/:id Optional Playlist detail (public, owner, or share token) POST /api/playlists/:id/view Optional Record playlist view","tags":["reference","developer","API"]},{"location":"docs/api/#user-playlists","title":"User Playlists","text":"
    Auth: Authenticated
     Method Path Description GET /api/playlists/my Own playlists POST /api/playlists Create playlist PUT /api/playlists/:id Update playlist (ownership check) DELETE /api/playlists/:id Delete playlist POST /api/playlists/:id/videos Add video ({mediaId}) DELETE /api/playlists/:id/videos/:mediaId Remove video PUT /api/playlists/:id/videos/reorder Reorder videos POST /api/playlists/:id/share Generate share token DELETE /api/playlists/:id/share Revoke share token","tags":["reference","developer","API"]},{"location":"docs/api/#playlist-admin","title":"Playlist Admin","text":"
    Prefix: /api/media/playlists \u00b7 Auth: Admin roles
     Method Path Description GET /api/media/playlists All playlists GET /api/media/playlists/featured Featured playlists with admin info POST /api/media/playlists/:id/feature Feature a playlist DELETE /api/media/playlists/:id/feature Unfeature a playlist PUT /api/media/playlists/featured/reorder Reorder featured playlists PUT /api/media/playlists/:id Admin update any playlist POST /api/media/playlists/:id/duplicate Duplicate playlist DELETE /api/media/playlists/:id Admin delete any playlist","tags":["reference","developer","API"]},{"location":"docs/api/#user-profile","title":"User Profile","text":"
    Prefix: /api/media/me \u00b7 Auth: Authenticated
     Method Path Description GET /api/media/me/stats User stats + 30-day activity + achievements GET /api/media/me/watch-history Paginated watch history POST /api/media/me/stats/recalculate Recompute stats from raw data GET /api/media/me/settings Privacy settings PUT /api/media/me/settings Update privacy settings PUT /api/media/me/profile Update display name PUT /api/media/me/password Change password","tags":["reference","developer","API"]},{"location":"docs/api/#route-summary","title":"Route Summary","text":"API Module Endpoint Count Express Auth 9 Users 7 Dashboard 7 Campaigns (CRUD + public + user + moderation + emails) 16 Responses 10 Email Queue 4 Representatives 7 Locations (CRUD + geocode + import) 21 Cuts 11 Shifts (CRUD + series) 19 Canvassing 20 GPS Tracking 10 Map Settings + Geocoding 3 Pages + Blocks 12 Email Templates 13 QR Codes 1 Site Settings 5 Listmonk 9 Docs Management 11 Services 2 Pangolin 16 Observability 3 Payments (public + admin) 29 Health + Metrics 3 Express Total ~248 Fastify Videos (CRUD + upload + actions + schedule + fetch) 39 Streaming 4 Public Gallery 6 Tracking 5 Reactions 4 Comments + Chat 13 Shorts + Upvotes 4 Playlists (public + user + admin) 18 User Profile 7 Health 1 Fastify Total ~101 Grand Total ~349","tags":["reference","developer","API"]},{"location":"docs/architecture/","title":"Architecture","text":"
    Changemaker Lite uses a dual-API architecture with a shared PostgreSQL database, a React single-page application, and Nginx for subdomain routing across 30+ services.
    ","tags":["reference","developer","architecture"]},{"location":"docs/architecture/#system-diagram","title":"System Diagram","text":"
    graph LR\n    Browser[\"Browser\"] --> Nginx[\"Nginx<br/>(reverse proxy)\"]\n    Nginx --> Admin[\"React Admin GUI<br/>port 3000\"]\n    Nginx --> API[\"Express API<br/>port 4000\"]\n    Nginx --> MediaAPI[\"Fastify Media API<br/>port 4100\"]\n    Nginx --> MkDocs[\"MkDocs<br/>port 4003/4004\"]\n    Nginx --> Services[\"Other Services<br/>(Gitea, NocoDB, etc.)\"]\n\n    API --> PostgreSQL[(\"PostgreSQL 16<br/>30+ tables\")]\n    MediaAPI --> PostgreSQL\n    API --> Redis[(\"Redis<br/>cache + queues\")]\n    API --> BullMQ[\"BullMQ<br/>(email, video jobs)\"]\n    BullMQ --> Redis\n\n    subgraph Tunnel [\"Public Access\"]\n        Newt[\"Newt Client\"] --> Pangolin[\"Pangolin Server\"]\n    end\n    Newt --> Nginx
    ","tags":["reference","developer","architecture"]},{"location":"docs/architecture/#key-components","title":"Key Components","text":"Component Technology Role Main API Express.js + TypeScript + Prisma Auth, campaigns, map, shifts, pages, canvassing, email Media API Fastify + TypeScript + Prisma Video library, analytics, uploads, scheduling Admin GUI React 19 + Vite + Ant Design + Zustand Admin dashboard, public pages, volunteer portal, media gallery Database PostgreSQL 16 Shared by both APIs (30+ models via Prisma) Cache Redis 7 Rate limiting, BullMQ job queues, geocoding cache Proxy Nginx Subdomain routing, security headers, WebSocket upgrade Tunnel Pangolin + Newt Expose services without port forwarding Monitoring Prometheus + Grafana + Alertmanager Metrics collection, dashboards, alerting","tags":["reference","developer","architecture"]},{"location":"docs/architecture/#dual-api-design","title":"Dual API Design","text":"
    The platform runs two independent API servers sharing one PostgreSQL database:
     Express API (port 4000)Fastify Media API (port 4100) 
    The main API handles all core platform logic:
     
       
    • Authentication \u2014 JWT access/refresh tokens, RBAC middleware
      •  
    • Modules \u2014 Influence (campaigns, responses), Map (locations, cuts, shifts, canvassing), Pages, Email Templates, Settings, Users, Payments, Social, Calendar
      •  
    • Services \u2014 Email queue (BullMQ), geocoding queue, Listmonk sync, Pangolin client, user provisioning
      •  
    • ORM \u2014 Prisma with 30+ models and migration history
      •  
     
    A separate server optimized for media handling:
     
       
    • Video CRUD \u2014 Upload with FFprobe metadata extraction
      •  
    • Scheduled Publishing \u2014 BullMQ queue with timezone support
      •  
    • Analytics \u2014 View tracking, watch time, completion rates (GDPR-compliant)
      •  
    • Public Gallery \u2014 Playlists, reactions, comments, SSE chat
      •  
    • ORM \u2014 Prisma (migrated from Drizzle, Feb 2026)
      •  
     
    Both servers connect to the same database and share the same Prisma schema. This separation allows the media API to handle large file uploads and streaming independently from the main API's request/response cycle.
    ","tags":["reference","developer","architecture"]},{"location":"docs/architecture/#authentication-flow","title":"Authentication Flow","text":"
    sequenceDiagram\n    participant Client\n    participant API\n    participant DB\n    participant Redis\n\n    Client->>API: POST /api/auth/login {email, password}\n    API->>Redis: Check rate limit (10/min per IP)\n    Redis-->>API: OK\n    API->>DB: Verify bcrypt password\n    DB-->>API: User record\n    API->>DB: Create refresh token\n    API-->>Client: {accessToken (15min), refreshToken (7d)}\n\n    Note over Client: Authenticated requests\n    Client->>API: GET /api/campaigns<br/>Authorization: Bearer <accessToken>\n    API->>API: Verify JWT + check role (RBAC)\n    API-->>Client: 200 OK\n\n    Note over Client: Token expired\n    Client->>API: POST /api/auth/refresh {refreshToken}\n    API->>DB: Atomic rotation (delete old, create new)\n    API-->>Client: {new accessToken, new refreshToken}
    ","tags":["reference","developer","architecture"]},{"location":"docs/architecture/#security-features","title":"Security Features","text":"
       
    • Password policy \u2014 12+ characters, uppercase, lowercase, digit (schema-enforced)
      •  
    • Refresh token rotation \u2014 Atomic Prisma transaction prevents race conditions
      •  
    • User enumeration prevention \u2014 Returns 401 (not 404) for missing users
      •  
    • Rate limiting \u2014 10 requests/minute on auth endpoints via Redis
      •  
    • 11 roles \u2014 SUPER_ADMIN (implicit bypass), 8 module-specific admin roles, USER, TEMP
      •  
    • Encryption \u2014 AES-256-GCM for sensitive DB fields (ENCRYPTION_KEY env var)
      •  
    ","tags":["reference","developer","architecture"]},{"location":"docs/architecture/#request-lifecycle","title":"Request Lifecycle","text":"
    graph TD\n    A[\"Incoming Request\"] --> B[\"Nginx\"]\n    B -->|\"Host: api.domain\"| C[\"Express API\"]\n    B -->|\"Host: media.domain\"| D[\"Fastify Media API\"]\n    B -->|\"Host: app.domain\"| E[\"React Admin GUI\"]\n    C --> F[\"Rate Limiter (Redis)\"]\n    F --> G[\"Auth Middleware (JWT)\"]\n    G --> H[\"Role Check (RBAC)\"]\n    H --> I[\"Validation (Zod)\"]\n    I --> J[\"Route Handler\"]\n    J --> K[\"Service Layer\"]\n    K --> L[\"Prisma ORM\"]\n    L --> M[(\"PostgreSQL\")]\n    J --> N[\"Response + Metrics\"]
    ","tags":["reference","developer","architecture"]},{"location":"docs/architecture/#database-schema","title":"Database Schema","text":"
    The database contains 30+ Prisma models organized by module:
     Module Key Models Auth User, RefreshToken Influence Campaign, CampaignEmail, CampaignResponse, Representative, PostalCode Map Location, Address, Cut, Shift, ShiftSignup Canvass CanvassSession, CanvassVisit, TrackingSession, TrackingPoint Pages Page, PageBlock, EmailTemplate Media Video, VideoReaction, VideoComment, VideoView, Playlist, PlaylistVideo Payments StripeProduct, StripePrice, StripeDonationPage, StripeOrder Social Friendship, SocialNotification, CalendarLayer, CalendarItem SMS SmsContactList, SmsCampaign, SmsMessage, SmsConversation People Contact, ContactAddress, ContactEmail, ContactPhone, ContactConnection Settings SiteSettings, MapSettings","tags":["reference","developer","architecture"]},{"location":"docs/architecture/#docker-compose-architecture","title":"Docker Compose Architecture","text":"
    Services are organized into categories with dependency management:
     
    graph TD\n    subgraph Core [\"Core (always started)\"]\n        PG[\"PostgreSQL\"] --> API[\"Express API\"]\n        Redis --> API\n        PG --> Media[\"Fastify Media API\"]\n        API --> Admin[\"React Admin\"]\n        Admin --> Nginx\n        API --> Nginx\n        Media --> Nginx\n    end\n\n    subgraph Communication [\"Communication (optional)\"]\n        RC[\"Rocket.Chat\"] --> MongoDB\n        Jitsi[\"Jitsi Meet (4 containers)\"]\n        Gancio[\"Gancio Events\"]\n    end\n\n    subgraph Monitoring [\"Monitoring (profile)\"]\n        Prometheus --> Grafana\n        Prometheus --> Alertmanager\n        cAdvisor --> Prometheus\n        NodeExporter --> Prometheus\n    end\n\n    subgraph Tunnel [\"Tunnel\"]\n        Newt --> Nginx\n    end
     
    Docker healthchecks ensure proper startup order: PostgreSQL and Redis must be healthy before the API starts. The API runs migrations and seeding automatically via its entrypoint script.
    ","tags":["reference","developer","architecture"]},{"location":"docs/architecture/#subdomain-routing","title":"Subdomain Routing","text":"
    Nginx routes requests based on the Host header. All services run on the changemaker-lite Docker bridge network.
     Pattern Target app.DOMAIN Admin GUI (admin + public + volunteer + gallery) api.DOMAIN Express API media.DOMAIN Fastify Media API DOMAIN (root) MkDocs static site *.DOMAIN 15+ additional service subdomains 
    See Services for the complete subdomain table.
    ","tags":["reference","developer","architecture"]},{"location":"docs/deployment/","title":"Deployment","text":"
    This guide covers how to take Changemaker Lite from a local development setup to a publicly accessible production deployment. The main decision is how to expose your services to the internet.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#architecture-overview","title":"Architecture Overview","text":"
    Regardless of which exposure method you choose, the internal architecture is the same:
     
    Internet \u2192 [Your exposure method] \u2192 Nginx (port 80) \u2192 Backend Services\n
     
    Nginx handles all subdomain routing internally. Every service is accessed through nginx on port 80, which proxies to the correct container based on the Host header.
     Subdomain Service Container Port app.DOMAIN Admin GUI + public pages 3000 api.DOMAIN Express API 4000 media.DOMAIN Fastify Media API 4100 DOMAIN (root) MkDocs documentation site 4004 db.DOMAIN NocoDB 8091 docs.DOMAIN MkDocs live preview 4003 code.DOMAIN Code Server 8888 git.DOMAIN Gitea 3030 n8n.DOMAIN Workflow automation 5678 home.DOMAIN Homepage dashboard 3010 listmonk.DOMAIN Newsletter manager 9001 mail.DOMAIN MailHog (dev email) 8025 qr.DOMAIN Mini QR generator 8089 draw.DOMAIN Excalidraw whiteboard 8090 vault.DOMAIN Vaultwarden password manager 8445 chat.DOMAIN Rocket.Chat team chat \u2014 events.DOMAIN Gancio event management 8092 grafana.DOMAIN Monitoring dashboards 3005","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#exposure-methods","title":"Exposure Methods","text":"","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#pangolin","title":"Option 1: Pangolin + Newt Tunnel (Recommended)","text":"
    Admin GUI: Tunnel Management Page
     
    The admin dashboard includes a dedicated Tunnel Management page at Admin \u2192 Settings \u2192 Tunnel. This page provides:
     
       
    • Live status of the Pangolin connection and Newt container health
      •  
    • Step-by-step setup instructions if credentials aren't configured yet
      •  
    • Full resource table listing every service, its domain, and target \u2014 useful as a reference when creating resources in the Pangolin dashboard
      •  
    • API-based site creation as an alternative to the Pangolin dashboard UI
      •  
    • Restart Newt button for quick container restarts without the terminal
      •  
     
    If you're unsure about any step above, the Tunnel page walks you through the same process interactively.
     
    Pangolin is a self-hosted tunnel server. The Newt client container runs alongside your stack and establishes an outbound connection to your Pangolin server, which then routes public traffic back through the tunnel. No port forwarding or static IP required.
     
    Advantages:
     
       
    • No port forwarding needed on your router/firewall
      •  
    • Works behind CGNAT, double NAT, or restrictive networks
      •  
    • SSL/TLS handled by the Pangolin server
      •  
    • Self-hosted \u2014 you control the tunnel infrastructure
      •  
    • Built-in access control (optional per-resource authentication)
      •  
     
    Requirements:
     
       
    • A Pangolin server (self-hosted on a VPS with a public IP)
      •  
    • A domain with DNS pointing to the Pangolin server
      •  
    • Pangolin API key and organization ID
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#step-1-configure-pangolin-credentials","title":"Step 1: Configure Pangolin Credentials","text":"
    If you used config.sh, you may have already set these. Otherwise, add to your .env:
     
    PANGOLIN_API_URL=https://api.your-pangolin-server.org/v1\nPANGOLIN_API_KEY=your_api_key_here\nPANGOLIN_ORG_ID=your_org_id\n
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#step-2-create-a-site-in-pangolin","title":"Step 2: Create a Site in Pangolin","text":"
    Log in to your Pangolin dashboard and create a new site:
     
       
    1. Navigate to Sites \u2192 Create New Site
      2.  
    2. Choose type: Newt
      3.  
    3. Enter a name (e.g., changemaker-yourdomain.org)
      4.  
    4. Choose a subnet (e.g., 100.90.128.3/24)
      5.  
    5. Select an exit node (if applicable)
      6.  
    6. Click Create Site
      7.  
    7. Copy the credentials \u2014 you'll need the Site ID, Newt ID, and Newt Secret
      8.  
     
    Save the credentials
     
    The Newt Secret is only shown once during site creation. Copy it immediately.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#step-3-update-env-with-site-credentials","title":"Step 3: Update .env with Site Credentials","text":"
    PANGOLIN_SITE_ID=your_site_id\nPANGOLIN_ENDPOINT=https://your-pangolin-server.org\nPANGOLIN_NEWT_ID=your_newt_id\nPANGOLIN_NEWT_SECRET=your_newt_secret\n
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#step-4-start-the-newt-container","title":"Step 4: Start the Newt Container","text":"
    docker compose up -d newt\n
     
    The Newt container connects to nginx (its only dependency) and establishes the tunnel:
     
    # From docker-compose.yml\nnewt:\n  image: fosrl/newt\n  container_name: newt-changemaker\n  restart: unless-stopped\n  environment:\n    - PANGOLIN_ENDPOINT=${PANGOLIN_ENDPOINT}\n    - NEWT_ID=${PANGOLIN_NEWT_ID}\n    - NEWT_SECRET=${PANGOLIN_NEWT_SECRET}\n  depends_on:\n    - nginx\n
     
    Verify the connection:
     
    docker compose logs newt --tail 20\n
     
    You should see a successful connection message.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#step-5-create-public-http-resources","title":"Step 5: Create Public HTTP Resources","text":"
    In the Pangolin dashboard, create an HTTP resource for each service you want exposed. All resources point to nginx:80 \u2014 nginx handles the routing internally.
     
    Required resources (minimum for a working deployment):
     Resource Name Domain Target Auth Admin GUI app.yourdomain.org nginx:80 Not Protected API Server api.yourdomain.org nginx:80 Not Protected Public Site yourdomain.org nginx:80 Not Protected 
    Optional resources (add as needed):
     Resource Name Domain Target Media API media.yourdomain.org nginx:80 NocoDB db.yourdomain.org nginx:80 Documentation docs.yourdomain.org nginx:80 Code Server code.yourdomain.org nginx:80 Gitea git.yourdomain.org nginx:80 Grafana grafana.yourdomain.org nginx:80 
    Set resources to Not Protected
     
    By default, Pangolin may enable authentication on new resources. This causes 302 redirects to the Pangolin login page instead of reaching your services. Set each resource to Not Protected (public access) unless you intentionally want Pangolin SSO in front of it.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#step-6-update-cors-for-production","title":"Step 6: Update CORS for Production","text":"
    Add your production domain to CORS_ORIGINS in .env:
     
    CORS_ORIGINS=https://app.yourdomain.org,http://localhost:3000,http://localhost\n
     
    Then restart the API:
     
    docker compose restart api\n
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#step-7-verify","title":"Step 7: Verify","text":"
    # Should return JSON (not a 302 redirect)\ncurl https://api.yourdomain.org/api/health\n\n# Admin GUI should load\ncurl -I https://app.yourdomain.org\n
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#cloudflare","title":"Option 2: Cloudflare Tunnel","text":"
    Cloudflare Tunnel (cloudflared) provides a similar zero-trust tunnel approach using Cloudflare's network. No port forwarding needed, and you get Cloudflare's CDN and DDoS protection.
     
    Advantages:
     
       
    • Free tier available
      •  
    • Built-in CDN and DDoS protection
      •  
    • No port forwarding needed
      •  
    • Managed SSL certificates
      •  
     
    Disadvantages:
     
       
    • Proprietary service (not self-hosted)
      •  
    • Cloudflare sees all traffic (no end-to-end encryption to your origin)
      •  
    • Subject to Cloudflare's Terms of Service
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#setup","title":"Setup","text":"
       
    1.  
      Create a Cloudflare Tunnel in the Zero Trust dashboard
       
      2.  
    2.  
      Add a cloudflared service to your docker-compose.yml:
       
      cloudflared:\n  image: cloudflare/cloudflared:latest\n  container_name: cloudflared-changemaker\n  restart: unless-stopped\n  command: tunnel run\n  environment:\n    - TUNNEL_TOKEN=${CLOUDFLARE_TUNNEL_TOKEN}\n  depends_on:\n    - nginx\n  networks:\n    - changemaker-lite\n
       
      3.  
    3.  
      Add your tunnel token to .env:
       
      CLOUDFLARE_TUNNEL_TOKEN=your_tunnel_token_here\n
       
      4.  
    4.  
      Configure public hostnames in the Cloudflare dashboard, all pointing to http://nginx:80:
       Hostname Service app.yourdomain.org http://nginx:80 api.yourdomain.org http://nginx:80 yourdomain.org http://nginx:80 (add more as needed) http://nginx:80 
      5.  
    5.  
      Start the tunnel:
       
      docker compose up -d cloudflared\n
       
      6.  
     
    Note
     
    The cloudflared service is not included in the default docker-compose.yml. Add it manually if you choose this method. The Newt service can be removed or left stopped.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#direct","title":"Option 3: Direct DNS + Reverse Proxy","text":"
    If your server has a public IP address (e.g., a VPS or dedicated server), you can point DNS directly to it and use nginx with SSL certificates.
     
    Advantages:
     
       
    • No tunnel overhead or third-party dependency
      •  
    • Full control over the network path
      •  
    • Lowest latency
      •  
     
    Disadvantages:
     
       
    • Requires a public IP and open ports (80, 443)
      •  
    • You manage SSL certificates yourself
      •  
    • Server IP is exposed
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#setup_1","title":"Setup","text":"
       
    1.  
      Point DNS for your domain and all subdomains to your server's IP:
       
      A     yourdomain.org        \u2192 YOUR_SERVER_IP\nA     *.yourdomain.org      \u2192 YOUR_SERVER_IP\n
       
      Or use individual A records for each subdomain if your DNS provider doesn't support wildcards.
       
      2.  
    2.  
      Open ports 80 and 443 on your server's firewall.
       
      3.  
    3.  
      Install Certbot (or another ACME client) for SSL certificates:
       
      # Ubuntu/Debian\nsudo apt install certbot\n\n# Get a wildcard certificate with DNS challenge\nsudo certbot certonly --manual --preferred-challenges dns \\\n  -d yourdomain.org -d '*.yourdomain.org'\n
       
      Alternatively, use the Certbot Docker image or a Let's Encrypt companion container.
       
      4.  
    4.  
      Update nginx to listen on 443 with your certificates. Add an SSL server block to nginx/conf.d/ssl.conf:
       
      server {\n    listen 443 ssl;\n    server_name app.yourdomain.org;\n\n    ssl_certificate /etc/nginx/ssl/fullchain.pem;\n    ssl_certificate_key /etc/nginx/ssl/privkey.pem;\n\n    location / {\n        proxy_pass http://changemaker-v2-admin:3000;\n        proxy_set_header Host $host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header X-Forwarded-Proto $scheme;\n        proxy_set_header Upgrade $http_upgrade;\n        proxy_set_header Connection \"upgrade\";\n    }\n}\n\n# Repeat for api.yourdomain.org, media.yourdomain.org, etc.\n# Or use a single server block with $host matching\n
       
      5.  
    5.  
      Mount certificates into the nginx container via docker-compose.yml:
       
      nginx:\n  volumes:\n    - /etc/letsencrypt/live/yourdomain.org:/etc/nginx/ssl:ro\n
       
      6.  
    6.  
      Set up auto-renewal with a cron job or systemd timer:
       
      0 3 * * * certbot renew --quiet && docker compose restart nginx\n
       
      7.  
     
    Traefik alternative
     
    If you prefer automatic SSL and don't want to manage nginx SSL config manually, consider replacing nginx with Traefik. Traefik can auto-discover Docker containers and provision Let's Encrypt certificates automatically. This would require adapting the container labels and removing the nginx service.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#tailscale","title":"Option 4: Tailscale / WireGuard (Private Access)","text":"
    For deployments that should only be accessible to specific people (not the general public), a mesh VPN like Tailscale or plain WireGuard gives you private networking without exposing anything to the internet.
     
    Use cases:
     
       
    • Internal team deployments
      •  
    • Development/staging servers
      •  
    • Access from mobile devices without public exposure
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#tailscale-setup","title":"Tailscale Setup","text":"
       
    1. Install Tailscale on your server and client devices
      2.  
    2. Access services via Tailscale IP (e.g., http://100.x.x.x:3000)
      3.  
    3. Optionally use Tailscale Funnel to selectively expose specific services publicly
      4.  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#wireguard-setup","title":"WireGuard Setup","text":"
       
    1. Set up a WireGuard server on your host
      2.  
    2. Connect client devices via WireGuard config
      3.  
    3. Access services via the WireGuard interface IP
      4.  
     
    Note
     
    With private access methods, you may not need subdomain routing at all. Access services directly by port: http://server-ip:3000 (admin), http://server-ip:4000 (API), etc.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#production-checklist","title":"Production Checklist","text":"
    Before going live, verify each item:
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#security","title":"Security","text":"
       
    •  All placeholder passwords changed (grep -c \"REQUIRED_STRONG\" .env should return 0)
      •  
    •  NODE_ENV=production set in .env
      •  
    •  ENCRYPTION_KEY set and differs from JWT secrets
      •  
    •  EMAIL_TEST_MODE=false (unless you want MailHog in production)
      •  
    •  CORS_ORIGINS includes your production domain
      •  
    •  Admin password changed after first login
      •  
    •  Redis password set (REDIS_PASSWORD)
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#networking","title":"Networking","text":"
       
    •  DNS records configured for your domain and subdomains
      •  
    •  SSL/TLS working (tunnel handles this, or manual certs)
      •  
    •  All Pangolin resources set to \"Not Protected\" (if using Pangolin)
      •  
    •  curl https://api.yourdomain.org/api/health returns JSON
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#services","title":"Services","text":"
       
    •  Core services running: docker compose ps shows api, admin, v2-postgres, redis, nginx healthy
      •  
    •  Database migrated: docker compose exec api npx prisma migrate deploy
      •  
    •  Database seeded: docker compose exec api npx prisma db seed
      •  
    •  Admin GUI accessible at https://app.yourdomain.org
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#backups","title":"Backups","text":"
       
    •  Backup script tested: ./scripts/backup.sh
      •  
    •  Backup cron job configured (see Backups below)
      •  
    •  Restore procedure tested at least once
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#monitoring-optional","title":"Monitoring (Optional)","text":"
       
    •  Monitoring stack started: docker compose --profile monitoring up -d
      •  
    •  Grafana accessible and dashboards loading
      •  
    •  Alert rules configured in Alertmanager
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#backups_1","title":"Backups","text":"
    The included backup script dumps PostgreSQL databases, archives uploads, and optionally uploads to S3.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#running-a-backup","title":"Running a Backup","text":"
    ./scripts/backup.sh\n
     
    This creates a timestamped directory under ./backups/ containing:
     
       
    • changemaker_v2.sql.gz \u2014 Main PostgreSQL dump (compressed)
      •  
    • listmonk.sql.gz \u2014 Listmonk database dump (if running)
      •  
    • uploads.tar.gz \u2014 Media uploads archive
      •  
    • manifest.json \u2014 Backup metadata
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#options","title":"Options","text":"
    # Upload to S3 (requires AWS CLI + S3_BUCKET env var)\n./scripts/backup.sh --s3\n\n# Custom retention (delete local backups older than N days)\n./scripts/backup.sh --retention 14\n
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#automated-backups","title":"Automated Backups","text":"
    Add a cron job for daily backups:
     
    # Edit crontab\ncrontab -e\n\n# Add daily backup at 3 AM\n0 3 * * * /path/to/changemaker.lite/scripts/backup.sh >> /var/log/changemaker-backup.log 2>&1\n\n# With S3 upload\n0 3 * * * /path/to/changemaker.lite/scripts/backup.sh --s3 >> /var/log/changemaker-backup.log 2>&1\n
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#restore","title":"Restore","text":"
    # Restore main database\ngunzip -c backups/changemaker-v2-backup-TIMESTAMP/changemaker_v2.sql.gz | \\\n  docker compose exec -T v2-postgres psql -U changemaker changemaker_v2\n\n# Restore Listmonk database\ngunzip -c backups/changemaker-v2-backup-TIMESTAMP/listmonk.sql.gz | \\\n  docker compose exec -T listmonk-db psql -U listmonk listmonk\n\n# Restore uploads\ntar xzf backups/changemaker-v2-backup-TIMESTAMP/uploads.tar.gz -C ./\n
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#monitoring","title":"Monitoring","text":"
    The monitoring stack runs behind a Docker Compose profile and is not started by default.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#starting-the-monitoring-stack","title":"Starting the Monitoring Stack","text":"
    docker compose --profile monitoring up -d\n
     
    This starts:
     Service Port Purpose Prometheus 9090 Metrics collection and queries Grafana 3005 Dashboards and visualization Alertmanager 9093 Alert routing and notifications cAdvisor 8086 Container resource metrics Node Exporter 9100 Host system metrics Redis Exporter 9121 Redis metrics Gotify 8889 Push notifications","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#pre-configured-dashboards","title":"Pre-configured Dashboards","text":"
    Grafana includes 3 auto-provisioned dashboards:
     
       
    1. API Overview \u2014 HTTP request rates, latency, error rates, active sessions
      2.  
    2. Infrastructure \u2014 Container CPU/memory, PostgreSQL connections, Redis memory
      3.  
    3. Campaign Activity \u2014 Email queue size, campaign sends, response submissions
      4.  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#custom-metrics","title":"Custom Metrics","text":"
    The API exposes 12 custom Prometheus metrics with the cm_ prefix:
     
       
    • cm_api_uptime_seconds \u2014 API uptime
      •  
    • cm_email_queue_size \u2014 BullMQ pending emails
      •  
    • cm_active_canvass_sessions \u2014 Active canvassing sessions
      •  
    • cm_locations_total \u2014 Total locations in database
      •  
    • And more \u2014 see api/src/utils/metrics.ts
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#alert-rules","title":"Alert Rules","text":"
    Pre-configured alerts in configs/prometheus/alerts.yml:
     
       
    • API down for more than 5 minutes
      •  
    • High error rate (>5% of requests returning 5xx)
      •  
    • Database connection failures
      •  
    • Redis connection failures
      •  
    • Email queue backlog
      •  
    • Disk space warnings
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#upgrading","title":"Upgrading","text":"","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#pulling-updates","title":"Pulling Updates","text":"
    # Pull latest code\ngit pull origin v2\n\n# Rebuild and restart containers\ndocker compose build api admin\ndocker compose up -d api admin\n\n# Run any new migrations\ndocker compose exec api npx prisma migrate deploy\n
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#database-migrations","title":"Database Migrations","text":"
    Always run migrations after pulling updates:
     
    docker compose exec api npx prisma migrate deploy\n
     
    Back up first
     
    Always run ./scripts/backup.sh before applying migrations in production. Migrations may alter table structures and are not easily reversible.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#troubleshooting-production-issues","title":"Troubleshooting Production Issues","text":"","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#pangolin-302-redirects-instead-of-content","title":"Pangolin: 302 Redirects Instead of Content","text":"
    Symptom: API returns 302 redirects to the Pangolin authentication page.
     
    Fix: In the Pangolin dashboard, edit each resource and set Authentication to Not Protected.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#cors-errors","title":"CORS Errors","text":"
    Symptom: Browser console shows CORS errors when accessing the production domain.
     
    Fix: Add your production app. subdomain to CORS_ORIGINS in .env, then docker compose restart api.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#newt-wont-connect","title":"Newt Won't Connect","text":"
    Check in order:
     
       
    1. Credentials: Verify PANGOLIN_NEWT_ID and PANGOLIN_NEWT_SECRET in .env
      2.  
    2. Endpoint: Confirm PANGOLIN_ENDPOINT matches your Pangolin server URL
      3.  
    3. Logs: docker compose logs newt --tail 50
      4.  
    4. Nginx running: Newt depends on nginx \u2014 docker compose ps nginx
      5.  
    5. Network: Ensure outbound HTTPS is not blocked by your firewall
      6.  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#services-unreachable-via-tunnel","title":"Services Unreachable via Tunnel","text":"
       
    1. Verify nginx is running: docker compose ps nginx
      2.  
    2. Test locally first: curl http://localhost:4000/api/health
      3.  
    3. Check nginx logs: docker compose logs nginx --tail 50
      4.  
    4. Verify DNS: dig app.yourdomain.org should point to your Pangolin server
      5.  
     
    See Troubleshooting for more common issues.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/getting-started/","title":"Getting Started","text":"
    This guide walks you through installing Changemaker Lite, running your first deployment, and logging into the admin dashboard.
     
    ","tags":["guide","getting-started","operator"],"boost":2},{"location":"docs/getting-started/#prerequisites","title":"Prerequisites","text":"
       
    • Docker 24+ and Docker Compose v2
      •  
    • OpenSSL (for secret generation)
      •  
    • A Linux server (Ubuntu 22.04+ recommended) or macOS for development
      •  
    • At least 2 GB RAM and 10 GB disk space
      •  
    • A domain name (optional, but recommended for production)
      •  
    ","tags":["guide","getting-started","operator"],"boost":2},{"location":"docs/getting-started/#quick-install-pre-built-images","title":"Quick Install (Pre-built Images)","text":"
    The fastest way to deploy \u2014 no source code, no compilation:
     
    curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/v2/scripts/install.sh | bash\n
     
    This downloads a lightweight release package (~2 MB), runs the configuration wizard, and pulls pre-built Docker images. First startup takes ~2 minutes. See Installation for details.
    ","tags":["guide","getting-started","operator"],"boost":2},{"location":"docs/getting-started/#quick-start-from-source","title":"Quick Start (From Source)","text":"
    For development or customization, clone the full repository:
     
    git clone https://gitea.bnkops.com/admin/changemaker.lite\ncd changemaker.lite\ngit checkout v2\n
     
    bash config.sh\n
     
    docker compose up -d\n
     
    Open http://localhost:3000 and sign in with the admin email and password you configured. The API container automatically runs database migrations and seeding on first startup \u2014 no manual steps needed.
     
    Change your password
     
    If you used the wizard's generated password, change it immediately from the admin dashboard.
     
    For the full setup walkthrough, see Installation.
    ","tags":["guide","getting-started","operator"],"boost":2},{"location":"docs/getting-started/#configuration-wizard","title":"Configuration Wizard","text":"
    The config.sh wizard produces a fully populated .env file in 14 steps:
     Step What It Does 1. Prerequisites Verifies Docker, Docker Compose, and OpenSSL 2. Environment file Creates .env from .env.example (backs up existing) 3. Domain Sets root domain + 14 derived variables, updates mkdocs.yml 4. Admin credentials Email + password (enforces 12+ chars, mixed case, digit) 5. Secrets Auto-generates 21 unique secrets (JWT, encryption, database, service passwords) 6. Email MailHog (dev) or production SMTP, optionally shared with Listmonk 7. Feature flags 9 toggles: Media, Listmonk, Payments, Chat, Events, Meet, SMS, Docs Comments, Bunker Ops 8. Tunnel Pangolin credentials for secure public access 9. CORS Auto-calculated allowed origins from domain 10. Nginx Renders .conf.template files with domain substitution 11. Homepage Generates services.yaml with 27 service entries 12. Permissions Creates 12 directories with container-friendly permissions 13. Upgrade watcher Installs systemd units for GUI-triggered upgrades (optional, requires sudo) 14. Summary Displays configuration summary + next steps 
    See Installation for detailed documentation of each step.
    ","tags":["guide","getting-started","operator"],"boost":2},{"location":"docs/getting-started/#services","title":"Services","text":"
    Changemaker Lite includes 30+ Docker services organized into 8 categories:
     Category Services Startup Core API, Admin, PostgreSQL, Redis, Nginx docker compose up -d v2-postgres redis api admin nginx Media Fastify media API docker compose up -d media-api Communication Rocket.Chat, Gancio, Jitsi Meet Individual docker compose up -d commands Newsletter & Email Listmonk, MailHog docker compose up -d listmonk-app Developer Tools Code Server, MkDocs, Gitea, NocoDB, n8n Individual docker compose up -d commands Utilities Mini QR, Excalidraw, Vaultwarden, Homepage docker compose up -d mini-qr excalidraw vaultwarden homepage Monitoring Prometheus, Grafana, Alertmanager, exporters docker compose --profile monitoring up -d Infrastructure Newt tunnel, Docker socket proxy Auto-starts with tunnel configuration 
    See Services Overview for the complete catalog with ports, feature flags, and detailed descriptions.
    ","tags":["guide","getting-started","operator"],"boost":2},{"location":"docs/getting-started/#next-steps","title":"Next Steps","text":"
       
    • Installation \u2014 detailed setup walkthrough and manual configuration
      •  
    • Services Overview \u2014 complete service catalog (30+ containers)
      •  
    • Environment Variables \u2014 complete .env reference
      •  
    • First Steps \u2014 create your first campaign and add locations
      •  
    • Updates & Upgrades \u2014 keep your installation current
      •  
    • Control Panel (CCP) \u2014 multi-instance management
      •  
    • Features at a Glance \u2014 visual overview of every module
      •  
    • Admin Guide \u2014 full administration reference
      •  
    • Deployment \u2014 production setup with SSL and tunneling
      •  
    ","tags":["guide","getting-started","operator"],"boost":2},{"location":"docs/getting-started/control-panel/","title":"Changemaker Control Panel (CCP)","text":"
    The Changemaker Control Panel is a multi-tenant management layer for operators who run multiple Changemaker Lite instances from a single server. It provides a web UI to provision, monitor, and maintain a fleet of instances without manual configuration.
     
    Single instance?
     
    If you're running a single Changemaker Lite instance, you don't need CCP. Skip this page and continue with First Steps.
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#when-to-use-ccp","title":"When to Use CCP","text":"
    CCP is designed for:
     
       
    • Campaign organizations managing instances for multiple chapters or regions
      •  
    • Hosting providers offering Changemaker Lite as a managed service
      •  
    • Development teams spinning up isolated test instances
      •  
     
    CCP handles the entire instance lifecycle: provisioning, configuration, health monitoring, backups, and upgrades \u2014 all from a single dashboard.
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#architecture","title":"Architecture","text":"
    CCP runs as 4 Docker containers alongside (but independent from) your CML instances:
     
    \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502   CCP Admin GUI (5100)   \u2502  React + Vite + Ant Design\n\u2502   Dark theme, SPA        \u2502  Zustand auth store\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n             \u2502\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25bc\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502   CCP API (5000)         \u2502  Express + TypeScript\n\u2502   JWT auth, RBAC         \u2502  Prisma ORM \u2192 PostgreSQL\n\u2502   Docker socket access   \u2502  Winston logger\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n             \u2502\n    \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n    \u25bc        \u25bc        \u25bc\nccp-postgres ccp-redis  Docker Socket\n(port 5480)  (port 6399)\n
     Service Container Port Description CCP API ccp-api 5000 Express API with Docker CLI access CCP Admin ccp-admin 5100 React admin GUI CCP PostgreSQL ccp-postgres 5480 CCP metadata database CCP Redis ccp-redis 6399 Rate limiting, caching 
    Each managed CML instance gets its own isolated set of containers and PostgreSQL database, with ports allocated from non-overlapping ranges.
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#setup","title":"Setup","text":"","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#1-run-the-setup-script","title":"1. Run the Setup Script","text":"
    cd changemaker-control-panel\nchmod +x setup.sh\n./setup.sh\n
     
    The setup script:
     
       
    • Detects the installation directory and resolves absolute paths
      •  
    • Creates instances/ and backups/ directories
      •  
    • Copies .env.example to .env if not present
      •  
    • Sets INSTANCES_BASE_PATH, BACKUP_STORAGE_PATH, and CML_SOURCE_PATH
      •  
    • Generates random secrets for any placeholder values
      •  
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#2-review-environment","title":"2. Review Environment","text":"
    Edit .env and verify the key settings:
     Variable Default Description JWT_ACCESS_SECRET Auto-generated JWT signing key JWT_REFRESH_SECRET Auto-generated Refresh token signing key ENCRYPTION_KEY Auto-generated AES-256 key for instance secrets at rest INITIAL_ADMIN_EMAIL admin@example.com Bootstrap admin email INITIAL_ADMIN_PASSWORD ChangeMe2025!! Bootstrap admin password INSTANCES_BASE_PATH ./instances Where instance directories are created CML_SOURCE_PATH Auto-detected Path to CML source repo for provisioning BACKUP_STORAGE_PATH ./backups Backup archive storage PANGOLIN_API_URL \u2014 Pangolin API for tunnel management PANGOLIN_API_KEY \u2014 Pangolin authentication PANGOLIN_ORG_ID \u2014 Pangolin organization","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#3-start-ccp","title":"3. Start CCP","text":"
    docker compose up -d\n\n# Run database migrations and seed the admin user\ndocker compose exec ccp-api npx prisma migrate deploy\ndocker compose exec ccp-api npx prisma db seed\n
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#4-log-in","title":"4. Log In","text":"
    Open http://localhost:5100 and sign in with the admin credentials from .env.
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#creating-an-instance","title":"Creating an Instance","text":"
    The Create Instance wizard walks through 5 steps:
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#step-1-basic-information","title":"Step 1: Basic Information","text":"
       
    • Instance name \u2014 human-readable label (e.g., \"Edmonton Chapter\")
      •  
    • Slug \u2014 URL-safe identifier (e.g., edmonton), used for directory names and compose project
      •  
    • Domain \u2014 the domain this instance will serve (e.g., edmonton.example.org)
      •  
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#step-2-features","title":"Step 2: Features","text":"
    Toggle which platform features to enable for this instance:
     
       
    • Media Manager
      •  
    • Listmonk newsletter sync
      •  
    • Payments
      •  
    • Rocket.Chat
      •  
    • Gancio events
      •  
    • Jitsi Meet
      •  
    • SMS Campaigns
      •  
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#step-3-email","title":"Step 3: Email","text":"
    Configure SMTP for the instance, or use MailHog for testing.
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#step-4-tunnel","title":"Step 4: Tunnel","text":"
    Optionally configure Pangolin tunnel credentials for public access.
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#step-5-review","title":"Step 5: Review","text":"
    Review all settings, then click Create to start provisioning.
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#provisioning-flow","title":"Provisioning Flow","text":"
    When you create an instance, CCP runs a 13-step async provisioning process:
     Step What Happens 1 Validate uniqueness (slug + domain) 2 Allocate 4 ports from ranges 3 Generate 14 secrets (passwords, JWT keys, encryption keys) 4 Create Instance record (status: PROVISIONING) 5 Create instance directory 6 Copy CML source code (rsync, excluding node_modules/.git/.env) 7 Decrypt secrets and build template context 8 Render 7 config files from Handlebars templates (docker-compose.yml, .env, nginx configs, Pangolin, Prometheus) 9 Copy static files (nginx.conf) 10 docker compose pull (non-fatal if images are cached) 11 docker compose build 12 Start infrastructure (PostgreSQL + Redis), wait for healthy 13 Start API (runs migrations + seed), then start all remaining services 
    The admin GUI polls every 3 seconds during provisioning to show progress. When complete, the instance status changes to RUNNING.
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#port-allocation","title":"Port Allocation","text":"
    CCP allocates ports from 4 non-overlapping ranges to prevent conflicts between instances:
     Range Start End Purpose API 14000 14999 Express API server Admin 13000 13999 React admin GUI PostgreSQL 15400 15499 Database Nginx 10000 10999 Reverse proxy 
    Each new instance receives one port from each range. Ports are tracked in the database and released when instances are deleted.
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#pages-overview","title":"Pages Overview","text":"","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#dashboard","title":"Dashboard","text":"
    At-a-glance fleet status:
     
       
    • Total instances, running, healthy, degraded, stopped, error counts
      •  
    • Instance cards with status indicators and quick actions
      •  
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#instance-list","title":"Instance List","text":"
    Searchable, filterable table of all instances with status, domain, health, and creation date.
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#instance-detail","title":"Instance Detail","text":"
    5-tab view for each instance:
     Tab Content Overview Status, domain, ports, features, health summary Services Per-container status grid with restart and log-view actions Logs Real-time log viewer with service filter, tail count, and time range Backups Backup list with create, download, and delete actions Tunnel Pangolin tunnel status and configuration","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#backups","title":"Backups","text":"
    Cross-instance backup management:
     
       
    • All backups in one table with instance filter
      •  
    • Stats: total count, total size, last backup time
      •  
    • \"Backup All Running\" bulk action
      •  
    • Download and delete individual archives
      •  
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#audit-log","title":"Audit Log","text":"
    Filterable activity trail with 18 action types:
     
       
    • Instance lifecycle: CREATE, UPDATE, DELETE, START, STOP, RESTART, UPGRADE
      •  
    • Backups: CREATE, DELETE
      •  
    • Tunnel: PANGOLIN_SETUP, PANGOLIN_SYNC
      •  
    • Users: LOGIN, CREATE, UPDATE, DELETE
      •  
    • Settings: UPDATE
      •  
     
    Each entry includes timestamp, user, action, instance, IP address, and details (expandable JSON).
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#settings","title":"Settings","text":"
    CCP-level configuration:
     
       
    • Port ranges
      •  
    • Pangolin credentials
      •  
    • Default feature flags for new instances
      •  
    • Health check interval
      •  
    • Backup retention period
      •  
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#roles","title":"Roles","text":"Role Capabilities SUPER_ADMIN Full access: create/delete instances, manage users, view secrets, delete backups OPERATOR Manage instances: create, start/stop/restart, backups, health checks VIEWER Read-only: view instances, logs, health, backups, audit log","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#security","title":"Security","text":"
       
    • JWT authentication with 15-minute access tokens and 7-day refresh tokens (atomic rotation)
      •  
    • AES-256-GCM encryption for instance secrets stored in the database
      •  
    • Audit logging on all operations with IP address capture
      •  
    • Role-based access control on all API endpoints
      •  
    • Docker socket access restricted to the CCP API container only
      •  
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#next-steps","title":"Next Steps","text":"
       
    • Services Overview \u2014 learn about the services CCP provisions for each instance
      •  
    • Updates & Upgrades \u2014 upgrading CML instances
      •  
    • Deployment \u2014 production setup with tunneling and SSL
      •  
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/environment-variables/","title":"Environment Variables","text":"
    Changemaker Lite uses a single .env file at the project root to configure all services. Copy the example file to get started:
     
    cp .env.example .env\n
     
    Security Essentials
     
       
    • Change every REQUIRED_STRONG_PASSWORD_CHANGE_THIS value before starting services
      •  
    • Generate secrets with openssl rand -hex 32 (or -hex 16 where noted)
      •  
    • Never commit .env to version control
      •  
    • Use unique values for each secret \u2014 do not reuse JWT secrets as encryption keys
      •  
    ","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#quick-reference","title":"Quick Reference","text":"
    Variables are grouped by service. Each table marks whether a variable is required for a basic deployment or optional (has a sensible default or only needed for specific features).
     Symbol Meaning Must be set before first run Has a working default; change for production Feature flag \u2014 opt-in","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#general","title":"General","text":"Variable Default Description NODE_ENV development Set to production for production deployments. Controls logging, error detail, and security checks. DOMAIN cmlite.org Root domain. Used for nginx subdomain routing (app.DOMAIN, api.DOMAIN, etc.). The root domain serves the MkDocs documentation site; all application routes live under app.DOMAIN. USER_ID 1000 UID for container file ownership. Match your host user's UID (id -u). GROUP_ID 1000 GID for container file ownership. Match your host user's GID (id -g). DOCKER_GROUP_ID 984 GID of the docker group on the host. Needed for containers that access the Docker socket. Find with getent group docker.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#postgresql-main-database","title":"PostgreSQL (Main Database)","text":"
    The primary database for both the Express API and the Fastify Media API (shared).
     Variable Default Description V2_POSTGRES_USER changemaker Database username. V2_POSTGRES_PASSWORD \u2014 Must change. Database password. V2_POSTGRES_DB changemaker_v2 Database name. V2_POSTGRES_PORT 5433 Host port mapping. The container listens on 5432 internally. 
    Connection string
     
    The DATABASE_URL is constructed automatically inside Docker. If running locally, set: 
    DATABASE_URL=postgresql://changemaker:YOUR_PASSWORD@localhost:5433/changemaker_v2\n
    ","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#jwt-authentication","title":"JWT Authentication","text":"Variable Default Description JWT_ACCESS_SECRET \u2014  Secret for signing access tokens. Generate with openssl rand -hex 32. JWT_REFRESH_SECRET \u2014  Secret for signing refresh tokens. Must differ from the access secret. JWT_ACCESS_EXPIRY 15m Access token lifetime. Short-lived by design. JWT_REFRESH_EXPIRY 7d Refresh token lifetime. Tokens are rotated atomically on each refresh.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#encryption-key","title":"Encryption Key","text":"Variable Default Description ENCRYPTION_KEY \u2014  AES key for encrypting secrets stored in the database (SMTP passwords, API keys, etc.). Generate with openssl rand -hex 32. Must not reuse a JWT secret. Required in production (NODE_ENV=production).","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#initial-admin-account","title":"Initial Admin Account","text":"
    These credentials create the first super-admin user during database seeding (npx prisma db seed).
     Variable Default Description INITIAL_ADMIN_EMAIL admin@cmlite.org Email address for the initial admin. INITIAL_ADMIN_PASSWORD \u2014 Must change. Must be 12+ characters with uppercase, lowercase, and a digit. Change this password after first login.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#api-server","title":"API Server","text":"Variable Default Description API_PORT 4000 Host port for the Express API. API_URL http://localhost:4000 Public URL of the API. Used for generating links in emails and QR codes. CORS_ORIGINS http://localhost:3000,http://localhost Comma-separated list of allowed CORS origins. Add your production domain (e.g., https://app.yourdomain.org) for production. 
    Production CORS
     
    If you deploy behind a tunnel (Pangolin, Cloudflare) and API requests fail with CORS errors, add your production app. subdomain here: 
    CORS_ORIGINS=https://app.betteredmonton.org,http://localhost:3000,http://localhost\n
     Then restart the API: docker compose restart api
    ","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#admin-gui","title":"Admin GUI","text":"Variable Default Description ADMIN_PORT 3000 Host port for the React admin dashboard. ADMIN_URL http://localhost:3000 Public URL of the admin GUI.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#nginx-reverse-proxy","title":"Nginx Reverse Proxy","text":"Variable Default Description NGINX_HTTP_PORT 80 HTTP port. All subdomains route through nginx. NGINX_HTTPS_PORT 443 HTTPS port. SSL is typically handled by the tunnel provider (Pangolin/Cloudflare).","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#redis","title":"Redis","text":"
    Shared by rate limiting, BullMQ job queues, geocoding cache, and session data.
     Variable Default Description REDIS_PASSWORD \u2014 Must change. Redis requires authentication. REDIS_URL redis://:${REDIS_PASSWORD}@redis-changemaker:6379 Full connection URL. Uses the password variable automatically.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#payments-stripe","title":"Payments (Stripe)","text":"Variable Default Description ENABLE_PAYMENTS false  Set to true to enable the payments feature (memberships, products, donations). Stripe API keys are stored encrypted in the database via the admin settings page.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#email-smtp","title":"Email / SMTP","text":"Variable Default Description SMTP_HOST mailhog-changemaker SMTP server. Default points to the MailHog dev container. SMTP_PORT 1025 SMTP port. 1025 for MailHog, 587 for most production SMTP. SMTP_USER (empty) SMTP username. Not needed for MailHog. SMTP_PASS (empty) SMTP password. SMTP_FROM noreply@cmlite.org \"From\" address on outgoing emails. SMTP_FROM_NAME Changemaker Lite Display name for the \"From\" header. EMAIL_TEST_MODE true When true, all emails go to MailHog instead of real SMTP. Set to false in production. TEST_EMAIL_RECIPIENT admin@cmlite.org Catch-all recipient when test mode is on. 
    Development email
     
    With EMAIL_TEST_MODE=true, all outgoing email is captured in MailHog at http://localhost:8025. No real emails are sent.
    ","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#listmonk-newsletters","title":"Listmonk (Newsletters)","text":"
    Listmonk handles newsletter/marketing campaigns. Sync with the main platform is opt-in.
     Variable Default Description LISTMONK_PORT 9001 Listmonk web UI port. LISTMONK_DB_PORT 5434 Listmonk's own PostgreSQL port (separate from the main DB). Uses 5434 to avoid conflict with the main PostgreSQL (5432 internal / 5433 host). LISTMONK_DB_USER listmonk Listmonk database user. LISTMONK_DB_PASSWORD \u2014  Listmonk database password. LISTMONK_DB_NAME listmonk Listmonk database name. LISTMONK_WEB_ADMIN_USER admin Login for the Listmonk web dashboard. LISTMONK_WEB_ADMIN_PASSWORD \u2014  Password for the Listmonk web dashboard. LISTMONK_API_USER v2-api API user for programmatic access (auto-created by init container). LISTMONK_API_TOKEN \u2014 Token for API user. Generate with openssl rand -hex 16. LISTMONK_ADMIN_USER v2-api Same as LISTMONK_API_USER (used by the sync service). LISTMONK_ADMIN_PASSWORD \u2014 Same as LISTMONK_API_TOKEN. LISTMONK_SYNC_ENABLED false  Set to true to sync participants/locations/users to Listmonk lists. LISTMONK_WEBHOOK_SECRET (empty) Shared secret for Listmonk webhook callbacks. LISTMONK_PROXY_PORT 9002 Nginx proxy port for Listmonk. Listmonk SMTP settings 
    Listmonk has its own SMTP configuration, separate from the main platform's:
     Variable Default Description LISTMONK_SMTP_HOST mailhog-changemaker SMTP host for Listmonk. LISTMONK_SMTP_PORT 1025 SMTP port. LISTMONK_SMTP_USER (empty) SMTP username. LISTMONK_SMTP_PASSWORD (empty) SMTP password. LISTMONK_SMTP_TLS_TYPE none TLS mode: none, STARTTLS, or TLS. LISTMONK_SMTP_FROM Changemaker Lite <noreply@cmlite.org> From address for newsletters.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#represent-api-canadian-electoral-data","title":"Represent API (Canadian Electoral Data)","text":"Variable Default Description REPRESENT_API_URL https://represent.opennorth.ca OpenNorth Represent API endpoint. Used for postal code \u2192 representative lookups. No API key required.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#nocodb-data-browser","title":"NocoDB (Data Browser)","text":"
    Read-only database browser. Useful for inspecting data without SQL.
     Variable Default Description NOCODB_V2_PORT / NOCODB_PORT 8091 Host port for the NocoDB web UI. NOCODB_URL http://changemaker-v2-nocodb:8080 Internal Docker URL. NC_ADMIN_EMAIL admin@cmlite.org NocoDB admin email. NC_ADMIN_PASSWORD \u2014  NocoDB admin password.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#media-manager","title":"Media Manager","text":"
    Video library with upload, analytics, scheduling, and a public gallery.
     Variable Default Description ENABLE_MEDIA_FEATURES false  Set to true to enable the media system. MEDIA_API_PORT 4100 Fastify media API port. MEDIA_API_PUBLIC_URL http://media-api:4100 Internal URL for the media API container. MEDIA_ROOT /media/library Path to the video library inside the container. MEDIA_UPLOADS /media/uploads Path for upload processing. MAX_UPLOAD_SIZE_GB 10 Maximum single-file upload size in gigabytes. PUBLIC_MEDIA_PORT 3100 Public media gallery server port. VIDEO_PLAYER_DEBUG false Enable verbose video player logging. Analytics & scheduling settings Variable Default Description VIDEO_ANALYTICS_RETENTION_DAYS 90 Days to retain analytics data. GDPR-compliant with IP hashing. VIDEO_ANALYTICS_IP_HASHING_ENABLED true Hash viewer IPs for privacy. VIDEO_SCHEDULE_DEFAULT_TIMEZONE UTC Default timezone for scheduled publishing. VIDEO_SCHEDULE_NOTIFICATION_ENABLED true Notify on scheduled publish/unpublish. VIDEO_PREVIEW_LINK_EXPIRY_HOURS 24 Preview link JWT expiry (hours).","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#gitea-git-hosting","title":"Gitea (Git Hosting)","text":"
    Self-hosted Git repository. Optional service.
     Variable Default Description GITEA_URL http://gitea-changemaker:3000 Internal container URL for Gitea. GITEA_PORT / GITEA_WEB_PORT 3030 Gitea web UI port. GITEA_SSH_PORT 2222 Gitea SSH port for git operations. GITEA_DB_TYPE mysql Database type (Gitea uses its own MySQL). GITEA_DB_HOST gitea-db:3306 Internal database host. GITEA_DB_NAME gitea Database name. GITEA_DB_USER gitea Database user. GITEA_DB_PASSWD \u2014  Gitea database password. GITEA_DB_ROOT_PASSWORD \u2014  MySQL root password for Gitea. GITEA_ROOT_URL https://git.cmlite.org Public-facing URL for Gitea. GITEA_DOMAIN git.cmlite.org Domain used in git clone URLs. Gitea Docs Comments 
    Enable comments on MkDocs documentation pages, backed by Gitea Issues.
     Variable Default Description GITEA_COMMENTS_ENABLED false  Enable comments on MkDocs pages. GITEA_API_TOKEN (empty) Personal access token with repo write scope. Create in Gitea \u2192 Settings \u2192 Applications. GITEA_COMMENTS_REPO_OWNER (empty) Gitea username that owns the docs-comments repo. GITEA_COMMENTS_REPO_NAME docs-comments Repository name (auto-created via admin setup). GITEA_OAUTH_CLIENT_ID (empty) OAuth2 application client ID (create in Gitea \u2192 Settings \u2192 Applications \u2192 OAuth2). GITEA_OAUTH_CLIENT_SECRET (empty) OAuth2 application client secret.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#n8n-workflow-automation","title":"n8n (Workflow Automation)","text":"Variable Default Description N8N_PORT 5678 n8n web UI port. N8N_HOST n8n.cmlite.org Public hostname for n8n. N8N_ENCRYPTION_KEY \u2014  Encryption key for n8n credentials storage. N8N_USER_EMAIL admin@example.com Initial n8n admin email. N8N_USER_PASSWORD \u2014  Initial n8n admin password. GENERIC_TIMEZONE UTC Timezone for n8n cron triggers.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#mkdocs-documentation","title":"MkDocs (Documentation)","text":"Variable Default Description MKDOCS_PORT 4003 MkDocs dev server port (live preview). MKDOCS_SITE_SERVER_PORT 4004 MkDocs static site server port. BASE_DOMAIN https://cmlite.org Base URL for generated documentation links. MKDOCS_PREVIEW_URL http://mkdocs:8000 Internal container URL. MKDOCS_DOCS_PATH /mkdocs/docs Documentation source directory inside the container.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#code-server-web-ide","title":"Code Server (Web IDE)","text":"Variable Default Description CODE_SERVER_PORT 8888 Code Server web UI port. CODE_SERVER_URL http://code-server:8080 Internal container URL. USER_NAME coder User account inside the Code Server container.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#homepage-service-dashboard","title":"Homepage (Service Dashboard)","text":"Variable Default Description HOMEPAGE_PORT 3010 Homepage web UI port. HOMEPAGE_EMBED_PORT 8887 Port for iframe embedding in admin. HOMEPAGE_VAR_BASE_URL http://localhost Base URL used in Homepage service links.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#mini-qr-qr-code-generator","title":"Mini QR (QR Code Generator)","text":"Variable Default Description MINI_QR_PORT 8089 Mini QR direct access port. MINI_QR_URL http://mini-qr:8080 Internal container URL. MINI_QR_EMBED_PORT 8885 Port for iframe embedding (walk sheets, cut exports).","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#excalidraw-whiteboard","title":"Excalidraw (Whiteboard)","text":"Variable Default Description EXCALIDRAW_PORT 8090 Excalidraw web UI port. EXCALIDRAW_URL http://excalidraw-changemaker:80 Internal container URL. EXCALIDRAW_EMBED_PORT 8886 Port for iframe embedding. EXCALIDRAW_WS_URL wss://draw.cmlite.org WebSocket URL for real-time collaboration.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#vaultwarden-password-manager","title":"Vaultwarden (Password Manager)","text":"
    Self-hosted Bitwarden-compatible password manager. Optional service.
     Variable Default Description VAULTWARDEN_PORT 8445 Vaultwarden web UI port. VAULTWARDEN_URL http://vaultwarden-changemaker:80 Internal container URL. VAULTWARDEN_EMBED_PORT 8890 Port for iframe embedding in admin. VAULTWARDEN_ADMIN_TOKEN (empty) Admin panel token (access at /admin). Generate with openssl rand -hex 32. VAULTWARDEN_DOMAIN https://vault.cmlite.org Public-facing URL. Must use HTTPS \u2014 Bitwarden web vault enforces HTTPS for account creation. Set to your Pangolin tunnel URL. VAULTWARDEN_SIGNUPS_ALLOWED false Allow new user self-registration. Keep false and use admin panel invites. VAULTWARDEN_WEBSOCKET_ENABLED true Enable WebSocket notifications for real-time sync. VAULTWARDEN_SMTP_SECURITY off SMTP security mode: off for MailHog, starttls or force_tls for production. Uses the main SMTP_* variables for host/credentials. 
    Initial setup
     
    The vaultwarden-init container automatically invites the INITIAL_ADMIN_EMAIL user when starting. Check MailHog (or your SMTP) for the invitation email.
    ","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#rocketchat-team-chat","title":"Rocket.Chat (Team Chat)","text":"
    Self-hosted team chat for volunteer coordination. Requires MongoDB (auto-configured).
     Variable Default Description ENABLE_CHAT false  Set to true to enable the Rocket.Chat integration. The initial default; once saved in admin Settings, the DB value is authoritative. ROCKETCHAT_ADMIN_USER rcadmin Rocket.Chat admin username. ROCKETCHAT_ADMIN_PASSWORD \u2014  Rocket.Chat admin password. ROCKETCHAT_URL http://rocketchat-changemaker:3000 Internal container URL. ROCKETCHAT_EMBED_PORT 8891 Port for iframe embedding in admin.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#gancio-event-management","title":"Gancio (Event Management)","text":"
    Self-hosted event management platform. Uses the shared PostgreSQL database (auto-created by init-gancio-db.sh).
     Variable Default Description GANCIO_PORT 8092 Gancio web UI port. GANCIO_URL http://gancio-changemaker:13120 Internal container URL. GANCIO_EMBED_PORT 8892 Port for iframe embedding in admin. GANCIO_BASE_URL https://events.cmlite.org Public-facing URL for Gancio. Used in event links. GANCIO_ADMIN_USER admin Gancio admin username for shift-to-event sync (OAuth login). GANCIO_ADMIN_PASSWORD \u2014  Gancio admin password. GANCIO_SYNC_ENABLED false  Set to true to enable automatic shift \u2192 Gancio event synchronization.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#jitsi-meet-video-conferencing","title":"Jitsi Meet (Video Conferencing)","text":"
    Self-hosted video conferencing with JWT authentication. Integrates with Rocket.Chat for in-channel video calls.
     Variable Default Description ENABLE_MEET false  Set to true to enable the Jitsi Meet integration. The initial default; once saved in admin Settings, the DB value is authoritative. JITSI_APP_ID changemaker JWT application ID. Must match across Jitsi Prosody, Rocket.Chat app settings, and JWT_ACCEPTED_ISSUERS/JWT_ACCEPTED_AUDIENCES. JITSI_APP_SECRET \u2014  JWT secret for signing Jitsi tokens. Generate with openssl rand -hex 32. Shared between Jitsi Prosody, Rocket.Chat, and the API. JITSI_JICOFO_AUTH_PASSWORD \u2014 Internal XMPP password for Jicofo (conference focus). Generate with openssl rand -hex 16. JITSI_JVB_AUTH_PASSWORD \u2014 Internal XMPP password for JVB (video bridge). Generate with openssl rand -hex 16. JITSI_EMBED_PORT 8893 Port for iframe embedding in admin. JITSI_URL http://jitsi-web-changemaker:80 Internal container URL. JVB_ADVERTISE_IP (empty) Server's public IP address. Required in production for NAT traversal so remote participants can connect. JVB_PORT 10000 UDP port for media traffic. Must be open in your firewall. 
    Production requirements
     
       
    • JVB_ADVERTISE_IP must be set to your server's public IP for calls to work outside the local network.
      •  
    • Port 10000/udp must be open in your firewall for media traffic.
      •  
    • Calls must go through the production domain (not localhost) for SSL/JWT to work.
      •  
    ","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#sms-campaigns-termux-android-bridge","title":"SMS Campaigns (Termux Android Bridge)","text":"
    Send SMS messages via an Android phone running the Termux API server. The phone acts as an SMS gateway.
     Variable Default Description ENABLE_SMS false  Set to true to enable SMS campaigns. The initial default; once saved in admin Settings, the DB value is authoritative. TERMUX_API_URL http://10.0.0.193:5001 URL of the Termux API server running on the Android phone. TERMUX_API_KEY (empty) API key for authenticating with the Termux server (HMAC auth via X-API-Key header). SMS_DELAY_BETWEEN_MS 3000 Delay between sending individual SMS messages (ms). Prevents carrier throttling. SMS_MAX_RETRIES 3 Maximum retry attempts for failed SMS sends. SMS_RESPONSE_SYNC_INTERVAL_MS 30000 How often to poll the phone's inbox for responses (ms). SMS_DEVICE_MONITOR_INTERVAL_MS 30000 How often to check device health \u2014 battery, connectivity (ms). 
    GUI configuration
     
    The Termux API URL and API key can also be configured from Admin \u2192 Settings \u2192 SMS. Database values override these env vars when set.
    ","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#mailhog-development-email","title":"MailHog (Development Email)","text":"Variable Default Description MAILHOG_SMTP_PORT 1025 SMTP port for capturing emails. MAILHOG_WEB_PORT 8025 Web UI to view captured emails.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#nar-national-address-register","title":"NAR (National Address Register)","text":"
    Canadian address data import for geographic canvassing.
     Variable Default Description NAR_DATA_DIR /data Path to extracted NAR data inside the container. Expects YYYYMM/Addresses/ and YYYYMM/Locations/ subdirectories. Mount via ./data:/data:ro in Docker Compose. 
    Download NAR data from Statistics Canada.
    ","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#geocoding","title":"Geocoding","text":"
    Multi-provider geocoding for address resolution. Works out of the box with free providers; optional paid providers improve accuracy.
     Variable Default Description MAPBOX_API_KEY (empty) Mapbox API key for improved geocoding accuracy. Free tier: 100k requests/month. Sign up. GEOCODING_RATE_LIMIT_MS 1100 Delay between requests to free providers (ms). Respects rate limits. GEOCODING_CACHE_ENABLED true Enable Redis-backed geocoding cache. GEOCODING_CACHE_TTL_HOURS 24 Cache lifetime in hours. GOOGLE_MAPS_API_KEY (empty) Google Maps API key. Most accurate but $0.005/request after free tier. GOOGLE_MAPS_ENABLED false Enable Google Maps as a geocoding provider. GEOCODING_PARALLEL_ENABLED true Enable parallel geocoding for bulk imports (~10x speedup). GEOCODING_BATCH_SIZE 10 Number of concurrent geocoding requests during bulk operations. BULK_GEOCODE_ENABLED true Enable bulk re-geocoding from the admin UI. BULK_GEOCODE_MAX_BATCH 5000 Maximum locations per bulk geocoding run.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#overpass-area-import","title":"Overpass / Area Import","text":"
    OpenStreetMap data import for map enrichment.
     Variable Default Description OVERPASS_API_URL https://overpass-api.de/api/interpreter Overpass API endpoint. Use a private instance for heavy usage. OVERPASS_MIN_DELAY_MS 30000 Minimum delay between requests (ms). The public API requires 30 seconds. AREA_IMPORT_MAX_GRID_POINTS 500 Maximum reverse-geocode grid points per area import.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#pangolin-tunnel","title":"Pangolin Tunnel","text":"
    Expose services to the internet without port forwarding, using a self-hosted Pangolin instance.
     Variable Default Description PANGOLIN_API_URL https://api.bnkserve.org/v1 Pangolin server API endpoint. PANGOLIN_API_KEY (empty) API key for Pangolin management. PANGOLIN_ORG_ID (empty) Organization ID in Pangolin. PANGOLIN_SITE_ID (empty) Site ID (populated after setup via admin GUI). PANGOLIN_ENDPOINT https://pangolin.bnkserve.org Pangolin tunnel endpoint. PANGOLIN_NEWT_ID (empty) Newt client ID (populated after setup). PANGOLIN_NEWT_SECRET (empty) Newt client secret (populated after setup). 
    Setup flow
     
    Configure the tunnel from Admin \u2192 Settings \u2192 Pangolin. The setup wizard walks you through creating a site, copying credentials, and connecting the Newt container. See Deployment for the full guide.
    ","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#monitoring","title":"Monitoring","text":"
    These services are behind the monitoring Docker Compose profile. Start them with:
     
    docker compose --profile monitoring up -d\n
     Variable Default Description PROMETHEUS_PORT 9090 Prometheus web UI / query port. GRAFANA_PORT 3005 Grafana dashboard port. GRAFANA_ADMIN_PASSWORD admin  Change in production. GRAFANA_ROOT_URL http://localhost:3005 Public URL for Grafana (used in links). CADVISOR_PORT 8086 cAdvisor container metrics port. NODE_EXPORTER_PORT 9100 Prometheus node exporter port. REDIS_EXPORTER_PORT 9121 Redis metrics exporter port. ALERTMANAGER_PORT 9093 Alertmanager web UI port. GOTIFY_PORT 8889 Gotify push notification port. GOTIFY_ADMIN_USER admin Gotify admin username. GOTIFY_ADMIN_PASSWORD admin  Change in production. GRAFANA_EMBED_PORT 8894 Port for iframe embedding Grafana in admin. ALERTMANAGER_EMBED_PORT 8895 Port for iframe embedding Alertmanager in admin.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#bunker-ops-fleet-management","title":"Bunker Ops (Fleet Management)","text":"
    Remote metrics push for managing multiple Changemaker Lite instances from a central monitoring server.
     Variable Default Description INSTANCE_LABEL (empty) Unique label for this instance (used as a Prometheus metric label). Falls back to DOMAIN if empty. BUNKER_OPS_ENABLED false  Enable remote metrics push to a central VictoriaMetrics server. BUNKER_OPS_REMOTE_WRITE_URL (empty) VictoriaMetrics remote_write endpoint (e.g., https://ops.example.com/api/v1/write).","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#generating-secrets","title":"Generating Secrets","text":"
    Use these commands to generate all required secrets at once:
     
    # JWT secrets (two separate values)\necho \"JWT_ACCESS_SECRET=$(openssl rand -hex 32)\"\necho \"JWT_REFRESH_SECRET=$(openssl rand -hex 32)\"\n\n# Encryption key (must differ from JWT secrets)\necho \"ENCRYPTION_KEY=$(openssl rand -hex 32)\"\n\n# Database and Redis passwords\necho \"V2_POSTGRES_PASSWORD=$(openssl rand -hex 24)\"\necho \"REDIS_PASSWORD=$(openssl rand -hex 24)\"\n\n# Listmonk\necho \"LISTMONK_DB_PASSWORD=$(openssl rand -hex 24)\"\necho \"LISTMONK_WEB_ADMIN_PASSWORD=$(openssl rand -hex 16)\"\nLISTMONK_TOKEN=$(openssl rand -hex 16)\necho \"LISTMONK_API_TOKEN=$LISTMONK_TOKEN\"\necho \"LISTMONK_ADMIN_PASSWORD=$LISTMONK_TOKEN\"\n\n# Supporting services\necho \"GITEA_DB_PASSWD=$(openssl rand -hex 24)\"\necho \"GITEA_DB_ROOT_PASSWORD=$(openssl rand -hex 24)\"\necho \"N8N_ENCRYPTION_KEY=$(openssl rand -hex 32)\"\necho \"N8N_USER_PASSWORD=$(openssl rand -hex 16)\"\necho \"NC_ADMIN_PASSWORD=$(openssl rand -hex 16)\"\necho \"INITIAL_ADMIN_PASSWORD=$(openssl rand -base64 18)\"\n\n# Vaultwarden\necho \"VAULTWARDEN_ADMIN_TOKEN=$(openssl rand -hex 32)\"\n\n# Rocket.Chat\necho \"ROCKETCHAT_ADMIN_PASSWORD=$(openssl rand -hex 16)\"\n\n# Gancio\necho \"GANCIO_ADMIN_PASSWORD=$(openssl rand -hex 16)\"\n\n# Jitsi Meet\necho \"JITSI_APP_SECRET=$(openssl rand -hex 32)\"\necho \"JITSI_JICOFO_AUTH_PASSWORD=$(openssl rand -hex 16)\"\necho \"JITSI_JVB_AUTH_PASSWORD=$(openssl rand -hex 16)\"\n
     
    Tip
     
    Copy the output and paste the values into your .env file. The INITIAL_ADMIN_PASSWORD uses base64 encoding to ensure it contains uppercase, lowercase, and digits (meeting the password policy).
    ","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#minimal-vs-full-deployment","title":"Minimal vs Full Deployment","text":"Minimal (Core Only)Full Stack 
    For a basic deployment with campaigns, map, and admin:
     Required variables
    V2_POSTGRES_PASSWORD=...\nREDIS_PASSWORD=...\nJWT_ACCESS_SECRET=...\nJWT_REFRESH_SECRET=...\nENCRYPTION_KEY=...\nINITIAL_ADMIN_PASSWORD=...\n
     Start services
    docker compose up -d v2-postgres redis api admin\n
     
    For the complete platform including media, newsletters, monitoring, and all services:
     Additional variables needed
    # Everything above, plus:\nENABLE_MEDIA_FEATURES=true\nENABLE_PAYMENTS=true\nENABLE_CHAT=true\nENABLE_MEET=true\nENABLE_SMS=true\nLISTMONK_SYNC_ENABLED=true\nGANCIO_SYNC_ENABLED=true\nLISTMONK_DB_PASSWORD=...\nLISTMONK_WEB_ADMIN_PASSWORD=...\nLISTMONK_API_TOKEN=...\nNC_ADMIN_PASSWORD=...\nGITEA_DB_PASSWD=...\nGITEA_DB_ROOT_PASSWORD=...\nN8N_ENCRYPTION_KEY=...\nN8N_USER_PASSWORD=...\nVAULTWARDEN_ADMIN_TOKEN=...\nROCKETCHAT_ADMIN_PASSWORD=...\nGANCIO_ADMIN_PASSWORD=...\nJITSI_APP_SECRET=...\nJITSI_JICOFO_AUTH_PASSWORD=...\nJITSI_JVB_AUTH_PASSWORD=...\nJVB_ADVERTISE_IP=your.public.ip.here\nEMAIL_TEST_MODE=false\nSMTP_HOST=smtp.your-provider.com\nSMTP_PORT=587\nSMTP_USER=you@example.com\nSMTP_PASS=your-smtp-password\n
     Start services
    docker compose up -d\ndocker compose --profile monitoring up -d\n
    ","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/features/","title":"Features at a Glance","text":"
    Changemaker Lite bundles advocacy campaigns, geographic mapping, volunteer management, media hosting, and landing pages into a single self-hosted platform. Every feature can be toggled on or off from Settings in the admin panel.
    ","tags":["reference","getting-started"],"boost":2},{"location":"docs/getting-started/features/#core-features","title":"Core Features","text":"
       
    •  
       Advocacy Campaigns
       
      Help supporters contact elected representatives through email campaigns with postal code lookup and a public response wall.
       
       Campaign guide
       
      •  
    •  
       Map & Canvassing
       
      Manage locations, draw canvassing territories, schedule volunteer shifts, and run GPS-tracked door-to-door outreach.
       
       Map guide
       
      •  
    •  
       Media Manager
       
      Upload videos and photos, curate playlists, publish a shorts feed, and track engagement with built-in analytics.
       
       Media guide
       
      •  
    •  
       Landing Pages
       
      Build campaign microsites with a drag-and-drop GrapesJS visual editor and publish at custom slugs.
       
       Landing pages guide
       
      •  
    •  
       Payments (Stripe)
       
      Accept memberships, product sales, and donations with encrypted Stripe integration and branded donation pages.
       
       Payments guide
       
      •  
    •  
       SMS Campaigns
       
      Text message outreach via a Termux Android bridge with contact lists, templates, and response tracking.
       
       SMS guide
       
      •  
    •  
       Public Homepage
       
      Customizable landing page with hero section, live stats, featured campaigns, upcoming shifts, and activity feed.
       
       Homepage guide
       
      •  
    ","tags":["reference","getting-started"],"boost":2},{"location":"docs/getting-started/features/#communication-collaboration","title":"Communication & Collaboration","text":"
       
    •  
       Newsletter (Listmonk)
       
      Opt-in mailing lists and newsletter campaigns with automatic subscriber sync from shifts and contacts.
       
       Newsletter guide
       
      •  
    •  
       Email Templates
       
      Reusable email templates with variable substitution for campaign communications.
       
       Email templates guide
       
      •  
    •  
       Team Chat (Rocket.Chat)
       
      Self-hosted team chat with iframe integration, floating widget, and native mobile app support.
       
       Chat guide
       
      •  
    •  
       Video Conferencing (Jitsi)
       
      Self-hosted video calls integrated with Rocket.Chat via JWT authentication \u2014 no separate login required.
       
       Video conferencing guide
       
      •  
    ","tags":["reference","getting-started"],"boost":2},{"location":"docs/getting-started/features/#integrations-services","title":"Integrations & Services","text":"
       
    •  
       Events (Gancio)
       
      Self-hosted event management with automatic shift-to-event sync and an embeddable calendar widget.
       
       Events guide
       
      •  
    •  
       Password Manager (Vaultwarden)
       
      Bitwarden-compatible password vault for secure team credential sharing.
       
       Password manager guide
       
      •  
    •  
       User Provisioning
       
      Automatic account creation and sync across Rocket.Chat, Gitea, Vaultwarden, and Listmonk.
       
       User provisioning guide
       
      •  
    •  
       People / Contacts
       
      Centralized contact management for supporters, donors, and community members with cross-module linking.
       
       People guide
       
      •  
    •  
       Whiteboard (Excalidraw)
       
      Self-hosted collaborative whiteboard for brainstorming, planning, and visual collaboration.
       
       Whiteboard guide
       
      •  
    ","tags":["reference","getting-started"],"boost":2},{"location":"docs/getting-started/features/#volunteer-portal","title":"Volunteer Portal","text":"
       
    •  
       Social Connections
       
      Friend system, activity feed, groups, profiles, pokes, and privacy controls for volunteer community building.
       
       Social guide
       
      •  
    •  
       Achievements & Leaderboard
       
      Badge system with 11 achievements across 4 categories, progress tracking, and competitive leaderboards.
       
       Achievements guide
       
      •  
    •  
       Volunteer Quick Join
       
      QR code invite links for instant volunteer onboarding \u2014 scan, fill a short form, and start canvassing.
       
       Quick join guide
       
      •  
    ","tags":["reference","getting-started"],"boost":2},{"location":"docs/getting-started/features/#automation-analytics","title":"Automation & Analytics","text":"
       
    •  
       Email Automation
       
      Automated volunteer lifecycle emails \u2014 thank-you notes, shift reminders, weekly summaries, and re-engagement campaigns.
       
       Automation guide
       
      •  
    •  
       Data Quality Dashboard
       
      Geocoding quality metrics with per-provider stats, confidence tiers, and coverage analysis.
       
       Data quality guide
       
      •  
    •  
       Documentation Analytics
       
      Page view tracking and engagement metrics for MkDocs documentation pages.
       
       Docs analytics guide
       
      •  
    ","tags":["reference","getting-started"],"boost":2},{"location":"docs/getting-started/features/#admin-tools","title":"Admin Tools","text":"
       
    •  
       Docs Comments
       
      Gitea-backed comment system for documentation pages with anonymous posting and moderation.
       
       Docs comments guide
       
      •  
    •  
       Command Palette
       
      Global Ctrl+K search across pages, campaigns, locations, users, settings, and media.
       
       Command palette guide
       
      •  
    •  
       Navigation Settings
       
      Customize the public navigation menu with feature toggles, custom links, and drag-and-drop reordering.
       
       Navigation guide
       
      •  
    •  
       Platform Settings
       
      Five-tab settings page covering organization details, theme colors, email configuration, feature flags, and notifications.
       
       Settings guide
       
      •  
    •  
       Social Sharing (OG Tags)
       
      Open Graph meta tags for campaigns, landing pages, and gallery videos \u2014 rich link previews on social media.
       
       OG sharing guide
       
      •  
    •  
       Gallery Ads
       
      Internal ad system with 5 ad types, audience targeting, scheduling, frequency caps, and CTR analytics.
       
       Gallery ads guide
       
      •  
    •  
       Self-Service Contact Profile
       
      Token-based public profile pages where contacts can view and update their information and preferences.
       
       Contact profile guide
       
      •  
    ","tags":["reference","getting-started"],"boost":2},{"location":"docs/getting-started/first-steps/","title":"First Steps","text":"
    You've installed Changemaker Lite \u2014 here's what to do next.
    ","tags":["tutorial","getting-started","admin"],"boost":2},{"location":"docs/getting-started/first-steps/#1-log-in","title":"1. Log In","text":"
    Open the admin panel at http://localhost:3000 (or app.DOMAIN in production) and sign in with the admin email and password you configured during setup.
     
     
    Change your password
     
    If you used the wizard's generated password, change it immediately from Settings > Organization.
    ","tags":["tutorial","getting-started","admin"],"boost":2},{"location":"docs/getting-started/first-steps/#2-explore-the-dashboard","title":"2. Explore the Dashboard","text":"
    The dashboard gives you an at-a-glance view of platform activity. Initially it will be empty \u2014 that's normal.
     
    ","tags":["tutorial","getting-started","admin"],"boost":2},{"location":"docs/getting-started/first-steps/#3-configure-settings","title":"3. Configure Settings","text":"
    Visit Settings (/app/settings) to:
     
       
    • Set your organization name, logo, and tagline
      •  
    • Choose theme colors for admin and public interfaces
      •  
    • Enable feature modules (campaigns, map, media, payments, etc.)
      •  
    • Configure email delivery (MailHog for testing, production SMTP for live use)
      •  
    • Check the System tab to verify your installation and check for updates
      •  
     
    ","tags":["tutorial","getting-started","admin"],"boost":2},{"location":"docs/getting-started/first-steps/#4-create-your-first-campaign","title":"4. Create Your First Campaign","text":"
    Go to Campaigns (/app/campaigns) and click Create Campaign:
     
       
    1. Write a title and description
      2.  
    2. Compose the email template supporters will send
      3.  
    3. Select government levels to target
      4.  
    4. Publish \u2014 the campaign appears at /campaigns
      5.  
     
    ","tags":["tutorial","getting-started","admin"],"boost":2},{"location":"docs/getting-started/first-steps/#5-add-locations","title":"5. Add Locations","text":"
    Go to Locations (/app/map) and add addresses:
     
       
    • Click on the map to drop a marker
      •  
    • Import a CSV of addresses
      •  
    • Use the NAR (National Address Register) import for Canadian data
      •  
     
    ","tags":["tutorial","getting-started","admin"],"boost":2},{"location":"docs/getting-started/first-steps/#6-schedule-a-shift","title":"6. Schedule a Shift","text":"
    Go to Shifts (/app/map/shifts) and create your first volunteer shift:
     
       
    1. Set a date, time, and location description
      2.  
    2. Optionally link it to a canvassing area
      3.  
    3. Share the public shifts page (/shifts) with volunteers
      4.  
     
    ","tags":["tutorial","getting-started","admin"],"boost":2},{"location":"docs/getting-started/first-steps/#7-invite-volunteers","title":"7. Invite Volunteers","text":"
    Share the shifts page link or generate QR codes for in-person events. Volunteers sign up with just an email address.
    ","tags":["tutorial","getting-started","admin"],"boost":2},{"location":"docs/getting-started/first-steps/#next-steps","title":"Next Steps","text":"
       
    • Services Overview \u2014 complete catalog of all 30+ Docker services
      •  
    • Updates & Upgrades \u2014 keep your installation current
      •  
    • Features at a Glance \u2014 visual overview of every module
      •  
    • Admin Guide \u2014 full administration reference
      •  
    • Deployment \u2014 production setup with tunneling and SSL
      •  
    ","tags":["tutorial","getting-started","admin"],"boost":2},{"location":"docs/getting-started/installation/","title":"Installation","text":"
    Changemaker Lite runs as a set of Docker containers orchestrated by Docker Compose. The config.sh wizard handles all configuration \u2014 or you can set things up manually.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#prerequisites","title":"Prerequisites","text":"
       
    • Docker 24+ and Docker Compose v2
      •  
    • OpenSSL (for secret generation)
      •  
    • A Linux server (Ubuntu 22.04+ recommended) or macOS for development
      •  
    • At least 2 GB RAM for core services, 4 GB for the full stack
      •  
    • A domain name (optional for development, recommended for production)
      •  
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#quick-start","title":"Quick Start","text":"
    Clone the repository:
     
    git clone https://gitea.bnkops.com/admin/changemaker.lite\ncd changemaker.lite\ngit checkout v2\n
     
    Run the configuration wizard:
     
    bash config.sh\n
     
    Start all services:
     
    docker compose up -d\n
     
    Open http://localhost:3000 and sign in with the admin credentials you configured. Database migrations and seeding run automatically on first startup.
     
    Change your password
     
    If you used the wizard's generated password, change it immediately from the admin dashboard.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#pre-built-image-installation","title":"Pre-built Image Installation","text":"
    For production deployments, you can skip cloning the source repository entirely. Pre-built Docker images are pulled from the Gitea container registry.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#one-line-install","title":"One-Line Install","text":"
    curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/v2/scripts/install.sh | bash\n
     
    This script:
     
       
    1. Checks prerequisites (Docker, Docker Compose, OpenSSL)
      2.  
    2. Downloads the latest release package from Gitea
      3.  
    3. Extracts to ~/changemaker.lite/
      4.  
    4. Launches the configuration wizard (config.sh)
      5.  
     
    After the wizard completes, start everything with docker compose up -d.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#manual-download","title":"Manual Download","text":"
    If you prefer not to pipe to bash:
     
    # Download latest release\ncurl -LO https://gitea.bnkops.com/admin/changemaker.lite/releases/latest/download/changemaker-lite-latest.tar.gz\ntar xzf changemaker-lite-latest.tar.gz\ncd changemaker-lite\nbash config.sh\ndocker compose up -d\n
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#whats-different-from-source-install","title":"What's Different from Source Install","text":"Source Install Pre-built Install Download size ~200 MB (full repo) ~2 MB (config + scripts) First startup 10+ min (TypeScript compile + Docker build) ~2 min (image pull only) Requires Git, full repo Docker only Upgrades git pull + rebuild Download new release tarball Development Edit source, hot-reload Not for development 
    When to use which
     
    Use pre-built install for production deployments and quick evaluation. Use source install when you want to modify the platform code or contribute to development.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#configuration-wizard-configsh","title":"Configuration Wizard (config.sh)","text":"
    The wizard performs 14 steps to produce a fully configured .env file and prepare the system for startup. Each step is interactive with sensible defaults.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-1-prerequisites-check","title":"Step 1: Prerequisites Check","text":"
    Verifies that Docker, Docker Compose v2, and OpenSSL are installed. Exits immediately if any are missing, with links to installation guides.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-2-environment-file-setup","title":"Step 2: Environment File Setup","text":"
       
    • If no .env exists, copies .env.example as the starting point
      •  
    • If .env already exists, offers to back it up (timestamped copy) and create a fresh one, or update values in place
      •  
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-3-domain-configuration","title":"Step 3: Domain Configuration","text":"
    Prompts for your root domain (default: cmlite.org) and derives 14 environment variables from it:
     Variable Example Value DOMAIN example.org BASE_DOMAIN https://example.org GITEA_ROOT_URL https://git.example.org GITEA_DOMAIN git.example.org N8N_HOST n8n.example.org SMTP_FROM noreply@example.org INITIAL_ADMIN_EMAIL admin@example.org NC_ADMIN_EMAIL admin@example.org EXCALIDRAW_WS_URL wss://draw.example.org LISTMONK_SMTP_FROM Changemaker Lite <noreply@example.org> HOMEPAGE_VAR_BASE_URL https://example.org VAULTWARDEN_DOMAIN https://vault.example.org GANCIO_BASE_URL https://events.example.org TEST_EMAIL_RECIPIENT admin@example.org 
    Also updates mkdocs/mkdocs.yml with the new site_url and repo_url, and asks whether this is a production deployment (sets NODE_ENV=production).
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-4-admin-credentials","title":"Step 4: Admin Credentials","text":"
    Prompts for the initial super-admin email and password. The password is validated against the security policy:
     
       
    • Minimum 12 characters
      •  
    • At least one uppercase letter
      •  
    • At least one lowercase letter
      •  
    • At least one digit
      •  
    • Requires password confirmation
      •  
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-5-secret-generation","title":"Step 5: Secret Generation","text":"
    Auto-generates 21 unique secrets \u2014 no placeholder passwords remain after this step:
     Category Count Secrets JWT & Encryption 4 JWT_ACCESS_SECRET, JWT_REFRESH_SECRET, JWT_INVITE_SECRET (each 64-char hex), ENCRYPTION_KEY (64-char hex, must differ from JWT secrets) Database 2 V2_POSTGRES_PASSWORD, REDIS_PASSWORD (24-char alphanumeric) Listmonk 3 LISTMONK_DB_PASSWORD, LISTMONK_WEB_ADMIN_PASSWORD, LISTMONK_API_TOKEN NocoDB 1 NC_ADMIN_PASSWORD Gitea 2 GITEA_DB_PASSWD, GITEA_DB_ROOT_PASSWORD n8n 2 N8N_ENCRYPTION_KEY, N8N_USER_PASSWORD Monitoring 2 GRAFANA_ADMIN_PASSWORD, GOTIFY_ADMIN_PASSWORD Vaultwarden 1 VAULTWARDEN_ADMIN_TOKEN (64-char hex) Rocket.Chat 1 ROCKETCHAT_ADMIN_PASSWORD Gancio 1 GANCIO_ADMIN_PASSWORD Jitsi Meet 3 JITSI_APP_SECRET (64-char hex), JITSI_JICOFO_AUTH_PASSWORD, JITSI_JVB_AUTH_PASSWORD","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-6-email-configuration","title":"Step 6: Email Configuration","text":"
    Choose between:
     
       
    • MailHog (default) \u2014 captures all outgoing emails at http://localhost:8025 for development
      •  
    • Production SMTP \u2014 configures host, port, user, and password. Optionally shares credentials with Listmonk for newsletter delivery
      •  
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-7-feature-flags","title":"Step 7: Feature Flags","text":"
    Enable or disable 9 optional platform features:
     Flag Environment Variable What It Enables Media Manager ENABLE_MEDIA_FEATURES=true Video library, analytics, scheduled publishing Listmonk Sync LISTMONK_SYNC_ENABLED=true Newsletter subscriber sync from platform participants Payments ENABLE_PAYMENTS=true Stripe-based products, donations, and plans Rocket.Chat ENABLE_CHAT=true Team communication platform Gancio Events GANCIO_SYNC_ENABLED=true Shift-to-event sync with Gancio Jitsi Meet ENABLE_MEET=true Video conferencing (also prompts for server public IP) SMS Campaigns ENABLE_SMS=true Termux Android bridge for SMS (also prompts for API URL) Docs Comments GITEA_COMMENTS_ENABLED=true Gitea-backed page comments on documentation Bunker Ops BUNKER_OPS_ENABLED=true Fleet metrics push to central server (also prompts for remote write URL)","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-8-tunnel-configuration-pangolin","title":"Step 8: Tunnel Configuration (Pangolin)","text":"
    Optionally configures Pangolin tunnel credentials for secure public access:
     
       
    • PANGOLIN_API_URL \u2014 API endpoint (default: https://api.bnkserve.org/v1)
      •  
    • PANGOLIN_API_KEY \u2014 Authentication key
      •  
    • PANGOLIN_ORG_ID \u2014 Organization identifier
      •  
     
    Complete tunnel setup is done from the admin GUI at Settings > Tunnel after services are running.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-9-cors-origins","title":"Step 9: CORS Origins","text":"
    Automatically calculates allowed origins from your domain:
     
    http://app.DOMAIN,https://app.DOMAIN,http://DOMAIN,https://DOMAIN,http://localhost:3000,http://localhost,http://localhost:4003\n
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-10-nginx-config-generation","title":"Step 10: Nginx Config Generation","text":"
    Renders all .conf.template files in nginx/conf.d/ by substituting ${DOMAIN} with your configured domain. This produces the nginx configuration files that handle subdomain routing.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-11-homepage-services-yaml","title":"Step 11: Homepage Services YAML","text":"
    Generates configs/homepage/services.yaml with 27 service entries (both production and local development URLs) for the Homepage service dashboard.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-12-container-directory-permissions","title":"Step 12: Container Directory Permissions","text":"
    Creates and sets permissions (775) on 12 directories needed by containers:
     Directory Purpose configs/code-server/.config Code Server configuration configs/code-server/.local Code Server local data mkdocs/.cache MkDocs build cache mkdocs/site MkDocs built site output assets/uploads Listmonk uploads assets/images Shared images assets/icons Homepage icons media/local/inbox Media upload inbox media/local/thumbnails Video thumbnails media/public Public media files local-files n8n local files data NAR import data","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-13-upgrade-watcher-optional","title":"Step 13: Upgrade Watcher (Optional)","text":"
    Installs a systemd path watcher that enables the admin GUI's \"Check for Updates\" and \"Start Upgrade\" buttons. This step requires sudo and is optional \u2014 you can install it later or use the CLI upgrade script directly.
     
    The watcher installs two systemd units:
     
       
    • changemaker-upgrade.path \u2014 watches for data/upgrade/trigger.json
      •  
    • changemaker-upgrade.service \u2014 runs scripts/upgrade-watcher.sh when triggered
      •  
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-14-summary-next-steps","title":"Step 14: Summary & Next Steps","text":"
    Displays a configuration summary showing all choices made, then prints startup commands.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#what-gets-modified","title":"What Gets Modified","text":"
    After the wizard completes, the following files have been created or modified:
     File Action .env Created (or updated) with all configuration values mkdocs/mkdocs.yml Updated site_url and repo_url with domain nginx/conf.d/*.conf Generated from .conf.template files configs/homepage/services.yaml Generated with all service URLs 12 directories Created with container-friendly permissions systemd units (optional) Installed to /etc/systemd/system/","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#manual-setup-alternative","title":"Manual Setup (Alternative)","text":"
    If you prefer to configure by hand instead of using the wizard:
     
    cp .env.example .env\n
     
    At minimum, set these required secrets:
     
    # Generate cryptographic secrets\nV2_POSTGRES_PASSWORD=$(openssl rand -base64 48 | tr -dc 'a-zA-Z0-9' | head -c 24)\nREDIS_PASSWORD=$(openssl rand -base64 48 | tr -dc 'a-zA-Z0-9' | head -c 24)\nJWT_ACCESS_SECRET=$(openssl rand -hex 32)\nJWT_REFRESH_SECRET=$(openssl rand -hex 32)\nJWT_INVITE_SECRET=$(openssl rand -hex 32)\nENCRYPTION_KEY=$(openssl rand -hex 32)   # must differ from all JWT secrets\n
     
    Set your admin credentials (password must meet the 12+ char complexity requirement):
     
    INITIAL_ADMIN_EMAIL=admin@yourdomain.org\nINITIAL_ADMIN_PASSWORD=YourStrongPassword1\n
     
    Then configure optional sections:
     
       
    • Domain: Set DOMAIN and all derived variables (see Step 3 table above)
      •  
    • SMTP: Set SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, EMAIL_TEST_MODE=false
      •  
    • Feature flags: Enable features as needed (see Step 7 table above)
      •  
    • Tunnel: Set PANGOLIN_API_URL, PANGOLIN_API_KEY, PANGOLIN_ORG_ID
      •  
     
    See Environment Variables for every available option.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#full-stack-startup","title":"Full Stack Startup","text":"
    After configuration, start the entire platform:
     
    docker compose up -d\n
     
    That's it. Docker handles the startup order automatically:
     
       
    1. PostgreSQL and Redis start first (with healthchecks)
      2.  
    2. API waits for both to be healthy, then auto-runs database migrations and seeding
      3.  
    3. Admin GUI waits for the API
      4.  
    4. Nginx, media, communication, and all other services start in parallel
      5.  
    5. Init containers (nocodb-init, listmonk-init, etc.) run once and exit
      6.  
     
    Watch the startup progress:
     
    docker compose logs -f api --tail 20\n
     
    Once you see Starting server on port 4000, open http://localhost:3000 and log in.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#include-monitoring","title":"Include Monitoring","text":"
    The monitoring stack (Prometheus, Grafana, Alertmanager) uses a Docker Compose profile and isn't included by default:
     
    docker compose --profile monitoring up -d\n
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#start-only-core-services","title":"Start Only Core Services","text":"
    If you prefer a minimal startup (lower resource usage):
     
    docker compose up -d v2-postgres redis api admin nginx\n
     
    Manual migrations
     
    The API container runs migrations and seeding automatically on startup via its entrypoint script. You only need to run them manually if you're developing locally without Docker:
     
    cd api && npx prisma migrate deploy && npx prisma db seed\n
     
    See Services Overview for the complete service catalog.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#verifying-installation","title":"Verifying Installation","text":"
    After starting services, verify everything is healthy:
     
    # Check running containers\ndocker compose ps\n\n# API health check\ncurl -s http://localhost:4000/api/health | python3 -m json.tool\n\n# View API logs\ndocker compose logs api --tail 20\n\n# Check for containers in restart loops\ndocker compose ps | grep -i restarting\n
     
    You should see the API return {\"status\":\"ok\"} and all started containers in a \"running\" state.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#next-steps","title":"Next Steps","text":"
       
    • Services Overview \u2014 complete service catalog with ports and startup commands
      •  
    • Environment Variables \u2014 complete .env reference
      •  
    • First Steps \u2014 create your first campaign and add locations
      •  
    • Updates & Upgrades \u2014 keep your installation up to date
      •  
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/services/","title":"Services Overview","text":"
    Changemaker Lite runs as 30+ Docker containers orchestrated by Docker Compose. This page catalogs every service, organized by category.
     
    Quick reference
     
    Use docker compose ps to see which services are currently running, or docker compose ps -a to include stopped containers.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#core-required","title":"Core (Required)","text":"
    These services form the minimum viable platform. Start them first.
     Container Port Description changemaker-v2-api 4000 Express.js REST API (Prisma ORM) changemaker-v2-admin 3000 React admin GUI (Vite + Ant Design) changemaker-v2-postgres 5433 PostgreSQL 16 \u2014 primary database redis-changemaker 6379 Redis 7 \u2014 cache, rate limiting, job queues changemaker-v2-nginx 80 Nginx reverse proxy \u2014 subdomain routing 
    # Start core services only (minimal)\ndocker compose up -d v2-postgres redis api admin nginx\n\n# Or start everything at once\ndocker compose up -d\n
     
    The API container automatically runs database migrations and seeding on startup via its entrypoint script.
     
    Note
     
    Nginx is technically optional for local development (you can access services directly by port), but required for production subdomain routing.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#media","title":"Media","text":"Container Port Description Feature Flag changemaker-media-api 4100 Fastify media API \u2014 video library, analytics, scheduling ENABLE_MEDIA_FEATURES=true 
    docker compose up -d media-api\n
     
    The media API runs as a separate Fastify server sharing the same PostgreSQL database. It handles video upload (FFprobe metadata extraction), scheduled publishing via BullMQ, and GDPR-compliant view analytics.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#communication","title":"Communication","text":"","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#rocketchat-team-chat","title":"Rocket.Chat (Team Chat)","text":"Container Port Description Feature Flag rocketchat-changemaker 8891 Rocket.Chat server ENABLE_CHAT=true mongodb-changemaker \u2014 MongoDB (Rocket.Chat data store) \u2014 nats-changemaker \u2014 NATS (Rocket.Chat message bus) \u2014 
    docker compose up -d rocketchat mongodb nats\n
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#gancio-events","title":"Gancio (Events)","text":"Container Port Description Feature Flag gancio-changemaker 8092 Gancio event platform GANCIO_SYNC_ENABLED=true gancio-init \u2014 Init container \u2014 creates Gancio database \u2014 
    docker compose up -d gancio\n
     
    Init containers
     
    gancio-init runs once on first start to create the Gancio database in PostgreSQL, then exits. This is normal \u2014 don't worry about seeing it in a \"stopped\" state.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#jitsi-meet-video-conferencing","title":"Jitsi Meet (Video Conferencing)","text":"Container Port Description Feature Flag jitsi-web-changemaker 8893 Jitsi web interface ENABLE_MEET=true jitsi-prosody-changemaker \u2014 XMPP server (Prosody) \u2014 jitsi-jicofo-changemaker \u2014 Jitsi conference focus \u2014 jitsi-jvb-changemaker 10000/udp Jitsi video bridge \u2014 
    docker compose up -d jitsi-web jitsi-prosody jitsi-jicofo jitsi-jvb\n
     
    Firewall requirement
     
    Jitsi requires UDP port 10000 open in your firewall for video/audio media traffic. Set JVB_ADVERTISE_IP in .env to your server's public IP address.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#newsletter-email","title":"Newsletter & Email","text":"Container Port Description Feature Flag listmonk-app 9001 Listmonk newsletter platform LISTMONK_SYNC_ENABLED=true listmonk-db 5432 PostgreSQL (Listmonk's own database) \u2014 listmonk-init \u2014 Init container \u2014 creates API user \u2014 mailhog-changemaker 8025 MailHog email capture (development) EMAIL_TEST_MODE=true 
    # Newsletter platform\ndocker compose up -d listmonk-app\n\n# Email testing (captures all outgoing emails)\ndocker compose up -d mailhog\n
     
    Listmonk has its own PostgreSQL instance separate from the main database. The listmonk-init container auto-creates the API user for platform integration.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#developer-tools","title":"Developer Tools","text":"Container Port Description code-server-changemaker 8888 VS Code in the browser mkdocs-changemaker 4003 MkDocs live preview (hot reload) mkdocs-site-server-changemaker 4004 MkDocs static site server gitea-changemaker 3030 Gitea \u2014 self-hosted Git repository gitea-db \u2014 PostgreSQL (Gitea's database) changemaker-v2-nocodb 8091 NocoDB \u2014 read-only database browser nocodb-init \u2014 Init container \u2014 registers database n8n-changemaker 5678 n8n \u2014 workflow automation 
    # Start individual tools\ndocker compose up -d code-server\ndocker compose up -d mkdocs mkdocs-site-server\ndocker compose up -d gitea\ndocker compose up -d nocodb\ndocker compose up -d n8n\n
     
    Tip
     
    mkdocs (port 4003) provides live editing with hot reload for documentation authors. mkdocs-site-server (port 4004) serves the built static site for production visitors.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#utilities","title":"Utilities","text":"Container Port Description mini-qr 8089 QR code PNG generator excalidraw-changemaker 8090 Collaborative whiteboard vaultwarden-changemaker 8445 Vaultwarden \u2014 Bitwarden-compatible password manager vaultwarden-init \u2014 Init container \u2014 configures admin settings homepage-changemaker 3010 Homepage \u2014 service dashboard 
    docker compose up -d mini-qr excalidraw vaultwarden homepage\n
     
    Mini QR is used internally by walk sheets and cut export pages to generate printable QR codes.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#monitoring-docker-profile","title":"Monitoring (Docker Profile)","text":"
    Monitoring services are behind a Docker Compose profile and are not started by default.
     Container Port Description prometheus-changemaker 9090 Prometheus \u2014 metrics collection grafana-changemaker 3005 Grafana \u2014 monitoring dashboards alertmanager-changemaker 9093 Alertmanager \u2014 alert routing cadvisor-changemaker 8086 cAdvisor \u2014 container metrics node-exporter-changemaker 9100 Node Exporter \u2014 host system metrics redis-exporter-changemaker 9121 Redis Exporter \u2014 Redis metrics gotify-changemaker 8889 Gotify \u2014 push notifications 
    # Start the entire monitoring stack\ndocker compose --profile monitoring up -d\n
     
    The monitoring stack includes 3 pre-configured Grafana dashboards and 12 custom cm_* Prometheus metrics. See Monitoring for details.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#infrastructure","title":"Infrastructure","text":"Container Port Description newt \u2014 Pangolin tunnel connector (Newt) docker-socket-proxy \u2014 Docker socket proxy for secure container access 
    # Newt starts automatically if PANGOLIN_NEWT_ID and PANGOLIN_NEWT_SECRET are set\ndocker compose up -d newt\n
     
    The Newt container connects to a Pangolin tunnel server for secure public access without opening inbound ports. See Tunnel for setup.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#subdomain-routing","title":"Subdomain Routing","text":"
    When Nginx is running, services are accessible via subdomains. The root domain serves documentation only; all application routes are at app.DOMAIN.
     Subdomain Target Purpose app.DOMAIN Admin (3000) All application routes (admin, public pages, campaigns, map, shifts, media gallery) api.DOMAIN Express API (4000) REST API media.DOMAIN Fastify Media API (4100) Media API DOMAIN MkDocs Static (4004) Documentation / marketing site db.DOMAIN NocoDB (8091) Database browser docs.DOMAIN MkDocs Live (4003) Live documentation preview code.DOMAIN Code Server (8888) Web IDE n8n.DOMAIN n8n (5678) Workflow automation git.DOMAIN Gitea (3030) Git hosting home.DOMAIN Homepage (3010) Service dashboard grafana.DOMAIN Grafana (3005) Metrics visualization listmonk.DOMAIN Listmonk (9001) Newsletter platform qr.DOMAIN Mini QR (8089) QR code generator draw.DOMAIN Excalidraw (8090) Collaborative whiteboard vault.DOMAIN Vaultwarden (8445) Password manager events.DOMAIN Gancio (8092) Event platform chat.DOMAIN Rocket.Chat (8891) Team chat meet.DOMAIN Jitsi Meet (8893) Video conferencing mail.DOMAIN MailHog (8025) Email capture (dev)","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#init-containers","title":"Init Containers","text":"
    Several services use init containers \u2014 lightweight containers that run once on first startup to bootstrap databases or configuration, then exit with code 0. This pattern is borrowed from Kubernetes.
     Init Container Purpose listmonk-init Creates the Listmonk API user for platform integration gancio-init Creates the Gancio database in the shared PostgreSQL instance vaultwarden-init Configures Vaultwarden admin settings nocodb-init Registers the main database with NocoDB for browsing 
    Seeing these containers in a \"stopped\" or \"exited (0)\" state is completely normal.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#starting-everything","title":"Starting Everything","text":"
    To start all services at once (excluding monitoring):
     
    docker compose up -d\n
     
    To start everything including monitoring:
     
    docker compose up -d && docker compose --profile monitoring up -d\n
     
    To see what's running:
     
    docker compose ps\n
     
    Warning
     
    Starting all services at once requires at least 4 GB RAM. For resource-constrained environments, start only the services you need.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#next-steps","title":"Next Steps","text":"
       
    • Installation \u2014 setup walkthrough and configuration wizard details
      •  
    • Environment Variables \u2014 complete .env reference
      •  
    • First Steps \u2014 create your first campaign and volunteer shift
      •  
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/upgrades/","title":"Updates & Upgrades","text":"
    Changemaker Lite includes a built-in upgrade system that pulls code updates, rebuilds containers, runs database migrations, and restarts services \u2014 all while preserving your customizations.
     
    There are two ways to upgrade:
     
       
    1. Admin GUI \u2014 Check for updates and run upgrades from Settings > System
      2.  
    2. CLI \u2014 Run ./scripts/upgrade.sh directly from the command line
      3.  
     
    Both methods execute the same 6-phase upgrade process.
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#prerequisites","title":"Prerequisites","text":"","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#upgrade-watcher-required-for-gui-method","title":"Upgrade Watcher (Required for GUI Method)","text":"
    The admin GUI triggers upgrades via a systemd path watcher that monitors for trigger files. This must be installed on the host system.
     
    Install during initial setup:
     
    The config.sh wizard offers to install the watcher automatically (Step 13). If you skipped it, install manually:
     
    # Edit the systemd units to set your project path and user\nsed -e \"s|__PROJECT_DIR__|$(pwd)|g\" scripts/systemd/changemaker-upgrade.path > /tmp/changemaker-upgrade.path\nsed -e \"s|__PROJECT_DIR__|$(pwd)|g\" -e \"s|__USER__|$(whoami)|g\" scripts/systemd/changemaker-upgrade.service > /tmp/changemaker-upgrade.service\n\n# Install and enable\nsudo cp /tmp/changemaker-upgrade.path /tmp/changemaker-upgrade.service /etc/systemd/system/\nsudo systemctl daemon-reload\nsudo systemctl enable --now changemaker-upgrade.path\n
     
    Verify it's running:
     
    sudo systemctl status changemaker-upgrade.path\n
     
    How the watcher works
     
    The API container writes a trigger.json file to a shared data/upgrade/ volume. The systemd path watcher detects the file and runs scripts/upgrade-watcher.sh on the host, which dispatches to the appropriate script (check or upgrade). Progress and results are communicated back via JSON files that the API reads.
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#method-1-admin-gui","title":"Method 1: Admin GUI","text":"","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#checking-for-updates","title":"Checking for Updates","text":"
       
    1. Navigate to Settings (/app/settings)
      2.  
    2. Click the System tab
      3.  
    3. Click Check for Updates
      4.  
     
    The system fetches from the git remote and shows:
     
       
    • Current commit hash and message
      •  
    • Remote commit hash (if different)
      •  
    • Number of commits behind
      •  
    • Changelog of incoming changes
      •  
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#starting-an-upgrade","title":"Starting an Upgrade","text":"
       
    1. Review the changelog to understand what's changing
      2.  
    2. Click Start Upgrade
      3.  
    3. Optionally configure:
         
      • Skip backup \u2014 skip the database backup phase (not recommended)
        •  
      • Pull images \u2014 also update third-party Docker images (PostgreSQL, Redis, etc.)
        •  
      • Use registry images \u2014 pull pre-built images from Gitea instead of compiling from source (faster \u2014 requires scripts/build-and-push.sh to have been run first)
        •  
      • Dry run \u2014 preview what would happen without making changes
        •  
       
      4.  
    4. Monitor the 6-phase progress indicator
      5.  
     
    The GUI polls for progress updates and displays the current phase, percentage, and status message in real time.
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#the-6-upgrade-phases","title":"The 6 Upgrade Phases","text":"
    Both the GUI and CLI methods execute the same 6-phase process:
     Phase % Name What Happens 1 5% Pre-flight Checks Verifies Docker, git, disk space (2 GB minimum), remote reachability, and clean working directory 2 15% Backup Runs scripts/backup.sh (pg_dump + archive), backs up user-modifiable content, saves pre-upgrade commit hash 3 30% Code Update Saves user paths, stashes local changes, git pull, pops stash with auto-conflict resolution, detects new .env variables 4 50% Container Rebuild Rebuilds api, admin, media-api from source (default) or pulls pre-built images from the Gitea registry (--use-registry); conditionally rebuilds nginx and code-server if their configs changed; optionally pulls third-party images 5 70% Service Restart Stops app containers, force-recreates LSIO containers, verifies Gancio config, starts infrastructure, waits for PostgreSQL, starts API (runs migrations), starts everything else, restarts Newt tunnel and monitoring if they were running 6 90% Verification Health checks for API, Admin, Media API, Gancio, MkDocs; detects containers in restart loops","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#what-gets-preserved","title":"What Gets Preserved","text":"
    The upgrade script automatically preserves user-modifiable paths that you may have customized:
     Path What It Contains mkdocs/docs/ Your documentation content mkdocs/mkdocs.yml MkDocs configuration mkdocs/site/ Built documentation site configs/ Prometheus, Grafana, Alertmanager, Homepage configs nginx/conf.d/services.conf Custom nginx service proxies 
    These files are saved before git pull and unconditionally restored afterward, even if the pull introduces changes to them. Your versions always win.
     
    Tip
     
    The .env file is never touched by git pull (it's in .gitignore). However, if new environment variables are added in .env.example, the upgrade script automatically appends them to your .env with their default values and warns you to review them.
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#method-2-cli","title":"Method 2: CLI","text":"
    Run the upgrade script directly:
     
    ./scripts/upgrade.sh\n
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#options","title":"Options","text":"Flag Description --skip-backup Skip the backup phase (requires --force) --pull-services Also pull new third-party Docker images --use-registry Pull pre-built images from Gitea instead of compiling from source --dry-run Show what would happen without executing --force Continue past non-critical warnings --branch BRANCH Git branch to pull (default: current branch) --rollback Rollback to pre-upgrade commit --api-mode Write progress/result JSON for admin GUI (used internally)","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#examples","title":"Examples","text":"
    # Standard upgrade\n./scripts/upgrade.sh\n\n# Preview changes without executing\n./scripts/upgrade.sh --dry-run\n\n# Full upgrade including third-party image updates\n./scripts/upgrade.sh --pull-services\n\n# Upgrade using pre-built images from Gitea registry (faster, no TypeScript compile)\n./scripts/upgrade.sh --use-registry --force --skip-backup\n\n# Rollback to the last pre-upgrade state\n./scripts/upgrade.sh --rollback\n
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#registry-mode-fast-upgrades","title":"Registry Mode (Fast Upgrades)","text":"
    By default, the upgrade script compiles TypeScript from source (npm run build) and rebuilds Docker images on the deployment server. Registry mode skips this by pulling pre-built production images from the Gitea container registry \u2014 faster and requires no build tooling on the server.
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#how-it-works","title":"How It Works","text":"
       
    1. Run scripts/build-and-push.sh on a machine with Docker (usually your dev machine) to build and push production images tagged with the current commit SHA
      2.  
    2. During the next upgrade, pass --use-registry (CLI) or enable the checkbox (GUI)
      3.  
    3. The upgrade script pulls gitea.bnkops.com/admin/changemaker-{service}:{sha} instead of rebuilding from source
      4.  
    4. If a registry image is unavailable (e.g., the SHA wasn't pushed), it automatically falls back to a source build
      5.  
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#building-and-pushing-images","title":"Building and Pushing Images","text":"
    # Build and push all core services (api, admin, media-api, nginx)\n./scripts/build-and-push.sh\n\n# Skip code-server (9 GB \u2014 push only when Dockerfile changes)\n./scripts/build-and-push.sh --services api,admin,media-api,nginx\n\n# Build only, no push (verify locally first)\n./scripts/build-and-push.sh --no-push\n\n# Also mirror third-party images (postgres, redis, etc.) to Gitea\n./scripts/mirror-images.sh\n
     
    Registry prerequisites
     
       
    • Run docker login gitea.bnkops.com once per machine before pushing
      •  
    • Set GITEA_REGISTRY_USER and GITEA_REGISTRY_PASS in .env for the admin GUI's Registry status endpoint
      •  
    • gitea.bnkops.com must be reachable without proxies that limit upload size (Cloudflare free plan blocks blobs >100 MB)
      •  
     
    Release installs upgrade automatically via registry
     
    If you installed from a release tarball (not git clone), the upgrade script automatically uses registry mode. It downloads the latest release package from Gitea instead of running git pull. No additional configuration needed.
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#rollback","title":"Rollback","text":"","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#automatic-rollback","title":"Automatic Rollback","text":"
    If the upgrade fails at any phase, the script prints detailed rollback instructions including the pre-upgrade commit hash. Use the --rollback flag:
     
    ./scripts/upgrade.sh --rollback\n
     
    This:
     
       
    1. Finds the latest backup archive
      2.  
    2. Extracts the pre-upgrade commit hash from git-commit.txt inside the archive
      3.  
    3. Checks out that commit
      4.  
    4. Rebuilds and restarts all containers
      5.  
     
    Warning
     
    --rollback restores the code to the pre-upgrade state but does not automatically restore the database. If database migrations were applied during the failed upgrade, you may need to manually restore from the backup archive.
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#manual-rollback","title":"Manual Rollback","text":"
    # 1. Restore code\ncd /path/to/changemaker.lite\ngit checkout <pre-upgrade-commit-hash>\n\n# 2. Rebuild and restart\ndocker compose build api admin media-api\ndocker compose up -d\n\n# 3. Database restore (if needed \u2014 destructive!)\nls -lt backups/changemaker-v2-backup-*.tar.gz | head -5\ntar xzf backups/<backup>.tar.gz -C /tmp\ngunzip -c /tmp/<backup>/v2-postgres.sql.gz | \\\n  docker exec -i changemaker-v2-postgres psql -U changemaker -d changemaker_v2\n
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#new-environment-variables","title":"New Environment Variables","text":"
    When upstream code adds new environment variables to .env.example, the upgrade script automatically:
     
       
    1. Compares .env.example against your .env
      2.  
    2. Appends any missing variables with their default values
      3.  
    3. Warns you to review the new additions
      4.  
     
    [WARN] New env vars added to .env (review defaults):\n    NEW_FEATURE_FLAG\n    NEW_API_KEY\n
     
    Always review new variables after an upgrade \u2014 some may need manual configuration.
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#update-checker","title":"Update Checker","text":"
    A separate lightweight script checks for available updates without performing any changes:
     
    ./scripts/upgrade-check.sh\n
     
    This writes data/upgrade/status.json with:
     
       
    • Current and remote commit hashes
      •  
    • Number of commits behind
      •  
    • Changelog (last 30 commits)
      •  
    • Timestamp of last check
      •  
     
    The admin GUI reads this file to display update availability.
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#troubleshooting","title":"Troubleshooting","text":"","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#stale-progress-indicator","title":"Stale Progress Indicator","text":"
    If the GUI shows an upgrade \"in progress\" but nothing is happening, the upgrade script may have crashed. The system automatically detects stale progress (no update for 10+ minutes) and treats it as not running.
     
    To manually clear:
     
    rm -f data/upgrade/progress.json\n
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#merge-conflicts","title":"Merge Conflicts","text":"
    If git pull encounters merge conflicts in user-modifiable paths (docs, configs), the upgrade script auto-resolves by keeping your version. If conflicts occur in project-owned files (api/, admin/), the upgrade fails and asks you to resolve manually.
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#lock-file","title":"Lock File","text":"
    The upgrade script uses .upgrade.lock to prevent concurrent upgrades. If a previous upgrade crashed without cleaning up:
     
    # Verify no upgrade is actually running\nps aux | grep upgrade.sh\n\n# Remove stale lock\nrm -f .upgrade.lock\n
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#health-check-failures","title":"Health Check Failures","text":"
    If Phase 6 health checks fail, services may still be starting. Wait 1-2 minutes and check manually:
     
    # API health\ncurl -s http://localhost:4000/api/health\n\n# Container status\ndocker compose ps\n\n# Recent logs\ndocker compose logs api --tail 50\ndocker compose logs admin --tail 50\n
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#systemd-watcher-not-triggering","title":"Systemd Watcher Not Triggering","text":"
    # Check watcher status\nsudo systemctl status changemaker-upgrade.path\n\n# Check service logs\nsudo journalctl -u changemaker-upgrade.service --tail 20\n\n# Re-enable if stopped\nsudo systemctl enable --now changemaker-upgrade.path\n
    ","tags":["guide","operator","upgrades"]},{"location":"docs/services/","title":"Services","text":"
    Changemaker Lite orchestrates 20+ services via Docker Compose. This page is your map to every service: what it does, how to reach it, and where to find its upstream documentation.
    ","tags":["reference","operator","services","docker"]},{"location":"docs/services/#core-platform","title":"Core Platform","text":"
    The essential services that power the application.
     
       
    •  
       Express API
       
      Main V2 API server. Handles authentication, campaigns, map, shifts, pages, email, and all business logic. Prisma ORM with PostgreSQL.
       
      Port: 4000 \u00b7 Container: changemaker-v2-api
       
       API Reference
       
      •  
    •  
       Fastify Media API
       
      Video library server. Upload, metadata extraction (FFprobe), analytics, scheduled publishing, and public gallery. Shares the same PostgreSQL database.
       
      Port: 4100 \u00b7 Container: changemaker-media-api
       
       Media Guide
       
      •  
    •  
       Admin GUI
       
      React single-page application (Vite + Ant Design + Zustand). Serves the admin dashboard, public campaign pages, volunteer portal, and media gallery \u2014 all from one build.
       
      Port: 3000 \u00b7 Container: changemaker-v2-admin
       
       Feature Guides
       
      •  
    •  
       PostgreSQL 16
       
      Primary database shared by both APIs. Managed by Prisma migrations. Contains 30+ tables covering users, campaigns, locations, shifts, media, and more.
       
      Port: 5433 (host) / 5432 (container) \u00b7 Container: changemaker-v2-postgres
       
       PostgreSQL Docs
       
      •  
    •  
       Redis
       
      In-memory store for rate limiting, BullMQ job queues (email, video scheduling), geocoding cache, and session data. Requires authentication.
       
      Port: 6379 \u00b7 Container: redis-changemaker
       
       Redis Docs
       
      •  
    •  
       Nginx
       
      Reverse proxy handling all subdomain routing (app., api., media., docs., etc.). Includes security headers (HSTS, CSP, Permissions-Policy) and WebSocket support.
       
      Port: 80 / 443 \u00b7 Container: changemaker-v2-nginx
       
       Nginx Docs
       
      •  
    ","tags":["reference","operator","services","docker"]},{"location":"docs/services/#communication-email","title":"Communication & Email","text":"
       
    •  
       Listmonk
       
      Self-hosted newsletter and mailing list manager. Drop-in replacement for Mailchimp. Opt-in sync with the main platform imports participants, locations, and users as subscriber lists.
       
      Port: 9001 \u00b7 Container: listmonk-app \u00b7 Subdomain: listmonk.DOMAIN
       
       Listmonk Docs
       
      •  
    •  
       MailHog
       
      Email capture for development. All outgoing email is intercepted and displayed in a web UI when EMAIL_TEST_MODE=true. No real emails are sent.
       
      Port: 8025 (web) / 1025 (SMTP) \u00b7 Container: mailhog-changemaker \u00b7 Subdomain: mail.DOMAIN
       
       MailHog GitHub
       
      •  
    ","tags":["reference","operator","services","docker"]},{"location":"docs/services/#content-editing","title":"Content & Editing","text":"
       
    •  
       MkDocs
       
      Material-themed documentation site with full-text search, blog, social cards, and Jinja2 template overrides. Two containers: live preview (dev) and static site (production).
       
      Port: 4003 (dev) / 4004 (static) \u00b7 Container: mkdocs-changemaker \u00b7 Subdomain: docs.DOMAIN
       
       MkDocs Material
       
      •  
    •  
       Code Server
       
      Full VS Code in the browser. Edit configuration files, templates, and documentation from anywhere without SSH. Supports extensions.
       
      Port: 8888 \u00b7 Container: code-server-changemaker \u00b7 Subdomain: code.DOMAIN
       
       Code Server Docs
       
      •  
    ","tags":["reference","operator","services","docker"]},{"location":"docs/services/#data-automation","title":"Data & Automation","text":"
       
    •  
       NocoDB
       
      Airtable-alternative database browser. Provides a spreadsheet-like interface to browse, filter, sort, and export campaign data. Read-only access to the main database.
       
      Port: 8091 \u00b7 Container: changemaker-v2-nocodb \u00b7 Subdomain: db.DOMAIN
       
       NocoDB Docs
       
      •  
    •  
       n8n
       
      Visual workflow automation platform. Connect APIs, trigger actions on events, schedule tasks, and build custom integrations \u2014 all without code. 400+ built-in integrations.
       
      Port: 5678 \u00b7 Container: n8n-changemaker \u00b7 Subdomain: n8n.DOMAIN
       
       n8n Docs
       
      •  
    •  
       Gitea
       
      Self-hosted Git repository hosting. Version control for campaign code, configuration, templates, and documentation. Includes issues, pull requests, and CI/CD.
       
      Port: 3030 (web) / 2222 (SSH) \u00b7 Container: gitea-changemaker \u00b7 Subdomain: git.DOMAIN
       
       Gitea Docs
       
      •  
    ","tags":["reference","operator","services","docker"]},{"location":"docs/services/#utilities","title":"Utilities","text":"
       
    •  
       Mini QR
       
      Lightweight QR code generator. Produces PNG images for walk sheets, campaign materials, and event signage. Embedded in the admin dashboard via iframe.
       
      Port: 8089 \u00b7 Container: mini-qr \u00b7 Subdomain: qr.DOMAIN
       
      •  
    •  
       Homepage
       
      Service dashboard showing the status of all containers at a glance. Auto-generated services.yaml from config.sh provides both production and local links.
       
      Port: 3010 \u00b7 Container: homepage-changemaker \u00b7 Subdomain: home.DOMAIN
       
       Homepage Docs
       
      •  
    •  
       Excalidraw
       
      Collaborative whiteboard for brainstorming, diagramming, and visual planning. Real-time collaboration via WebSocket.
       
      Port: 8090 \u00b7 Container: excalidraw-changemaker \u00b7 Subdomain: draw.DOMAIN
       
       Excalidraw
       
      •  
    •  
       Vaultwarden
       
      Self-hosted Bitwarden-compatible password manager. Secure credential sharing for campaign teams. Requires HTTPS for account creation; local browsing works on HTTP.
       
      Port: 8445 \u00b7 Container: vaultwarden-changemaker \u00b7 Subdomain: vault.DOMAIN
       
       Vaultwarden Wiki
       
      •  
    ","tags":["reference","operator","services","docker"]},{"location":"docs/services/#team-communication","title":"Team Communication","text":"
       
    •  
       Rocket.Chat
       
      Self-hosted team chat for volunteer coordination. Supports channels, direct messaging, threads, and file sharing. Embeddable in the admin dashboard via iframe. Enable with ENABLE_CHAT=true.
       
      Port: 3000 (internal) \u00b7 Container: rocketchat-changemaker \u00b7 Subdomain: chat.DOMAIN
       
       Rocket.Chat Docs
       
      •  
    •  
       Jitsi Meet
       
      Self-hosted video conferencing with JWT authentication. Four containers (web, Prosody, Jicofo, JVB) provide the full video call stack. Integrated with Rocket.Chat for one-click calls from channels and DMs. Enable with ENABLE_MEET=true.
       
      Containers: jitsi-web, jitsi-prosody, jitsi-jicofo, jitsi-jvb \u00b7 Subdomain: meet.DOMAIN
       
       Setup Guide \u00b7  Jitsi Docs
       
      •  
    •  
       Gancio
       
      Self-hosted event management platform. Automatic shift-to-event sync (when GANCIO_SYNC_ENABLED=true) publishes shifts as public events. Uses the shared PostgreSQL database. Embeddable calendar widget available for MkDocs pages.
       
      Port: 8092 \u00b7 Container: gancio-changemaker \u00b7 Subdomain: events.DOMAIN
       
       Gancio Docs
       
      •  
    ","tags":["reference","operator","services","docker"]},{"location":"docs/services/#networking-tunneling","title":"Networking & Tunneling","text":"
       
    •  
       Pangolin + Newt
       
      Self-hosted tunnel server with the Newt client container. Exposes your services to the internet without port forwarding. Handles SSL/TLS, works behind CGNAT and double NAT.
       
      Container: newt-changemaker \u00b7 Managed from Admin \u2192 Settings \u2192 Tunnel
       
       Deployment Guide \u00b7  Pangolin GitHub
       
      •  
    ","tags":["reference","operator","services","docker"]},{"location":"docs/services/#monitoring-stack","title":"Monitoring Stack","text":"
    These services run behind the monitoring Docker Compose profile. Start them with:
     
    docker compose --profile monitoring up -d\n
     
       
    •  
       Prometheus
       
      Metrics collection and time-series database. Scrapes 12 custom cm_* application metrics plus container, host, and Redis metrics. Pre-configured alert rules.
       
      Port: 9090 \u00b7 Container: prometheus-changemaker
       
       Prometheus Docs
       
      •  
    •  
       Grafana
       
      Metrics visualization with 3 auto-provisioned dashboards: API Overview, Infrastructure, and Campaign Activity. Supports custom dashboards and alerting.
       
      Port: 3005 \u00b7 Container: grafana-changemaker \u00b7 Subdomain: grafana.DOMAIN
       
       Grafana Docs
       
      •  
    •  
       Alertmanager
       
      Alert routing and notification delivery. Receives alerts from Prometheus and dispatches to Gotify, email, or webhooks based on configurable rules.
       
      Port: 9093 \u00b7 Container: alertmanager-changemaker
       
       Alertmanager Docs
       
      •  
    •  
       cAdvisor
       
      Container resource metrics. Exposes CPU, memory, network, and filesystem usage per container for Prometheus to scrape.
       
      Port: 8086 \u00b7 Container: cadvisor-changemaker
       
       cAdvisor GitHub
       
      •  
    •  
       Node Exporter
       
      Host system metrics. Reports CPU, memory, disk, and network stats for the underlying server.
       
      Port: 9100 \u00b7 Container: node-exporter-changemaker
       
       Node Exporter
       
      •  
    •  
       Redis Exporter
       
      Redis metrics for Prometheus. Exposes connection counts, memory usage, command stats, and keyspace info.
       
      Port: 9121 \u00b7 Container: redis-exporter-changemaker
       
       Redis Exporter GitHub
       
      •  
    •  
       Gotify
       
      Self-hosted push notification server. Receives alerts from Alertmanager and delivers them to mobile/desktop clients.
       
      Port: 8889 \u00b7 Container: gotify-changemaker
       
       Gotify Docs
       
      •  
    ","tags":["reference","operator","services","docker"]},{"location":"docs/services/#quick-reference","title":"Quick Reference","text":"
    All services at a glance with their default ports and subdomains.
     Service Port Subdomain Docker Profile Express API 4000 api. default Media API 4100 media. default Admin GUI 3000 app. default PostgreSQL 5433 \u2014 default Redis 6379 \u2014 default Nginx 80/443 (all) default Listmonk 9001 listmonk. default MailHog 8025 mail. default MkDocs (dev) 4003 docs. default MkDocs (static) 4004 (root) default Code Server 8888 code. default NocoDB 8091 db. default n8n 5678 n8n. default Gitea 3030 git. default Mini QR 8089 qr. default Homepage 3010 home. default Excalidraw 8090 draw. default Vaultwarden 8445 vault. default Rocket.Chat \u2014 chat. default Jitsi Meet \u2014 meet. default Gancio 8092 events. default Newt (tunnel) \u2014 \u2014 default Prometheus 9090 \u2014 monitoring Grafana 3005 grafana. monitoring Alertmanager 9093 \u2014 monitoring cAdvisor 8086 \u2014 monitoring Node Exporter 9100 \u2014 monitoring Redis Exporter 9121 \u2014 monitoring Gotify 8889 \u2014 monitoring 
    Starting services selectively
     
    You don't need to run everything. Start only what you need:
     
    # Core only\ndocker compose up -d v2-postgres redis api admin\n\n# Add nginx for subdomain routing\ndocker compose up -d nginx\n\n# Add monitoring\ndocker compose --profile monitoring up -d\n
     
    See Getting Started for the recommended startup order.
    ","tags":["reference","operator","services","docker"]},{"location":"docs/troubleshooting/","title":"Troubleshooting","text":"
    Common issues and their solutions when running Changemaker Lite.
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#cors-errors-in-production","title":"CORS Errors in Production","text":"
    Symptom: Browser console shows CORS errors when accessing production domain.
     
    Fix: Add your production domain to CORS_ORIGINS in .env:
     
    CORS_ORIGINS=https://app.yourdomain.org,http://localhost:3000\n
     
    Then restart the API: docker compose restart api
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#pangolin-tunnel-403302-errors","title":"Pangolin Tunnel \u2014 403/302 Errors","text":"
    Symptom: All API endpoints return 302 redirects to Pangolin auth page, or 403 Forbidden.
     
    Fix: In the Pangolin dashboard, set each resource to Not Protected (public access). Critical resources to fix first:
     
       
    1. api.yourdomain.org \u2014 Main API
      2.  
    2. app.yourdomain.org \u2014 Admin GUI + public pages
      3.  
    3. media.yourdomain.org \u2014 Media API
      4.  
     
    Verify:
     
    # Should return JSON, NOT a 302 redirect\ncurl -I https://api.yourdomain.org/api/health\n
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#database-connection-failures","title":"Database Connection Failures","text":"
    Symptom: API logs show database connection errors.
     
    Checklist:
     
       
    1. Check PostgreSQL: docker compose ps v2-postgres
      2.  
    2. Verify DATABASE_URL in .env matches container name and port
      3.  
    3. View logs: docker compose logs v2-postgres --tail 50
      4.  
    4. Test connection: docker compose exec api npx prisma db execute --stdin <<< \"SELECT 1\"
      5.  
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#redis-connection-failures","title":"Redis Connection Failures","text":"
    Symptom: API logs show Redis connection errors, rate limiting doesn't work.
     
    Checklist:
     
       
    1. Check Redis: docker compose ps redis-changemaker
      2.  
    2. Verify REDIS_PASSWORD and REDIS_URL format (redis://:password@host:port)
      3.  
    3. View logs: docker compose logs redis-changemaker --tail 50
      4.  
    4. Test: docker compose exec redis-changemaker redis-cli -a $REDIS_PASSWORD ping
      5.  
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#api-not-starting","title":"API Not Starting","text":"
    Symptom: API container keeps restarting or won't start.
     
    Checklist:
     
       
    1. Check logs: docker compose logs api --tail 100
      2.  
    2. Verify all required env vars are set (compare with .env.example)
      3.  
    3. Check database is ready: docker compose ps v2-postgres (should show \"healthy\")
      4.  
    4. Run migrations manually: docker compose exec api npx prisma migrate deploy
      5.  
    5. Check for port conflicts: ss -tlnp | grep 4000
      6.  
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#containers-in-restart-loops","title":"Containers in Restart Loops","text":"
    Symptom: docker compose ps shows containers with \"restarting\" status.
     
    Diagnosis:
     
    # Find restarting containers\ndocker compose ps | grep -i restarting\n\n# Check recent logs for the problem container\ndocker compose logs <service-name> --tail 50\n\n# Check container exit code\ndocker inspect <container-name> --format='{{.State.ExitCode}}'\n
     
    Common causes:
     
       
    • Missing environment variables (check .env)
      •  
    • Database not ready (healthcheck dependencies)
      •  
    • Port already in use by another process
      •  
    • Insufficient memory (check with free -h)
      •  
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#newt-tunnel-wont-connect","title":"Newt Tunnel Won't Connect","text":"
    Checklist (in order):
     
       
    1. Credentials: Verify PANGOLIN_NEWT_ID and PANGOLIN_NEWT_SECRET in .env
      2.  
    2. Endpoint: Confirm PANGOLIN_ENDPOINT matches your Pangolin server URL
      3.  
    3. Logs: docker compose logs newt --tail 50
      4.  
    4. Nginx running: Newt depends on nginx \u2014 docker compose ps nginx
      5.  
    5. Network: Ensure outbound HTTPS is not blocked by your firewall
      6.  
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#migration-errors","title":"Migration Errors","text":"
    Symptom: prisma migrate deploy fails.
     
    Common fixes:
     
    # Check migration status\ndocker compose exec api npx prisma migrate status\n\n# If migrations are out of sync, reset (DESTRUCTIVE \u2014 dev only)\ndocker compose exec api npx prisma migrate reset\n\n# If shadow database errors, create one\ndocker compose exec -T v2-postgres createdb -U changemaker prisma_shadow_diff\n
     
    Never use prisma db push in production
     
    Always use prisma migrate dev (development) or prisma migrate deploy (production) to keep migration history in sync.
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#media-api-upload-failures","title":"Media API Upload Failures","text":"
    Symptom: Video uploads fail with permission errors or 500 status.
     
    Checklist:
     
       
    1. Verify inbox volume is writable: check media/local/inbox has :rw mount
      2.  
    2. Check disk space: df -h
      3.  
    3. Verify FFmpeg is installed in container: docker compose exec media-api ffprobe -version
      4.  
    4. Check upload size limit: default is 10 GB in Fastify multipart config
      5.  
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#email-not-sending","title":"Email Not Sending","text":"
    Symptom: Advocacy emails or notifications aren't delivered.
     
    Checklist:
     
       
    1. Check EMAIL_TEST_MODE \u2014 if true, all emails go to MailHog (http://localhost:8025)
      2.  
    2. Verify SMTP credentials in .env (SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS)
      3.  
    3. Check BullMQ queue: visit Admin > Email Queue or check logs
      4.  
    4. Test SMTP from Settings: Admin > Settings > Email > Test Connection
      5.  
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#services-unreachable-via-tunnel","title":"Services Unreachable via Tunnel","text":"
    Checklist:
     
       
    1. Verify nginx is running: docker compose ps nginx
      2.  
    2. Test locally first: curl http://localhost:4000/api/health
      3.  
    3. Check nginx logs: docker compose logs nginx --tail 50
      4.  
    4. Verify DNS: dig app.yourdomain.org should point to your Pangolin server
      5.  
    5. Check Pangolin resources are all set to \"Not Protected\"
      6.  
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#slow-map-performance","title":"Slow Map Performance","text":"
    Symptom: Map page is slow or returns 500 errors with many locations.
     
    Causes and fixes:
     
       
    • Too many locations loaded at once \u2014 the API limits by address count with debounced bounds queries
      •  
    • Missing indexes \u2014 verify database has the 5 performance indexes on Location/Address tables
      •  
    • Browser memory \u2014 marker clustering activates above zoom level 18; below that, addresses are grouped
      •  
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#docker-disk-space","title":"Docker Disk Space","text":"
    Symptom: Builds fail, containers can't start, or images won't pull.
     
    # Check disk usage\ndf -h\n\n# Clean unused Docker resources\ndocker system prune -f\n\n# Clean old images (keep only last 2 days)\ndocker image prune -a --filter \"until=48h\"\n\n# Check what's using space\ndocker system df\n
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#getting-help","title":"Getting Help","text":"
    If your issue isn't listed here:
     
       
    1. Check the API logs: docker compose logs api --tail 200
      2.  
    2. Search the Gitea issues
      3.  
    3. Review the Deployment guide for production-specific issues
      4.  
    4. File a new issue with your logs and .env (redact passwords)
      5.  
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/user-guide/","title":"User Guide","text":"
    This guide covers everything you can do as a visitor or registered supporter \u2014 from contacting representatives to signing up for volunteer shifts.
    ","tags":["guide","user"]},{"location":"docs/user-guide/#what-you-can-do","title":"What You Can Do","text":"
       
    •  
       Campaigns
       
      Find active advocacy campaigns, look up your representatives, and send emails.
       
      •  
    •  
       Map
       
      Explore the interactive map showing locations across your community.
       
      •  
    •  
       Shifts
       
      Sign up for volunteer shifts and join canvassing teams.
       
      •  
    •  
       Events
       
      Browse upcoming events and RSVP through the event calendar.
       
      •  
    •  
       Gallery
       
      Watch campaign videos, browse photos, and explore playlists.
       
      •  
    •  
       Shop & Pricing
       
      Purchase campaign merchandise or subscribe to a membership plan.
       
      •  
    •  
       Donations
       
      Support the cause with one-time donations on branded pages.
       
      •  
    •  
       Your Profile
       
      View and manage your contact profile, preferences, and activity history.
       
      •  
    ","tags":["guide","user"]},{"location":"docs/user-guide/campaigns/","title":"Campaigns","text":"
    Browse active advocacy campaigns and contact your elected representatives.
    ","tags":["guide","user","influence","campaigns"]},{"location":"docs/user-guide/campaigns/#how-it-works","title":"How It Works","text":"
       
    1. Browse campaigns at /campaigns \u2014 see active campaigns with descriptions and email counts
      2.  
    2. Pick a campaign \u2014 read about the issue and who it targets
      3.  
    3. Enter your postal code \u2014 the system looks up your federal, provincial, municipal, and school board representatives
      4.  
    4. Send the email \u2014 use \"Send Now\" to send through the platform, or open it in your own email app (Gmail, Outlook, etc.)
      5.  
    5. Share the response \u2014 if a representative replies, submit it to the public Response Wall
      6.  
    ","tags":["guide","user","influence","campaigns"]},{"location":"docs/user-guide/campaigns/#response-wall","title":"Response Wall","text":"
    Each campaign has a public response wall where supporters share how their representatives responded. Responses can be upvoted and are moderated by admins. Verified responses display a trust badge.
    ","tags":["guide","user","influence","campaigns"]},{"location":"docs/user-guide/campaigns/#submit-your-own-campaign","title":"Submit Your Own Campaign","text":"
    Registered users can draft and submit their own advocacy campaigns at /campaigns/create. Submissions go through admin review before being published.
    ","tags":["guide","user","influence","campaigns"]},{"location":"docs/user-guide/campaigns/#public-routes","title":"Public Routes","text":"
       
    • /campaigns \u2014 browse active campaigns
      •  
    • /campaign/:slug \u2014 take action on a specific campaign
      •  
    • /campaign/:slug/responses \u2014 view the response wall
      •  
    • /campaigns/create \u2014 submit a user-generated campaign (requires login)
      •  
    • /campaigns/mine \u2014 manage your submitted campaigns (requires login)
      •  
    ","tags":["guide","user","influence","campaigns"]},{"location":"docs/user-guide/donations/","title":"Donations","text":"
    Make one-time contributions on branded donation pages.
    ","tags":["guide","user","payments"]},{"location":"docs/user-guide/donations/#how-it-works","title":"How It Works","text":"
       
    1. Browse donation pages at /donate
      2.  
    2. Choose a campaign to support
      3.  
    3. Select a suggested amount or enter a custom amount
      4.  
    4. Complete payment securely through Stripe
      5.  
    5. Receive a confirmation with a thank-you message
      6.  
    ","tags":["guide","user","payments"]},{"location":"docs/user-guide/donations/#donation-pages","title":"Donation Pages","text":"
    Each donation page has:
     
       
    • Custom branding \u2014 unique title, description, and cover image
      •  
    • Suggested amounts \u2014 pre-set donation tiers for quick selection
      •  
    • Goal tracking \u2014 progress bar showing how close the campaign is to its fundraising goal
      •  
    • Anonymous giving \u2014 option to donate without displaying your name
      •  
    ","tags":["guide","user","payments"]},{"location":"docs/user-guide/donations/#public-routes","title":"Public Routes","text":"
       
    • /donate \u2014 browse donation pages
      •  
    • /donate/:slug \u2014 donate on a specific campaign page
      •  
    ","tags":["guide","user","payments"]},{"location":"docs/user-guide/events/","title":"Events (Gancio)","text":"
    Integrated with Gancio for self-hosted event management. When enabled, volunteer shifts are automatically published as public events.
    ","tags":["guide","user","events"]},{"location":"docs/user-guide/events/#shift-to-event-sync","title":"Shift-to-Event Sync","text":"
    When GANCIO_SYNC_ENABLED=true, the platform:
     
       
    1. Creates a Gancio event whenever a new shift is published
      2.  
    2. Updates the event if the shift time, location, or details change
      3.  
    3. Deletes the event if the shift is cancelled
      4.  
     
    Sync uses OAuth authentication with the Gancio admin account.
    ","tags":["guide","user","events"]},{"location":"docs/user-guide/events/#key-features","title":"Key Features","text":"
       
    • Automatic sync \u2014 shifts appear as public events without manual entry
      •  
    • Embeddable calendar \u2014 GrapesJS block and MkDocs widget for embedding the event calendar on pages
      •  
    • Public events page \u2014 linked from the public navigation when enableEvents is enabled in settings
      •  
    ","tags":["guide","user","events"]},{"location":"docs/user-guide/events/#admin-routes","title":"Admin Routes","text":"
       
    • /app/gancio \u2014 Gancio service status and iframe embed
      •  
    ","tags":["guide","user","events"]},{"location":"docs/user-guide/events/#public-routes","title":"Public Routes","text":"
       
    • /events \u2014 public events navigation link (when enabled)
      •  
    • events.DOMAIN \u2014 Gancio web interface for browsing and RSVPs
      •  
    ","tags":["guide","user","events"]},{"location":"docs/user-guide/gallery/","title":"Gallery","text":"
    The public gallery at /gallery showcases campaign videos, photos, and curated playlists.
    ","tags":["guide","user","media","gallery"]},{"location":"docs/user-guide/gallery/#videos","title":"Videos","text":"
       
    • Browse by category \u2014 videos organized into categories with thumbnails and durations
      •  
    • Video player \u2014 full playback with engagement features (reactions, comments)
      •  
    • Shorts feed \u2014 TikTok-style vertical video feed for clips under 60 seconds at /gallery/shorts
      •  
    ","tags":["guide","user","media","gallery"]},{"location":"docs/user-guide/gallery/#photos","title":"Photos","text":"
       
    • Photo albums \u2014 browse photos organized into named collections
      •  
    • Reactions and comments \u2014 engage with individual photos
      •  
    ","tags":["guide","user","media","gallery"]},{"location":"docs/user-guide/gallery/#playlists","title":"Playlists","text":"
       
    • Curated playlists \u2014 admin and community-created video collections
      •  
    • Featured carousel \u2014 highlighted playlists on the gallery homepage
      •  
    • Playlist viewer \u2014 continuous playback with up-next queue at /gallery/playlist/:id
      •  
    ","tags":["guide","user","media","gallery"]},{"location":"docs/user-guide/gallery/#public-routes","title":"Public Routes","text":"
       
    • /gallery \u2014 public video and photo gallery
      •  
    • /gallery/watch/:id \u2014 watch a specific video
      •  
    • /gallery/playlist/:id \u2014 view a playlist
      •  
    • /gallery/shorts \u2014 browse the shorts feed
      •  
    ","tags":["guide","user","media","gallery"]},{"location":"docs/user-guide/map/","title":"Map","text":"
    The public map at /map shows locations across your community on an interactive Leaflet map.
    ","tags":["guide","user","map"]},{"location":"docs/user-guide/map/#features","title":"Features","text":"
       
    • Interactive map \u2014 zoom, pan, and click markers to see address details
      •  
    • Color-coded markers \u2014 locations are color-coded based on their status
      •  
    • Cluster groups \u2014 markers group together when zoomed out for better performance
      •  
    • Fullscreen mode \u2014 expand the map to fill your screen
      •  
    ","tags":["guide","user","map"]},{"location":"docs/user-guide/map/#public-routes","title":"Public Routes","text":"
       
    • /map \u2014 public interactive map
      •  
    ","tags":["guide","user","map"]},{"location":"docs/user-guide/profile/","title":"Self-Service Contact Profile","text":"
    Give supporters a private, token-based link to view and manage their own contact profile -- no login required.
    ","tags":["guide","user","CRM"]},{"location":"docs/user-guide/profile/#how-it-works","title":"How It Works","text":"
       
    1. An admin generates a profile link from the People CRM -- each link contains a unique 64-character hex token with a configurable expiration (24 hours to 1 year).
      2.  
    2. The supporter opens the link -- if the link is password-protected, they enter the password first. If expired, they see a branded expiration notice.
      3.  
    3. The supporter views and edits their profile -- they can update their name, email, phone, address, and cover photo.
      4.  
    4. Communication preferences -- supporters can opt out of email and/or SMS communications with simple toggle switches.
      5.  
    ","tags":["guide","user","CRM"]},{"location":"docs/user-guide/profile/#profile-tabs","title":"Profile Tabs","text":"
       
    • Profile -- edit display name, first/last name, email, phone, and address
      •  
    • Preferences -- toggle email and SMS opt-out switches
      •  
    • Activity -- paginated timeline of all engagement: emails sent, responses submitted, shift signups, canvass visits, donations, video views, and profile edits
      •  
    • Social tabs -- if the viewer is a logged-in user viewing their own profile and the social feature is enabled, additional tabs appear: Friends, Feed, Achievements, Notifications, and Discover
      •  
    ","tags":["guide","user","CRM"]},{"location":"docs/user-guide/profile/#security","title":"Security","text":"
       
    • Token-based access -- no account or login needed; the URL token grants access
      •  
    • Password protection -- admins can optionally set a password on the profile link
      •  
    • Expiration -- links expire after a configurable duration, showing a branded message with the expiration date
      •  
    • Rate limiting -- separate rate limits on profile views, edits, photo uploads, and password attempts
      •  
    • Cover photo -- supporters can upload a JPEG, PNG, or WebP cover photo (max 5 MB), automatically resized to 800x400
      •  
    ","tags":["guide","user","CRM"]},{"location":"docs/user-guide/profile/#engagement-score","title":"Engagement Score","text":"
    Each profile shows a circular engagement score (0-100) calculated from the contact's activity across the platform -- emails, shifts, canvass visits, donations, and video views.
    ","tags":["guide","user","CRM"]},{"location":"docs/user-guide/profile/#public-routes","title":"Public Routes","text":"
       
    • /profile/:token -- self-service contact profile page
      •  
    ","tags":["guide","user","CRM"]},{"location":"docs/user-guide/shifts/","title":"Shifts","text":"
    Browse available volunteer shifts and sign up to participate in canvassing and other campaign activities.
    ","tags":["guide","user","shifts"]},{"location":"docs/user-guide/shifts/#signing-up","title":"Signing Up","text":"
       
    1. Visit /shifts to see available time slots
      2.  
    2. Pick a shift that works for your schedule
      3.  
    3. Fill in your name and email
      4.  
    4. You'll receive a confirmation email with login credentials
      5.  
    ","tags":["guide","user","shifts"]},{"location":"docs/user-guide/shifts/#quick-join","title":"Quick Join","text":"
    Organizers may share a QR code at events for instant onboarding:
     
       
    1. Scan the QR code \u2014 it opens a Quick Join page
      2.  
    2. Enter your email (and optionally your name and phone)
      3.  
    3. Start immediately \u2014 you're logged in and redirected to the volunteer portal with your area pre-loaded
      4.  
     
    Quick Join creates a temporary 24-hour account. Your organizer can upgrade it to a permanent account afterward.
    ","tags":["guide","user","shifts"]},{"location":"docs/user-guide/shifts/#after-signing-up","title":"After Signing Up","text":"
    Once you have an account, log in to access the Volunteer Portal where you can:
     
       
    • View your assigned shifts and canvassing areas
      •  
    • Open the canvass map for GPS-guided door-to-door outreach
      •  
    • Track your activity and visit history
      •  
     
    See the Volunteer Guide for the full volunteer experience.
    ","tags":["guide","user","shifts"]},{"location":"docs/user-guide/shifts/#public-routes","title":"Public Routes","text":"
       
    • /shifts \u2014 browse and sign up for volunteer shifts
      •  
    • /join?token=... \u2014 quick join via invite link or QR code
      •  
    ","tags":["guide","user","shifts"]},{"location":"docs/user-guide/shop/","title":"Shop & Pricing","text":"
    Support the campaign by purchasing merchandise or subscribing to a membership plan.
    ","tags":["guide","user","payments"]},{"location":"docs/user-guide/shop/#shop","title":"Shop","text":"
    Browse available products at /shop:
     
       
    • Campaign merchandise and branded items
      •  
    • One-time purchases with Stripe checkout
      •  
    • Product details with images and descriptions
      •  
    ","tags":["guide","user","payments"]},{"location":"docs/user-guide/shop/#membership-plans","title":"Membership Plans","text":"
    View subscription options at /pricing:
     
       
    • Tiered membership plans with different benefits
      •  
    • Monthly and yearly billing options
      •  
    • Secure recurring payments through Stripe
      •  
    ","tags":["guide","user","payments"]},{"location":"docs/user-guide/shop/#public-routes","title":"Public Routes","text":"
       
    • /shop \u2014 browse products
      •  
    • /pricing \u2014 view subscription plans
      •  
    ","tags":["guide","user","payments"]},{"location":"docs/volunteer/","title":"Volunteer Guide","text":"
    Welcome! This guide walks you through everything you need as a campaign volunteer.
    ","tags":["guide","volunteer"]},{"location":"docs/volunteer/#getting-started","title":"Getting Started","text":"","tags":["guide","volunteer"]},{"location":"docs/volunteer/#1-sign-up-for-a-shift","title":"1. Sign Up for a Shift","text":"
    Visit the Shifts page (your organizer will share the link, or find it at /shifts). Browse available time slots, pick one that works, and fill in your name and email. You'll receive a confirmation email with login credentials.
    ","tags":["guide","volunteer"]},{"location":"docs/volunteer/#2-log-in","title":"2. Log In","text":"
    Sign in with the email and password from your confirmation at the login page.
    ","tags":["guide","volunteer"]},{"location":"docs/volunteer/#3-explore-the-volunteer-portal","title":"3. Explore the Volunteer Portal","text":"
    After logging in, you'll land on the volunteer portal. Use the bottom navigation to access:
     
       
    • Map \u2014 your canvassing area with GPS tracking
      •  
    • Shifts \u2014 your upcoming and past shifts
      •  
    • Friends \u2014 social connections with other volunteers
      •  
    • Achievements \u2014 badges and leaderboards
      •  
    ","tags":["guide","volunteer"]},{"location":"docs/volunteer/#in-this-section","title":"In This Section","text":"
       
    • Canvassing \u2014 the GPS-guided canvass map, recording visits, and walking routes
      •  
    • Shifts \u2014 viewing your assigned shifts, activity log, and route history
      •  
    • Social \u2014 friend connections, activity feed, groups, profiles, and privacy settings
      •  
    • Achievements \u2014 unlockable badges, progress tracking, and competitive leaderboards
      •  
    ","tags":["guide","volunteer"]},{"location":"docs/volunteer/#browsing-public-pages","title":"Browsing Public Pages","text":"
    Tap your name/avatar in the header and select Browse Site to visit the public pages \u2014 campaigns, the public map, and shift signups.
    ","tags":["guide","volunteer"]},{"location":"docs/volunteer/#faq","title":"FAQ","text":"
    Q: I can't find my assigned area on the map. A: Make sure your shift has an area assigned. Check with your organizer.
     
    Q: My GPS isn't working. A: Allow location access in your browser. Try moving near a window for better signal.
     
    Q: I recorded the wrong outcome. A: Visit the same address again and record the correct outcome. The most recent visit counts.
     
    Q: How do I sign up for more shifts? A: Visit the public shifts page at /shifts.
    ","tags":["guide","volunteer"]},{"location":"docs/volunteer/achievements/","title":"Achievements & Leaderboard","text":"
    Recognize volunteer contributions with unlockable achievement badges and competitive leaderboards.
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/achievements/#how-it-works","title":"How It Works","text":"
    Achievements are checked automatically when relevant actions occur (e.g., signing up for a shift, completing a canvass session, accepting a friend request). When a user's progress meets the threshold, the badge is unlocked and an in-app notification is sent.
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/achievements/#badge-categories","title":"Badge Categories","text":"","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/achievements/#shifts","title":"Shifts","text":"Badge Name Threshold Description FIRST_SHIFT First Steps 1 confirmed signup Sign up for your first volunteer shift SHIFT_STREAK_3 Reliable Volunteer 3 confirmed signups Sign up for 3 volunteer shifts SHIFT_STREAK_10 Shift Champion 10 confirmed signups Sign up for 10 volunteer shifts","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/achievements/#canvassing","title":"Canvassing","text":"Badge Name Threshold Description FIRST_CANVASS Door Knocker 1 completed session Complete your first canvass session CANVASS_50_DOORS Neighbourhood Explorer 50 visits Record 50 canvass visits CANVASS_100_DOORS Community Connector 100 visits Record 100 canvass visits CANVASS_500_DOORS Door-to-Door Legend 500 visits Record 500 canvass visits","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/achievements/#campaigns","title":"Campaigns","text":"Badge Name Threshold Description FIRST_CAMPAIGN_EMAIL Voice Heard 1 email sent Send your first advocacy email CAMPAIGN_CHAMPION Campaign Champion 5 distinct campaigns Participate in 5 different campaigns","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/achievements/#social","title":"Social","text":"Badge Name Threshold Description SOCIAL_BUTTERFLY Social Butterfly 10 accepted friends Make 10 friends on the platform TEAM_PLAYER Team Player 3 group memberships Be a member of 3 groups","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/achievements/#progress-tracking","title":"Progress Tracking","text":"
    Each badge displays a progress bar showing current progress toward the threshold. Already-unlocked badges show the unlock date and the progress value at unlock time or the current count (whichever is higher).
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/achievements/#leaderboards","title":"Leaderboards","text":"
    The Achievements page includes a leaderboard tab with three ranking types:
     
       
    • Canvass \u2014 ranked by total canvass visits recorded
      •  
    • Shifts \u2014 ranked by total confirmed shift signups
      •  
    • Campaigns \u2014 ranked by number of distinct campaigns participated in
      •  
     
    Leaderboard entries show rank, user name, and score. Users who have disabled \"Show in Friend Activity\" in their privacy settings are excluded from leaderboard rankings to respect their privacy choices.
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/achievements/#volunteer-stats","title":"Volunteer Stats","text":"
    The Achievements page also displays aggregate stats for the current user:
     
       
    • Confirmed shift signups
      •  
    • Completed canvass sessions
      •  
    • Total canvass visits
      •  
    • Advocacy emails sent
      •  
    • Campaigns participated in
      •  
    • Friend count
      •  
    • Group memberships
      •  
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/achievements/#volunteer-routes","title":"Volunteer Routes","text":"
       
    • /volunteer/achievements \u2014 badge gallery, progress bars, leaderboard tabs, and personal stats
      •  
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/canvassing/","title":"Canvassing","text":"
    The volunteer canvass map is your main tool for door-to-door outreach \u2014 a full-screen GPS-tracked experience.
    ","tags":["guide","volunteer","map","canvassing"]},{"location":"docs/volunteer/canvassing/#the-volunteer-map","title":"The Volunteer Map","text":"","tags":["guide","volunteer","map","canvassing"]},{"location":"docs/volunteer/canvassing/#what-you-see","title":"What You See","text":"
       
    • Colored markers \u2014 each marker is an address. Colors indicate the outcome of the last visit (green = supportive, red = opposed, grey = not yet visited)
      •  
    • Clusters \u2014 when zoomed out, markers group together showing the address count. Tap a cluster to zoom in.
      •  
    • Blue dot \u2014 your current GPS position
      •  
    • Walking route \u2014 a suggested path through the addresses (dotted line)
      •  
    ","tags":["guide","volunteer","map","canvassing"]},{"location":"docs/volunteer/canvassing/#recording-a-visit","title":"Recording a Visit","text":"
       
    1. Tap a marker to select an address
      2.  
    2. A bottom panel slides up showing address details
      3.  
    3. Tap Record Visit to log what happened:
         
      • Not Home \u2014 nobody answered
        •  
      • Supportive \u2014 positive interaction
        •  
      • Opposed \u2014 not supportive
        •  
      • Undecided \u2014 hasn't made up their mind
        •  
      • Moved \u2014 no longer lives there
        •  
      • Refused \u2014 declined to talk
        •  
       
      4.  
    4. Optionally add a note about the visit
      5.  
    5. Tap Save \u2014 the marker color updates immediately
      6.  
    ","tags":["guide","volunteer","map","canvassing"]},{"location":"docs/volunteer/canvassing/#sessions","title":"Sessions","text":"
       
    • Start a session before you begin knocking on doors \u2014 this tracks your route and time
      •  
    • End your session when you're done for the day
      •  
    • The map works offline for basic viewing, but you need a connection to save visits
      •  
    • If GPS is inaccurate, manually tap the correct marker on the map
      •  
    ","tags":["guide","volunteer","map","canvassing"]},{"location":"docs/volunteer/canvassing/#routes","title":"Routes","text":"
    The Routes tab shows your past canvassing routes on a map, helping you see which areas you've covered and plan your next outing.
    ","tags":["guide","volunteer","map","canvassing"]},{"location":"docs/volunteer/canvassing/#volunteer-routes","title":"Volunteer Routes","text":"
       
    • /volunteer \u2014 full-screen canvass map with GPS and visit recording
      •  
    • /volunteer/activity \u2014 visit history and outcome breakdown
      •  
    • /volunteer/routes \u2014 past canvassing routes
      •  
    ","tags":["guide","volunteer","map","canvassing"]},{"location":"docs/volunteer/shifts/","title":"Your Shifts","text":"
    View your upcoming and past volunteer shifts from the Shifts tab in the bottom navigation.
    ","tags":["guide","volunteer","shifts"]},{"location":"docs/volunteer/shifts/#shift-details","title":"Shift Details","text":"
    Each shift shows:
     
       
    • Date and time
      •  
    • Assigned area (if linked to a canvassing territory)
      •  
    • A button to open the canvass map for that area
      •  
    ","tags":["guide","volunteer","shifts"]},{"location":"docs/volunteer/shifts/#activity-log","title":"Activity Log","text":"
    The Activity tab shows your complete visit history:
     
       
    • Outcome breakdown \u2014 pie chart of your visit outcomes
      •  
    • Visit list \u2014 each visit with address, outcome, time, and notes
      •  
    • Stats \u2014 total visits, addresses covered, and sessions completed
      •  
    ","tags":["guide","volunteer","shifts"]},{"location":"docs/volunteer/shifts/#volunteer-routes","title":"Volunteer Routes","text":"
       
    • /volunteer/shifts \u2014 view assigned shifts
      •  
    • /volunteer/activity \u2014 visit history and outcome breakdown
      •  
    ","tags":["guide","volunteer","shifts"]},{"location":"docs/volunteer/social/","title":"Social Connections","text":"
    Connect with fellow volunteers through friend requests, activity feeds, team groups, and real-time notifications. Enable via Settings > Feature Toggles > Social Connections.
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/social/#friends","title":"Friends","text":"
       
    • Send requests \u2014 search for other volunteers and send friend requests
      •  
    • Accept / decline / cancel \u2014 manage requests from the Friends page
      •  
    • Mutual friends \u2014 view shared connections between users
      •  
    • Block / unblock \u2014 blocked users cannot send requests or appear in suggestions
      •  
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/social/#discover","title":"Discover","text":"
    The Discover page suggests potential friends using a ranked scoring algorithm based on:
     
       
    • Household/family connections (highest priority)
      •  
    • Mutual friends
      •  
    • Shared shifts (co-volunteers from the last 90 days)
      •  
    • Shared campaigns (co-participants from the last 90 days)
      •  
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/social/#activity-feed","title":"Activity Feed","text":"
    The Social Feed at /volunteer/feed shows recent activity from your friends:
     
       
    • Shift signups, campaign emails, canvass sessions, and response submissions
      •  
    • Limited to the last 30 days (max 50 items)
      •  
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/social/#groups","title":"Groups","text":"
    Groups are automatically created based on platform activity:
     
       
    • Shift teams \u2014 created when 2+ volunteers share a shift
      •  
    • Campaign teams \u2014 created when 2+ users participate in the same campaign
      •  
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/social/#profiles","title":"Profiles","text":"
    Each volunteer has a social profile showing volunteer stats, achievement badges, friendship status, and recent activity.
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/social/#pokes","title":"Pokes","text":"
    Send a friendly nudge to any accepted friend (24-hour cooldown per pair).
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/social/#privacy-settings","title":"Privacy Settings","text":"Setting Default Description Show online status On Whether friends see you as online Show in friend activity On Whether your actions appear in feeds Allow friend requests On Whether others can send you requests","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/social/#digest-emails","title":"Digest Emails","text":"
    Opt into periodic social digest emails with friend activity, unread notifications, and pending requests. Choose daily or weekly frequency.
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/social/#volunteer-routes","title":"Volunteer Routes","text":"
       
    • /volunteer/feed \u2014 social activity feed
      •  
    • /volunteer/friends \u2014 friends, requests, blocked, and groups
      •  
    • /volunteer/discover \u2014 ranked friend suggestions
      •  
    • /volunteer/profile \u2014 your social profile
      •  
    • /volunteer/profile/:userId \u2014 another volunteer's profile
      •  
    • /volunteer/notifications \u2014 notification center and preferences
      •  
    • /volunteer/groups/:id \u2014 group detail with member list
      •  
    ","tags":["guide","volunteer","social"]},{"location":"blog/archive/2026/","title":"2026","text":""},{"location":"blog/category/announcements/","title":"Announcements","text":""},{"location":"blog/category/platform/","title":"Platform","text":""}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\u200b\\-_,:!=\\[\\]()\"`/]+|\\.(?!\\d)|&[lg]t;|(?!\\b)(?=[A-Z][a-z])","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"test-page/","title":"Test Page","text":"
    Testing
     
    testing testing one two
     
    hello is this content going to show? 
    "},{"location":"test/","title":"test","text":"
    Hello! 
    "},{"location":"blog/","title":"Blog","text":""},{"location":"blog/2026/03/27/test-blog-post---version-7/","title":"Test Blog Post - Version 7","text":"
    This version uses the auto-setup token.
    "},{"location":"blog/2026/03/22/introducing-changemaker-lite-v2/","title":"Introducing Changemaker Lite v2","text":"
    Changemaker Lite v2 is a ground-up rebuild of the platform \u2014 same mission, entirely new architecture. After 14 phases of development, the platform is ready for production use.
    ","tags":["v2","release","self-hosted","FOSS"]},{"location":"blog/2026/03/22/introducing-changemaker-lite-v2/#what-changed","title":"What Changed","text":"
    V1 was two independent Express apps stitched together with NocoDB as a data layer. It worked, but scaling features meant fighting the architecture at every turn.
     
    V2 is a unified TypeScript stack:
     
       
    • Dual API architecture \u2014 Express.js for the main platform, Fastify for the media library, sharing a single PostgreSQL 16 database via Prisma ORM
      •  
    • React admin GUI \u2014 Vite + Ant Design + Zustand, serving admin, public, and volunteer interfaces from one build
      •  
    • 30+ Docker services \u2014 from core infrastructure to monitoring, communication, and developer tools
      •  
    • JWT authentication with refresh token rotation, role-based access control (11 roles), and a comprehensive security audit
      •  
    ","tags":["v2","release","self-hosted","FOSS"]},{"location":"blog/2026/03/22/introducing-changemaker-lite-v2/#whats-new","title":"What's New","text":"
    The feature set has grown substantially:
     
       
    • Advocacy campaigns with postal code \u2192 representative lookup, email sending, response walls, and moderation
      •  
    • Map & canvassing with multi-provider geocoding, polygon territories, GPS-tracked volunteer sessions, and walking route generation
      •  
    • Media manager with video upload, FFprobe metadata extraction, scheduled publishing, analytics, and a public gallery
      •  
    • Landing page builder powered by GrapesJS with drag-and-drop editing
      •  
    • Payments via encrypted Stripe integration \u2014 products, donations, and subscription plans
      •  
    • SMS campaigns via a Termux Android bridge
      •  
    • Team communication with self-hosted Rocket.Chat and Jitsi Meet
      •  
    • People CRM aggregating contacts across all modules with duplicate detection and merge
      •  
    • Volunteer social features \u2014 friend system, achievements, leaderboards, and a personal calendar
      •  
    • One-command install \u2014 curl | bash pulls a release tarball and runs the config wizard
      •  
    ","tags":["v2","release","self-hosted","FOSS"]},{"location":"blog/2026/03/22/introducing-changemaker-lite-v2/#why-self-hosted","title":"Why Self-Hosted","text":"
    Every subscription to corporate campaign software funds infrastructure you don't control. Your voter lists, canvassing outcomes, and communication patterns become assets on someone else's balance sheet.
     
    Changemaker Lite costs roughly the price of a VPS \u2014 often under $50/month for the full stack. But the real value isn't cost savings. It's control. No vendor can cut off your access. No acquisition can change your terms.
     
    Read more in our Philosophy page.
    ","tags":["v2","release","self-hosted","FOSS"]},{"location":"blog/2026/03/22/introducing-changemaker-lite-v2/#get-started","title":"Get Started","text":"
    curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/main/scripts/install.sh | bash\n
     
    Or follow the Getting Started guide for a walkthrough.
    ","tags":["v2","release","self-hosted","FOSS"]},{"location":"blog/2026/03/22/introducing-changemaker-lite-v2/#whats-next","title":"What's Next","text":"
    Phase 15 (Testing & Polish) is underway. We're also working on:
     
       
    • Social Calendar Phase B (shared views, availability finder)
      •  
    • Expanded test coverage
      •  
    • Performance optimization for large location datasets
      •  
     
    Follow this blog for updates, or subscribe to the newsletter.
    ","tags":["v2","release","self-hosted","FOSS"]},{"location":"comments/callback/","title":"Signing in...","text":"
    Completing sign in...
     
    You will be redirected back to the page you were on.
    "},{"location":"docs/","title":"Documentation","text":"
    Welcome to the Changemaker Lite documentation. Whether you're a campaign volunteer, an admin managing operations, or a sysadmin deploying the platform \u2014 start here.
    ","tags":["guide","getting-started"],"boost":2},{"location":"docs/#use-the-platform","title":"Use the Platform","text":"
       
    •  
       Getting Started
       
      Install Changemaker Lite, create your first admin account, and explore the dashboard.
       
       Getting Started
       
      •  
    •  
       Feature Guides
       
      Campaigns, email advocacy, response walls, map locations, landing pages, and media.
       
       Feature Guides
       
      •  
    •  
       Administration
       
      User management, roles and permissions, site settings, email templates, and newsletters.
       
       Administration
       
      •  
    •  
       Volunteer Guide
       
      Sign up for shifts, use the canvassing map, record visits, and track your activity.
       
       Volunteer Guide
       
      •  
    ","tags":["guide","getting-started"],"boost":2},{"location":"docs/#deploy-operate","title":"Deploy & Operate","text":"
       
    •  
       Deployment
       
      Docker Compose setup, environment variables, SSL/TLS, backups, and production checklist.
       
       Deployment
       
      •  
    •  
       Architecture
       
      Dual API design, database schema, authentication flow, and system diagram.
       
       Architecture
       
      •  
    •  
       Services
       
      Nginx routing, Redis, PostgreSQL, Listmonk, MkDocs, Gitea, NocoDB, and more.
       
       Services
       
      •  
    •  
       Monitoring
       
      Prometheus metrics, Grafana dashboards, Alertmanager rules, and health checks.
       
       Monitoring
       
      •  
    ","tags":["guide","getting-started"],"boost":2},{"location":"docs/#reference","title":"Reference","text":"
       
    •  
       API Reference
       
      REST endpoints for auth, campaigns, locations, shifts, media, and more.
       
       API Reference
       
      •  
    •  
       Troubleshooting
       
      Common errors, CORS issues, database problems, tunnel debugging, and FAQ.
       
       Troubleshooting
       
      •  
    •  
       Security
       
      Password policy, rate limiting, token rotation, encryption, and audit report.
       
       Security See Deployment
       
      •  
    •  
       Contributing
       
      Development setup, code style, git workflow, and pull request guidelines.
       
       Contributing
       
      •  
    ","tags":["guide","getting-started"],"boost":2},{"location":"docs/#platform-at-a-glance","title":"Platform at a Glance","text":"Component Technology Purpose Main API Express.js + Prisma Auth, campaigns, map, shifts, pages, email Media API Fastify + Prisma Video library, analytics, upload, scheduling Admin GUI React + Ant Design + Zustand Dashboard for admins and organizers Database PostgreSQL 16 Single shared database for both APIs Cache Redis Rate limiting, BullMQ jobs, geocoding queue Proxy Nginx Subdomain routing, security headers, SSL Tunnel Pangolin + Newt Expose services without port forwarding Monitoring Prometheus + Grafana Metrics, dashboards, alerts 
    New here?
     
    Start with the Getting Started guide to have the platform running in under 30 minutes.
     
    Looking for the source?
     
    Changemaker Lite is 100% open source. Browse the code on Gitea.
    ","tags":["guide","getting-started"],"boost":2},{"location":"docs/phil/","title":"Philosophy","text":"","tags":["concept","philosophy","FOSS"]},{"location":"docs/phil/#software-is-political","title":"Software Is Political","text":"
    Every tool your movement adopts shapes how you organize. Proprietary platforms reinforce hierarchy \u2014 the vendor decides what features you get, what data you can export, and what happens when you stop paying. Community-controlled tools support democratic autonomy because the people using them decide how they work.
     
    If you do politics, who is reading your secrets? Corporate platforms harvest political intelligence systematically. Facebook chat data has been used in criminal prosecutions. Social media platforms are leveraged for political coordination and surveillance. When you organize on corporate infrastructure, you hand your strategies, your voter data, and your movement's internal conversations to entities that may have every reason to work against you.
     
    Changemaker Lite exists because we believe organizational independence requires technological independence.
    ","tags":["concept","philosophy","FOSS"]},{"location":"docs/phil/#the-extractive-model","title":"The Extractive Model","text":"
    Most campaign and political software is extractive by design. The pattern is familiar:
     
       
    1. Free trial hooks you in
      2.  
    2. Paid features gate the tools you actually need
      3.  
    3. Data export becomes difficult or impossible
      4.  
    4. Pricing escalates as you grow and become dependent
      5.  
    5. Your usage patterns are monetized through data partnerships, behavioral analytics, and enterprise contracts
      6.  
     
    This isn't a side effect \u2014 it's the business model. You pay with money and with data. Your voter lists, canvassing outcomes, donor records, and communication patterns become assets on someone else's balance sheet.
     
    Every subscription to corporate software funds the machine you're fighting.
    ","tags":["concept","philosophy","FOSS"]},{"location":"docs/phil/#the-alternative-grow-power-dont-rent-it","title":"The Alternative: Grow Power, Don't Rent It","text":"
    Changemaker asks a different question than most political tech: instead of \"how do we extract more data from a community?\" we ask \"what tools are needed to grow change in a community?\"
     
    Growing change means:
     
       
    • Making real connections between organizers, volunteers, and community members \u2014 not just collecting their contact info
      •  
    • Providing access to the same caliber of tools that well-funded campaigns use \u2014 without the price tag or the surveillance
      •  
    • Deeply understanding the wants and needs of your movement \u2014 on infrastructure you control, with data you own
      •  
    ","tags":["concept","philosophy","FOSS"]},{"location":"docs/phil/#distributed-organizing-is-the-way-out","title":"Distributed Organizing Is The Way Out","text":"
    Socialist movements will never outspend capital. Progressive organizations cannot compete financially with well-funded conservative movements, and chasing big-donor dollars leads to mission drift and organizational capture \u2014 what some call the Political Industrial Complex.
     
    A thousand neighborhood mailing lists has more potential impact than any single organization. When organizing knowledge and digital tools are widely distributed \u2014 not gatekept by leadership or locked behind vendor paywalls \u2014 movements become genuinely resilient.
     
    The historical pattern is clear: worker victories occurred when organizing knowledge was widely distributed, not concentrated at the top. Changemaker Lite is built on this premise \u2014 provide the tools freely, train people to use them, and get out of the way.
     
    Workers, with the right tools, will build the future.
    ","tags":["concept","philosophy","FOSS"]},{"location":"docs/phil/#de-corp-your-stack","title":"De-Corp Your Stack","text":"
    The practical work of digital sovereignty starts with replacing corporate services one at a time:
     Corporate Tool Changemaker Alternative What You Gain Mailchimp Listmonk Unlimited subscribers, no per-send charges, your data stays local NationBuilder Changemaker Lite Full campaign platform without the $50-500/month ransom Google Docs Gitea + Code Server Version control, collaboration, no algorithmic scanning Slack Rocket.Chat Team chat with SSO, no message limits, no corporate eavesdropping SurveyMonkey Response Wall Supporter voices on your terms, with moderation you control Google Maps Self-hosted Leaflet No API fees, no tracking, offline-capable canvassing 
    The cost reduction is dramatic. Organizations spending thousands monthly on SaaS tools can replace them with a single self-hosted server running Changemaker Lite for roughly the cost of hosting \u2014 often under $50/month.
     
    But the real value isn't cost savings. It's control. No vendor can cut off your access. No acquisition can change your terms. No government can compel a foreign company to hand over your data. Your movement's digital infrastructure belongs to your movement.
    ","tags":["concept","philosophy","FOSS"]},{"location":"docs/phil/#security-culture-starts-with-infrastructure","title":"Security Culture Starts With Infrastructure","text":"
    Security culture isn't just about who knows what \u2014 it's about who can know what. When your communications run through corporate servers, you've made a structural decision about who has access before you've even thought about operational security.
     
    Key principles:
     
       
    • Compartmentalization by design \u2014 Self-hosted systems let you control exactly who has access to what, at the infrastructure level
      •  
    • No third-party access \u2014 No corporate subpoenas for your data, no partnership agreements sharing your information
      •  
    • Audit everything \u2014 When you run the servers, you can verify that your security promises are real, not just marketing
      •  
    • Consent and autonomy \u2014 Your community sets its own security boundaries rather than accepting whatever a vendor's privacy policy allows
      •  
     
    You wouldn't hold a sensitive strategy meeting in a room wired by someone else. Why would you plan your campaign on someone else's servers?
    ","tags":["concept","philosophy","FOSS"]},{"location":"docs/phil/#our-principles","title":"Our Principles","text":"
    Liberation First Technology should center marginalized voices. The tools we build reflect the values we hold, and they shape the movements that use them.
     
    Community Over Profit Changemaker Lite is free and open source software, built by a cooperative \u2014 not a startup looking for an exit. There are no shareholders to satisfy, no venture capitalists to answer to. The software serves the community because that's the only thing it's designed to do.
     
    Data Sovereignty Communities should own their complete digital infrastructure. Not just the content \u2014 the servers, the databases, the encryption keys, and the ability to pack up and leave at any time.
     
    Radical Accessibility Self-hosted doesn't have to mean self-excluding. Changemaker Lite is designed for organizers, not sysadmins. If you can follow a guide to set up a WordPress site, you can run this platform.
    ","tags":["concept","philosophy","FOSS"]},{"location":"docs/phil/#further-reading","title":"Further Reading","text":"
    These articles explore the ideas behind Changemaker Lite in depth:
     
       
    • If You Do Politics, Who Is Reading Your Secrets? \u2014 Why you should de-corp your software stack
      •  
    • Distributed Digital Organizing Is The Way Out \u2014 Why decentralized power structures outperform centralized ones
      •  
    • How Not To Get Got Making Content \u2014 Platform independence for political content creators
      •  
    • What Is Security Culture? \u2014 The foundations of security culture for movements
      •  
    ","tags":["concept","philosophy","FOSS"]},{"location":"docs/admin/","title":"Admin Guide","text":"
    The admin panel at /app is your command center for managing the entire platform. Use the sidebar to navigate between modules, or press Ctrl+K to open the command palette for quick access to any page, setting, or action.
    ","tags":["guide","admin"]},{"location":"docs/admin/#sections","title":"Sections","text":"
       
    •  
       Dashboard
       
      Live overview of platform activity, upcoming shifts, email stats, and service health.
       
      •  
    •  
       People & Access
       
      User management, roles, the People CRM, and contact merging.
       
      •  
    •  
       Advocacy
       
      Campaigns, response moderation, representative lookup, and email queue monitoring.
       
      •  
    •  
       Broadcast
       
      Newsletter sync, email templates, and SMS campaigns.
       
      •  
    •  
       Web Content
       
      Landing pages, homepage, navigation menu, and documentation management.
       
      •  
    •  
       Map & Canvassing
       
      Locations, areas, shifts, canvassing dashboard, data quality, and map settings.
       
      •  
    •  
       Media
       
      Video/photo library, analytics, playlists, comment moderation, and gallery ads.
       
      •  
    •  
       Payments
       
      Products, donations, subscription plans, and Stripe configuration.
       
      •  
    •  
       Services
       
      Tunnel management, monitoring, and third-party integrations.
       
      •  
    •  
       Settings
       
      Organization branding, theme colors, email config, feature toggles, and notifications.
       
      •  
    ","tags":["guide","admin"]},{"location":"docs/admin/#roles-reference","title":"Roles Reference","text":"Role Access Level SUPER_ADMIN Full platform access \u2014 implicitly bypasses all role checks INFLUENCE_ADMIN Campaigns, responses, representatives, email queue MAP_ADMIN Locations, areas, shifts, canvassing, data quality BROADCAST_ADMIN Newsletter sync, email templates CONTENT_ADMIN Landing pages, homepage, navigation, documentation MEDIA_ADMIN Video library, analytics, gallery, moderation, ads PAYMENTS_ADMIN Products, donations, plans, Stripe configuration EVENTS_ADMIN Gancio event sync and calendar management SOCIAL_ADMIN Social connections, achievements, calendar layers USER Volunteer portal only TEMP Limited volunteer access (auto-created on shift signup)","tags":["guide","admin"]},{"location":"docs/admin/dashboard/","title":"Dashboard","text":"
    The admin dashboard (/app) provides a real-time overview of platform activity.
     
    ","tags":["guide","admin"]},{"location":"docs/admin/dashboard/#dashboard-cards","title":"Dashboard Cards","text":"
       
    • Platform Stats \u2014 active campaigns, total emails sent, registered users, and location count
      •  
    • Activity Feed \u2014 recent events across all modules (signups, emails, visits, responses)
      •  
    • Upcoming Shifts \u2014 next scheduled volunteer shifts with signup counts
      •  
    • Newsletter Stats \u2014 Listmonk subscriber counts and recent campaign performance
      •  
    • Chat Activity \u2014 Rocket.Chat channel activity and online users (when chat is enabled)
      •  
    • Service Health \u2014 connectivity status for integrated services (Gitea, Gancio, Vaultwarden, etc.)
      •  
     
    All cards auto-refresh and gracefully degrade when their associated module is disabled.
    ","tags":["guide","admin"]},{"location":"docs/admin/people-access/","title":"People & Access","text":"
    Manage platform user accounts and roles, and use the People CRM to get a unified view of every supporter, donor, and volunteer across all modules.
     
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#user-management","title":"User Management","text":"","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#creating-users","title":"Creating Users","text":"
    Navigate to Users (/app/users) and click Add User. Fill in name, email, and role. The user will receive a welcome email with login instructions.
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#roles","title":"Roles","text":"Role Access Use Case SUPER_ADMIN Full platform access Campaign managers INFLUENCE_ADMIN Campaigns, responses, email queue Advocacy coordinators MAP_ADMIN Locations, areas, shifts, canvassing Field organizers USER Volunteer portal only Active volunteers TEMP Limited volunteer access Shift signups (auto-created)","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#password-policy","title":"Password Policy","text":"
    Passwords must be at least 12 characters with uppercase, lowercase, and a digit. This is enforced at the API schema level.
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#deactivating-users","title":"Deactivating Users","text":"
    Edit a user from the Users page and toggle their active status. Deactivated users cannot log in but their data is preserved. Banned users have their sessions invalidated immediately.
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#service-accounts-panel","title":"Service Accounts Panel","text":"
    When editing a user, the Service Accounts panel shows provisioning status for each integrated service (Rocket.Chat, Gitea, Vaultwarden, Listmonk). You can provision, deprovision, or re-sync individual services per user.
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#people-crm","title":"People CRM","text":"
    Enable with enablePeople in Settings. The People module serves as the platform's CRM, aggregating data from all other modules into a unified view.
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#virtual-aggregation","title":"Virtual Aggregation","text":"
    The People page does not store a separate \"people\" table. Instead, it aggregates records in real time from seven data sources:
     Source Data Users Platform accounts (name, email, phone, last login) Address Occupants Named residents from the map/canvassing module Campaign Senders People who sent advocacy emails Shift Signups Volunteer shift registrants SMS Contacts Contacts from SMS campaign lists Donations/Orders Buyers from the payments module Manual Contacts created directly in the CRM 
    Records are deduplicated by normalized email or phone number, with Users taking highest priority.
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#managed-contacts","title":"Managed Contacts","text":"
    Any virtual person can be \"promoted\" to a managed Contact record. This creates a persistent Contact entity in the database with:
     
       
    • Display name, first/last name \u2014 editable independently of the source
      •  
    • Tags \u2014 custom CRM tags for segmentation and filtering
      •  
    • Notes \u2014 free-text notes field
      •  
    • Support level \u2014 LEVEL_1 (Strong) through LEVEL_4 (Opposition)
      •  
    • Opt-out flags \u2014 email opt-out, SMS opt-out, and do-not-contact
      •  
    • Sign requested \u2014 track yard sign status
      •  
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#contact-details","title":"Contact Details","text":"
    Each managed contact supports multiple structured data entries:
     
       
    • Addresses \u2014 link to map locations with optional unit numbers and primary flag; new addresses can be auto-added to the map for geocoding
      •  
    • Emails \u2014 multiple email addresses with labels (e.g., Personal, Work) and primary designation
      •  
    • Phones \u2014 multiple phone numbers with labels and primary designation
      •  
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#activity-timeline","title":"Activity Timeline","text":"
    View a chronological timeline of all interactions for a person, across every module:
     
       
    • Advocacy emails sent and responses submitted
      •  
    • Shift signups and canvass visits
      •  
    • Donations and product purchases
      •  
    • SMS messages sent and received
      •  
    • Video views
      •  
    • Notes added and contact merges
      •  
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#duplicate-detection-and-merge","title":"Duplicate Detection and Merge","text":"
    The platform identifies potential duplicates by matching normalized email addresses and phone numbers across sources. The merge workflow lets you:
     
       
    • Select which fields to keep from the source vs. target contact
      •  
    • Merge tags, addresses, emails, and phones
      •  
    • Preserve the full audit trail (merged contacts are soft-linked, not deleted)
      •  
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#connection-graph","title":"Connection Graph","text":"
    Build a relationship graph between contacts using typed connections:
     
       
    • Connection types \u2014 Household, Family, Colleague, Referred By, and Custom
      •  
    • Bidirectional \u2014 connections can be one-way or mutual
      •  
    • Visual graph \u2014 interactive force-directed graph visualization showing contacts as nodes and connections as edges
      •  
    • Configurable depth \u2014 explore up to 3 degrees of separation
      •  
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#profile-links","title":"Profile Links","text":"
    Generate shareable public profile pages for contacts:
     
       
    • Unique token URLs at /profile/:token
      •  
    • Configurable expiration \u2014 24 hours, 7 days, 30 days, 90 days, 1 year, or never
      •  
    • Optional password protection \u2014 require a PIN or password to view
      •  
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#household-detection","title":"Household Detection","text":"
    The Household panel groups contacts who share the same physical address, making it easy to see all members of a household and their combined engagement.
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#create-user-from-contact","title":"Create User from Contact","text":"
    Promote a CRM contact to a full platform user account directly from the People interface, with role assignment and optional welcome email.
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/people-access/#admin-routes","title":"Admin Routes","text":"
       
    • /app/users \u2014 user CRUD, role assignment, service accounts
      •  
    • /app/people \u2014 contact list with search, filters, source/tag filtering, and bulk actions
      •  
    ","tags":["guide","admin","CRM"]},{"location":"docs/admin/settings/","title":"Platform Settings","text":"
    Centralized configuration for organization identity, theming, email delivery, feature modules, and automated notifications.
     
    ","tags":["guide","admin","configuration"]},{"location":"docs/admin/settings/#settings-tabs","title":"Settings Tabs","text":"","tags":["guide","admin","configuration"]},{"location":"docs/admin/settings/#organization","title":"Organization","text":"
    Configure your organization's public identity:
     
       
    • Organization Name \u2014 displayed in the admin sidebar, public pages, and emails
      •  
    • Short Name \u2014 shown when the admin sidebar is collapsed (max 10 characters)
      •  
    • Logo URL \u2014 displayed on the login page, homepage hero, and public navigation
      •  
    • Favicon URL \u2014 browser tab icon
      •  
    • Footer Text \u2014 shown in public page footers
      •  
    • Login Subtitle \u2014 displayed below the organization name on the login page
      •  
    ","tags":["guide","admin","configuration"]},{"location":"docs/admin/settings/#theme-colors","title":"Theme Colors","text":"
    Customize the look of admin and public interfaces:
     
    Admin theme:
     
       
    • Primary color (accent color for buttons, links, active states)
      •  
    • Background color (page background)
      •  
     
    Public theme:
     
       
    • Primary color
      •  
    • Background color
      •  
    • Container color (card and section backgrounds)
      •  
    • Header gradient (CSS gradient string for the public navigation bar)
      •  
     
    A live preview panel shows color swatches and a gradient preview as you configure.
    ","tags":["guide","admin","configuration"]},{"location":"docs/admin/settings/#email","title":"Email","text":"
    Configure how the platform sends emails:
     
       
    • Sender \u2014 from name and from address for all outgoing emails
      •  
    • Active SMTP provider \u2014 toggle between MailHog (testing) and Production SMTP with a single click
      •  
    • Production SMTP \u2014 host, port, username, and password (collapsible panel, disabled when MailHog is active)
      •  
    • Test mode \u2014 when enabled, all emails redirect to a single test recipient address
      •  
    • Test actions \u2014 \"Test Connection\" verifies SMTP connectivity; \"Send Test Email\" delivers a test message through the active provider
      •  
     
    A configuration summary card at the top displays the current provider, server, authentication status, and test mode state.
    ","tags":["guide","admin","configuration"]},{"location":"docs/admin/settings/#feature-toggles","title":"Feature Toggles","text":"
    Enable or disable platform modules. Disabling a module hides it from navigation but does not delete data.
     Category Flag Description Core Platform enableInfluence Advocacy campaigns, email sending, response wall enableMap Map, locations, canvassing, volunteer shifts enableNewsletter Listmonk newsletter sync enableLandingPages GrapesJS landing page builder Media & Content enableMediaFeatures Video library, public gallery, analytics enableGalleryAds Promotional cards in the video gallery enableEvents Gancio event calendar integration Communication enableChat Rocket.Chat team coordination enableMeet Jitsi video meetings (integrates with Rocket.Chat) enableSms Termux Android SMS campaigns People & Engagement enablePeople Unified contacts CRM enableSocial Volunteer social connections and activity feeds autoSyncPeopleToMap Auto-create map locations from contact addresses Commerce enablePayments Stripe subscriptions, products, and donations","tags":["guide","admin","configuration"]},{"location":"docs/admin/settings/#notifications","title":"Notifications","text":"
    Control which automated email notifications the platform sends. Disabling a notification stops future emails but does not affect already-queued jobs.
     
    Admin alerts:
     
       
    • New shift signup
      •  
    • Response wall submission
      •  
    • Yard sign request (from canvassing)
      •  
    • Shift cancellation
      •  
     
    Volunteer emails:
     
       
    • Canvass session summary (sent after completing a session)
      •  
    • Signup cancellation confirmation
      •  
    • 24-hour pre-shift reminder
      •  
    • Post-shift thank-you (sent 2 hours after shift ends)
      •  
     
    Re-engagement:
     
       
    • Re-engagement emails for inactive volunteers
      •  
    • Configurable inactivity threshold (days without activity)
      •  
    • Configurable cooldown period (minimum days between re-engagement emails)
      •  
    ","tags":["guide","admin","configuration"]},{"location":"docs/admin/settings/#admin-routes","title":"Admin Routes","text":"
       
    • /app/settings \u2014 multi-tab settings page (supports deep-linking to a specific tab via router state)
      •  
    ","tags":["guide","admin","configuration"]},{"location":"docs/admin/advocacy/","title":"Advocacy","text":"
    The advocacy module helps supporters contact their elected representatives through email campaigns.
    ","tags":["guide","admin","influence"]},{"location":"docs/admin/advocacy/#in-this-section","title":"In This Section","text":"
       
    • Campaigns \u2014 create and publish advocacy campaigns with postal code lookup and response tracking
      •  
    • Responses \u2014 moderate the public response wall where supporters share representative replies
      •  
    • Representatives \u2014 manage the representative lookup cache powered by the Represent API
      •  
    • Email Queue \u2014 monitor outgoing advocacy emails, retry failures, and view delivery stats
      •  
    ","tags":["guide","admin","influence"]},{"location":"docs/admin/advocacy/campaigns/","title":"Advocacy Campaigns","text":"
    Help supporters contact their elected representatives through email campaigns.
     
    ","tags":["guide","admin","influence","campaigns"]},{"location":"docs/admin/advocacy/campaigns/#how-it-works","title":"How It Works","text":"
       
    1. An admin creates a campaign \u2014 writes the email subject and body, selects which government levels to target (federal, provincial, municipal, school board), and publishes it.
      2.  
    2. A supporter visits the campaign page \u2014 enters their postal code to look up their representatives.
      3.  
    3. The supporter sends the email \u2014 either directly through the platform (\"Send Now\") or by opening it in their own email app (Gmail, Outlook, etc.).
      4.  
    4. Responses get tracked \u2014 supporters and admins can share representative responses on the Response Wall, with upvoting and moderation.
      5.  
    ","tags":["guide","admin","influence","campaigns"]},{"location":"docs/admin/advocacy/campaigns/#key-features","title":"Key Features","text":"
       
    • Postal code lookup \u2014 powered by the Represent API, returns representatives at all government levels
      •  
    • Two send methods \u2014 server-sent SMTP (tracked) or mailto link (opens user's email app)
      •  
    • Email editing \u2014 optionally let supporters personalize the email before sending
      •  
    • Response Wall \u2014 public wall where people share how their representatives responded, with moderation and verification
      •  
    • Campaign stats \u2014 track emails sent, responses received, and upvotes
      •  
    • Featured campaigns \u2014 highlight important campaigns on the public listing page
      •  
    ","tags":["guide","admin","influence","campaigns"]},{"location":"docs/admin/advocacy/campaigns/#user-submitted-campaigns","title":"User-Submitted Campaigns","text":"
    Registered (non-temporary) users can create their own advocacy campaigns and submit them for admin review.
     
       
    • Public submission route \u2014 users visit /campaigns/create to draft a campaign through a guided wizard
      •  
    • 3-step wizard \u2014 the submission flow walks users through campaign details (title, description, government levels), email template (subject and body), and a final review step before submitting
      •  
    • My campaigns dashboard \u2014 users can view and manage their submitted campaigns at /campaigns/mine, including checking moderation status and editing campaigns that have been sent back for changes
      •  
    • Restricted fields \u2014 user-submitted campaigns have limited options compared to admin-created ones (no SMTP sending, no highlight, no custom recipients); only the mailto link fallback is enabled by default
      •  
    • Auto-moderation status \u2014 newly submitted campaigns start in PENDING_REVIEW status and remain in DRAFT until an admin approves them
      •  
    • Edit restrictions \u2014 users can only edit their own campaigns, and only when the moderation status is PENDING_REVIEW or CHANGES_REQUESTED; editing automatically resets the status back to PENDING_REVIEW
      •  
    • Rate limiting \u2014 campaign submissions are rate-limited to 5 per hour per IP to prevent abuse
      •  
    • XSS protection \u2014 all user-supplied text (title, description, email subject, email body) is HTML-escaped before storage
      •  
    ","tags":["guide","admin","influence","campaigns"]},{"location":"docs/admin/advocacy/campaigns/#campaign-moderation","title":"Campaign Moderation","text":"
    Admins review user-submitted campaigns before they go live.
     
       
    • Moderation queue \u2014 accessible at /app/campaign-moderation, showing all user-generated campaigns filtered by moderation status (pending, approved, rejected, changes requested)
      •  
    • Moderation actions \u2014 for each campaign in the queue, admins can:
         
      • Approve \u2014 sets the moderation status to APPROVED and the campaign status to ACTIVE, making it publicly visible
        •  
      • Reject \u2014 marks the campaign as REJECTED with an optional reason visible to the submitter
        •  
      • Request changes \u2014 sets the status to CHANGES_REQUESTED with feedback, allowing the user to revise and resubmit
        •  
       
      •  
    • Moderation stats \u2014 the queue page displays counters for total user-generated campaigns, pending reviews, approved, rejected, and changes-requested counts
      •  
    • Reviewer tracking \u2014 each moderation action records the reviewer's user ID and timestamp
      •  
    • Search and filter \u2014 the moderation queue supports searching by campaign title, submitter name, or email, and filtering by moderation status
      •  
    ","tags":["guide","admin","influence","campaigns"]},{"location":"docs/admin/advocacy/campaigns/#campaign-analytics","title":"Campaign Analytics","text":"
    The Campaign Effectiveness dashboard provides cross-campaign performance analytics at /app/influence/effectiveness.
     
       
    • Performance tab \u2014 per-campaign KPIs including total emails sent, email delivery status breakdown, response counts, response rates, and call counts; top campaigns visualized as a horizontal bar chart
      •  
    • Representatives tab \u2014 tracks individual representative responsiveness across all campaigns; shows emails received, responses given, verified response count, and response rate per representative; sortable by response count, response rate, or name; includes government level distribution
      •  
    • Geography tab \u2014 engagement breakdown by geographic area; group results by postal code, city, or province; enriched with city/province data from the postal code cache
      •  
    • Funnel tab \u2014 conversion funnel visualization showing progression from emails sent to unique participants to responses received to verified responses, plus calls made; includes percentage-of-first and stage-to-stage dropoff rates
      •  
    • Trends tab \u2014 time-series activity chart showing daily or weekly email and response volumes; default view covers the last 30 days; merged email and response series for side-by-side comparison
      •  
    • Global filters \u2014 all tabs share campaign and date range filters; select a specific campaign or view aggregate data across all campaigns
      •  
    ","tags":["guide","admin","influence","campaigns"]},{"location":"docs/admin/advocacy/campaigns/#admin-routes","title":"Admin Routes","text":"
       
    • /app/campaigns \u2014 create, edit, and manage campaigns
      •  
    • /app/campaign-moderation \u2014 review and moderate user-submitted campaigns
      •  
    • /app/influence/effectiveness \u2014 campaign effectiveness analytics dashboard
      •  
    • /app/responses \u2014 moderate submitted responses
      •  
    • /app/email-queue \u2014 monitor outgoing email delivery
      •  
    ","tags":["guide","admin","influence","campaigns"]},{"location":"docs/admin/advocacy/campaigns/#public-routes","title":"Public Routes","text":"
       
    • /campaigns \u2014 browse active campaigns
      •  
    • /campaigns/create \u2014 submit a new user-generated campaign (requires login)
      •  
    • /campaigns/mine \u2014 view and manage your submitted campaigns (requires login)
      •  
    • /campaign/:slug \u2014 take action on a specific campaign
      •  
    • /campaign/:slug/responses \u2014 view the response wall
      •  
    ","tags":["guide","admin","influence","campaigns"]},{"location":"docs/admin/advocacy/email-queue/","title":"Email Queue","text":"
    Monitor outgoing advocacy emails processed through the BullMQ queue.
     
    ","tags":["guide","admin","influence","email"]},{"location":"docs/admin/advocacy/email-queue/#key-features","title":"Key Features","text":"
       
    • Queue dashboard \u2014 view pending, active, completed, and failed jobs at /app/email-queue
      •  
    • Job details \u2014 inspect individual email jobs with recipient, subject, status, and timestamps
      •  
    • Retry failed jobs \u2014 re-queue emails that failed due to SMTP errors or timeouts
      •  
    • Clear completed \u2014 bulk-remove completed jobs to keep the queue clean
      •  
    • Stats \u2014 total sent, delivery rate, and average processing time
      •  
    ","tags":["guide","admin","influence","email"]},{"location":"docs/admin/advocacy/email-queue/#admin-routes","title":"Admin Routes","text":"
       
    • /app/email-queue \u2014 email queue monitoring and management
      •  
    ","tags":["guide","admin","influence","email"]},{"location":"docs/admin/advocacy/representatives/","title":"Representatives","text":"
    The platform uses the Represent API to look up elected representatives by postal code across all government levels.
     
    ","tags":["guide","admin","influence"]},{"location":"docs/admin/advocacy/representatives/#how-it-works","title":"How It Works","text":"
       
    • Postal code lookup \u2014 enter a Canadian postal code to retrieve federal, provincial, municipal, and school board representatives
      •  
    • Redis cache \u2014 lookup results are cached to reduce API calls and improve response times
      •  
    • Cache management \u2014 view cache status and clear entries from /app/representatives
      •  
    • Government levels \u2014 campaigns can target specific levels (federal, provincial, municipal, school board)
      •  
    ","tags":["guide","admin","influence"]},{"location":"docs/admin/advocacy/representatives/#admin-routes","title":"Admin Routes","text":"
       
    • /app/representatives \u2014 representative cache management and lookup testing
      •  
    ","tags":["guide","admin","influence"]},{"location":"docs/admin/advocacy/responses/","title":"Response Moderation","text":"
    Review and moderate representative responses submitted by supporters on the public response wall.
     
    ","tags":["guide","admin","influence","moderation"]},{"location":"docs/admin/advocacy/responses/#key-features","title":"Key Features","text":"
       
    • Moderation queue \u2014 review submissions at /app/responses with filtering by campaign and status
      •  
    • Verification \u2014 mark responses as verified to display a trust badge on the public wall
      •  
    • Upvoting \u2014 supporters can upvote responses; counts are visible on the public wall
      •  
    • Approve / reject \u2014 control which responses appear publicly
      •  
    • Response stats \u2014 track response counts per campaign and per representative
      •  
    ","tags":["guide","admin","influence","moderation"]},{"location":"docs/admin/advocacy/responses/#admin-routes","title":"Admin Routes","text":"
       
    • /app/responses \u2014 response moderation dashboard
      •  
    ","tags":["guide","admin","influence","moderation"]},{"location":"docs/admin/broadcast/","title":"Broadcast","text":"
    Reach supporters through multiple channels \u2014 email newsletters, templated campaigns, and SMS text messages.
    ","tags":["guide","admin","broadcast"]},{"location":"docs/admin/broadcast/#in-this-section","title":"In This Section","text":"
       
    • Newsletter \u2014 Listmonk integration with automatic subscriber sync from shifts, campaigns, and contacts
      •  
    • Email Templates \u2014 reusable templates with variable substitution, version history, and test sending
      •  
    • SMS \u2014 text message campaigns via a Termux Android bridge with contact lists and response tracking
      •  
    ","tags":["guide","admin","broadcast"]},{"location":"docs/admin/broadcast/email-templates/","title":"Email Templates","text":"
    Create reusable email templates with variable substitution for campaign communications. Templates are used by advocacy campaigns, shift confirmations, volunteer re-engagement emails, and other automated communications.
     
    ","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/email-templates/#template-categories","title":"Template Categories","text":"
    Each template belongs to a category that determines where it can be used:
     
       
    • INFLUENCE -- advocacy campaign emails sent to representatives
      •  
    • MAP -- shift confirmation, volunteer thank-you, and canvassing-related emails
      •  
    • SYSTEM -- account verification, password reset, and platform notifications
      •  
    • PAYMENT -- donation receipts, subscription confirmations, and purchase orders
      •  
    ","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/email-templates/#variable-system","title":"Variable System","text":"
    Templates use Handlebars-style {{VARIABLE_NAME}} placeholders that are replaced at send time. Variables must use uppercase letters and underscores (e.g., {{RECIPIENT_NAME}}, {{CAMPAIGN_TITLE}}).
     
       
    • Text variables -- simple string substitution for names, dates, URLs, and other text
      •  
    • Video variables -- embed a media library video by referencing its ID
      •  
    • Conditional blocks -- show or hide content with {{#if VARIABLE}}...{{/if}} syntax
      •  
    • Required vs optional -- each variable can be marked as required, with sample values for test emails
      •  
     
    The template validator automatically extracts all variables from the HTML, text, and subject line content and checks for unmatched conditional blocks.
    ","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/email-templates/#version-history","title":"Version History","text":"
    Every change to a template's subject line, HTML content, or text content creates a new version. The full version history is preserved, and any previous version can be restored:
     
       
    • Version browsing -- view the subject, HTML, and text content of any past version
      •  
    • Rollback -- restore a previous version (creates a new version entry, preserving the audit trail)
      •  
    • Change notes -- each version includes a description of what changed
      •  
    • Author tracking -- versions record which admin made each change
      •  
    ","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/email-templates/#test-emails","title":"Test Emails","text":"
    Before activating a template, send a test email to verify rendering:
     
       
    • Variable substitution -- provide test data for each variable to preview the final output
      •  
    • Recipient selection -- send the test to any email address
      •  
    • Test log -- all test sends are logged with success/failure status and message IDs
      •  
    • Rate limited -- 10 test emails per 15 minutes per user to prevent abuse
      •  
    ","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/email-templates/#template-caching","title":"Template Caching","text":"
    Rendered templates are cached in memory for performance. The cache is automatically cleared when a template is created, updated, or deleted. Admins can also manually clear the cache from the admin interface.
    ","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/email-templates/#admin-routes","title":"Admin Routes","text":"
       
    • /app/email-templates -- create and manage email templates with a visual editor
      •  
    ","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/newsletter/","title":"Newsletter (Listmonk)","text":"
    Integrated with Listmonk for opt-in mailing lists and newsletter campaigns. Enable with LISTMONK_SYNC_ENABLED=true.
     
    ","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/newsletter/#managed-lists","title":"Managed Lists","text":"
    The platform automatically creates and maintains 13 subscriber lists in Listmonk:
     List Name Source Tags All Contacts All synced records v2 Campaign Participants Users who sent advocacy emails v2, influence Locations - All Address occupants with email v2, map Support Level 1-4 Addresses by canvass support level v2, map, support Has Campaign Sign Addresses with a yard sign v2, map, signs Users Active non-temp platform accounts v2, users Volunteers Shift signups v2, map, shifts Canvassers Users who completed canvass sessions v2, map, canvass Subscribers Active paid subscribers v2, payments Donors Users who completed a donation v2, payments","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/newsletter/#bulk-sync","title":"Bulk Sync","text":"
    The admin panel provides a manual \"Sync All\" action that synchronizes four data sources to Listmonk:
     
       
    1. Campaign participants -- distinct email senders from advocacy campaigns
      2.  
    2. Location contacts -- address occupants with email, mapped to support level and sign lists
      3.  
    3. Users -- active platform accounts (excludes TEMP users)
      4.  
    4. CRM tags -- contacts tagged in the People module, synced to tag-linked Listmonk lists
      5.  
     
    Each source upserts subscribers (creates new or merges into existing), preserving existing list memberships and merging metadata attributes.
    ","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/newsletter/#event-driven-sync","title":"Event-Driven Sync","text":"
    In addition to bulk sync, the platform fires real-time subscriber upserts on application events:
     
       
    • Shift signup -- adds to Volunteers list
      •  
    • Canvass session completed -- adds to Canvassers list
      •  
    • Campaign email sent -- adds to Campaign Participants list
      •  
    • Subscription activated -- adds to Subscribers list
      •  
    • Donation completed -- adds to Donors list
      •  
    • Product purchased -- adds to Donors list
      •  
    • Address updated (canvass visit) -- updates support level list membership
      •  
    • Re-engagement email sent -- updates Volunteers list metadata
      •  
    • CRM tag changed -- adds/removes from tag-linked Listmonk lists
      •  
     
    All event-driven syncs are fire-and-forget and silently fail if Listmonk is unreachable.
    ","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/newsletter/#admin-routes","title":"Admin Routes","text":"
       
    • /app/listmonk (sidebar: \"Newsletter\") -- sync status, subscriber counts, campaign stats, and manual sync trigger
      •  
    ","tags":["guide","admin","broadcast","email"]},{"location":"docs/admin/broadcast/sms/","title":"SMS Campaigns","text":"
    Text message outreach via a Termux Android bridge. Uses a real Android phone to send and receive SMS \u2014 no third-party SMS gateway or Twilio account needed.
     
     
    Enable with ENABLE_SMS=true or via the setup wizard.
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#architecture-overview","title":"Architecture Overview","text":"
    The SMS system uses a three-tier architecture where your server communicates with a lightweight Python Flask API running on an Android phone:
     
    graph LR\n    A[Admin Dashboard<br/>Campaign UI] -->|API calls| B[Express API<br/>BullMQ Queue]\n    B -->|HTTP + API Key| C[Android Phone<br/>Flask on Termux]\n    C -->|termux-sms-send| D[Android SMS]\n    D -->|Carrier Network| E[Recipients]\n    E -->|Reply SMS| D\n    D -->|termux-sms-list| C\n    C -->|HTTP response| B
     
    Why this approach?
     
       
    • No SaaS dependency \u2014 your phone is the SMS gateway, no Twilio/MessageBird/etc.
      •  
    • Real phone number \u2014 recipients see a real number, not a short code
      •  
    • Two-way messaging \u2014 incoming replies sync automatically
      •  
    • Low cost \u2014 just your phone plan's SMS allowance
      •  
    • Full control \u2014 FOSS stack end-to-end
      •  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#prerequisites","title":"Prerequisites","text":"
    Before starting setup, you'll need:
     Item Details Android phone Any Android 7+ device with an active SIM card and SMS plan Termux Terminal emulator \u2014 install from F-Droid (not Play Store) Termux:API Termux plugin for SMS/contacts/battery \u2014 install from F-Droid Tailscale (recommended) VPN mesh for stable IP \u2014 install from Play Store Network access Phone must be reachable from the server (Tailscale, LAN, or port forwarding) 
    Both Apps MUST Come from F-Droid
     
    The Play Store version of Termux is abandoned and incompatible with the API plugin. If you install Termux from the Play Store and Termux:API from F-Droid (or vice versa), SMS commands will fail with:
     
    Termux:API is not yet available on Google Play
     
    Fix: Uninstall both apps, then reinstall both from F-Droid. They must come from the same source because Android verifies matching app signatures for inter-process communication.
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#phone-setup","title":"Phone Setup","text":"","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#step-1-install-apps-from-f-droid","title":"Step 1: Install Apps from F-Droid","text":"
    On your Android phone:
     
       
    1. Install F-Droid \u2014 download from f-droid.org if you don't have it
      2.  
    2. Install Termux \u2014 search in F-Droid and install
      3.  
    3. Install Termux:API \u2014 search in F-Droid and install
      4.  
    4. Install Termux:Boot (optional) \u2014 for auto-start on phone reboot. Open once after install to register.
      5.  
    5. Install Tailscale (recommended) \u2014 from Play Store, connect to your tailnet for a stable IP
      6.  
     
    termux-api package
     
    You need two things called \"termux-api\": the F-Droid app (Termux:API) and the Termux package (pkg install termux-api). The setup script installs the package automatically, but the F-Droid app must be installed manually.
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#step-2-generate-api-key","title":"Step 2: Generate API Key","text":"
    Go to the admin dashboard SMS Setup page (/app/sms/setup) and click Generate API Key. Copy the key \u2014 you'll paste it into the setup command.
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#step-3-run-the-setup-script","title":"Step 3: Run the Setup Script","text":"
    Open Termux on the phone and run:
     
    # Clone the SMS server (first time only)\npkg install -y git && git clone https://gitea.bnkops.com/admin/campaign_connector.git ~/sms-server\n\n# Run the setup script \u2014 paste your API key at the end\nbash ~/sms-server/android/setup.sh YOUR_API_KEY_HERE\n
     
    The setup script automatically:
     
       
    • Installs Python, Flask, termux-api, and openssh
      •  
    • Saves the API key to ~/.bashrc
      •  
    • Requests SMS and Contacts permissions (tap Allow when prompted)
      •  
    • Creates a Termux:Boot auto-start script (if Termux:Boot is installed)
      •  
    • Starts the SMS server
      •  
     
    When done, note the Phone URL displayed (e.g. http://100.64.0.5:5001).
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#recommended-install-service-supervisor","title":"Recommended: Install Service Supervisor","text":"
    After initial setup, install termux-services for reliable process management. This uses runit, a proper UNIX service supervisor that automatically restarts the server if it crashes:
     
    cd ~/sms-server && bash android/setup-services.sh\n
     
    This registers two supervised services:
     
       
    • sms-api \u2014 Flask SMS API server (port 5001)
      •  
    • sshd-custom \u2014 SSH daemon for remote management (port 8022)
      •  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#step-4-prevent-android-from-killing-termux","title":"Step 4: Prevent Android from Killing Termux","text":"
    This is required for the server to run reliably in the background:
     
       
    1. Open Android Settings \u2192 Apps \u2192 Termux \u2192 Battery \u2192 set to Unrestricted
      2.  
    2. Lock Termux in the recent apps view (long-press the app card \u2192 Lock/Pin)
      3.  
    3. Samsung phones: also add Termux to Settings \u2192 Device Care \u2192 Battery \u2192 Never Sleeping Apps
      4.  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#updating","title":"Updating","text":"
    To pull the latest server code and re-run setup:
     
    cd ~/sms-server && git pull && bash android/setup.sh YOUR_API_KEY_HERE\n
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#service-management","title":"Service Management","text":"
    If you installed termux-services (recommended):
     
    # Check status\nsv status sms-api\n\n# Restart\nsv restart sms-api\n\n# Stop\nsv down sms-api\n\n# Start\nsv up sms-api\n\n# View logs\ntail -f ~/logs/sms-api.log\n\n# Health check\ncurl http://127.0.0.1:5001/health\n
     
    Without termux-services (legacy watchdog):
     
    # Check if the server is running\ncurl http://127.0.0.1:5001/health\n\n# Restart manually\ncd ~/sms-server/android && bash sms-watchdog.sh\n
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#accessing-the-phone","title":"Accessing the Phone","text":"
    There are several ways to run commands on the phone:
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#direct-on-phone","title":"Direct (on phone)","text":"
    Simply open the Termux app and type commands. Best for initial setup.
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#ssh-remote-access","title":"SSH (remote access)","text":"
    Start the SSH server in Termux, then connect from your computer:
     
    # On the phone (first time only):\npkg install openssh\npasswd  # Set a password\nsshd    # Start SSH server on port 8022\n\n# From your computer:\nssh -p 8022 your-phone-ip\n# Or with Tailscale:\nssh -p 8022 100.x.x.x\n
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#scrcpy-screen-mirror","title":"scrcpy (screen mirror)","text":"
    Mirror the phone screen to your computer \u2014 great for setup:
     
    # Install scrcpy on your computer (Ubuntu)\nsudo apt install scrcpy\n\n# Connect via USB\nscrcpy\n\n# Or wireless (phone must be on same network)\nscrcpy --tcpip=phone-ip:5555\n
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#setup-wizard","title":"Setup Wizard","text":"
    The admin panel provides a guided three-step wizard at /app/sms/setup:
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#step-1-prepare-phone","title":"Step 1: Prepare Phone","text":"
    Walks you through installing apps, cloning the server, setting the API key, and starting the Flask server. Generates a shared API key that both the server and phone use for authentication.
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#step-2-connect","title":"Step 2: Connect","text":"
    Choose how to find your phone's IP address:
     Tailscale Auto-Discovery (Recommended)Manual URL Entry 
       
    1. Enter your Tailscale API key (tskey-api-...)
      2.  
    2. Click Discover Devices
      3.  
    3. The wizard queries the Tailscale API and lists all devices on your tailnet
      4.  
    4. Select your Android phone \u2014 the URL auto-fills with its stable 100.x.x.x IP
      5.  
     
    Getting a Tailscale API Key
     
    Go to Tailscale Admin Console \u2192 Settings \u2192 Keys \u2192 Generate auth key or API access token.
     
    Enter the phone's URL directly:
     
       
    • With Tailscale: http://100.x.x.x:5001 (stable IP, works across networks)
      •  
    • On same LAN: http://192.168.x.x:5001 (changes if phone reconnects)
      •  
    • Via port forward: http://your-public-ip:5001 (requires router config)
      •  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#step-3-test-save","title":"Step 3: Test & Save","text":"
       
    1. Click Test Connection \u2014 the wizard calls the phone's /health endpoint
      2.  
    2. On success, you'll see device uptime and message count
      3.  
    3. Click Save Configuration \u2014 stores the URL and key encrypted in the database
      4.  
    4. The enableSms feature flag is automatically enabled
      5.  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#how-it-works","title":"How It Works","text":"","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#sending-messages","title":"Sending Messages","text":"
       
    1. Admin creates an SMS campaign with a message template and contact list
      2.  
    2. Campaign is started \u2192 messages are queued in BullMQ (one at a time, serial delivery)
      3.  
    3. For each message, the Express API calls POST /api/sms/send on the phone
      4.  
    4. The Flask server on the phone executes termux-sms-send to send via Android's native SMS
      5.  
    5. A notification appears on the phone for each sent message
      6.  
    6. Results are tracked in the database (success/failure per recipient)
      7.  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#receiving-responses","title":"Receiving Responses","text":"
    A background service (sms-response-sync.service.ts) polls the phone's inbox at a configurable interval:
     
       
    1. Calls GET /api/sms/inbox?since=<last_sync_timestamp> on the phone
      2.  
    2. The Flask server runs termux-sms-list to get new messages
      3.  
    3. Incoming messages are matched to contacts and classified by keyword
      4.  
    4. Threaded conversations are maintained per contact
      5.  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#device-monitoring","title":"Device Monitoring","text":"
    A background service (sms-device-monitor.service.ts) checks phone health periodically:
     
       
    • Battery level, charging status, temperature
      •  
    • Server uptime and total messages sent
      •  
    • Connection status (available/unreachable)
      •  
    • Results displayed on the SMS Dashboard
      •  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#key-features","title":"Key Features","text":"
       
    • Contact lists \u2014 import, tag, and segment contacts for targeted outreach
      •  
    • Message templates \u2014 reusable templates with {name} variable placeholders
      •  
    • BullMQ queue \u2014 serial delivery with configurable delays between messages
      •  
    • Response sync \u2014 incoming SMS replies synced and classified automatically
      •  
    • Device monitoring \u2014 battery, uptime, and connectivity reported in real-time
      •  
    • Conversation view \u2014 threaded message history per contact
      •  
    • Retry logic \u2014 configurable retry attempts for failed deliveries
      •  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#admin-routes","title":"Admin Routes","text":"Route Description /app/sms/setup Guided setup wizard with Tailscale auto-discovery /app/sms SMS dashboard \u2014 campaign overview and device status /app/sms/contacts Manage contact lists and entries /app/sms/campaigns Create and monitor SMS campaigns /app/sms/conversations View threaded conversations with contacts","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#configuration","title":"Configuration","text":"","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#environment-variables","title":"Environment Variables","text":"Variable Default Description ENABLE_SMS false Feature flag (also set via setup wizard) TERMUX_API_URL \u2014 Phone URL, e.g. http://100.x.x.x:5001 TERMUX_API_KEY \u2014 Shared API key for authentication SMS_DELAY_BETWEEN_MS 1000 Delay between messages in a campaign (ms) SMS_MAX_RETRIES 3 Retry attempts for failed sends SMS_RESPONSE_SYNC_INTERVAL_MS 10000 How often to check for incoming replies (ms) SMS_DEVICE_MONITOR_INTERVAL_MS 30000 How often to check device health (ms) TAILSCALE_API_KEY \u2014 Tailscale API key for auto-discovery TAILSCALE_TAILNET \u2014 Tailscale tailnet name (optional) 
    Note
     
    When you use the setup wizard, configuration is stored in the database and takes priority over environment variables. You don't need to set env vars if you use the wizard.
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#phone-side-configuration","title":"Phone-Side Configuration","text":"
    On the phone, only one environment variable is needed:
     
    export SMS_API_SECRET='your-64-char-hex-key'\n
     
    The Flask server also accepts TERMUX_API_KEY as an alias for backwards compatibility.
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#phone-api-endpoints","title":"Phone API Endpoints","text":"
    The Flask server running on the phone exposes these endpoints on port 5001:
     Method Endpoint Auth Description GET /health No Server status, uptime, messages sent GET / No Web dashboard with endpoint documentation POST /api/sms/send Yes Send an SMS message POST /api/sms/send-reply Yes Send a reply with conversation tracking GET /api/sms/inbox No Get incoming messages (with since filter) GET /api/sms/list No List messages with pagination GET /api/sms/history No Get SMS history for a phone number GET /api/device/battery No Battery level, health, temperature GET /api/device/location No GPS coordinates (requires permission) GET /api/device/info No Device info + battery + uptime GET /api/contacts/list No Phone address book (with search) POST /api/campaign/notify No Push notification to device 
    Authentication uses the X-API-Key header with the shared secret.
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#troubleshooting","title":"Troubleshooting","text":"","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#phone-cant-be-reached","title":"Phone can't be reached","text":"
    Symptoms: Test connection fails, \"Connection refused\" or timeout.
     
    Checks:
     
       
    1. Is the Flask server running? Check Termux \u2014 you should see the startup banner
      2.  
    2. Is the IP correct? Run ifconfig in Termux to find the current IP
      3.  
    3. Are they on the same network? If not using Tailscale, both must be on the same LAN
      4.  
    4. Is Tailscale connected? Check the Tailscale app on the phone \u2014 it should show \"Connected\"
      5.  
    5. Firewall? Android rarely blocks incoming connections on Termux, but check if any firewall app is installed
      6.  
     
    # Quick test from your server\ncurl http://PHONE_IP:5001/health\n
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#authentication-required-errors","title":"\"Authentication required\" errors","text":"
    Symptoms: API calls return 401 with \"Authentication required\".
     
    Fix: The API key on the phone doesn't match the one in the admin panel.
     
    # On the phone, check the current key\necho $SMS_API_SECRET\n\n# If it doesn't match, update it\nexport SMS_API_SECRET='correct-key-from-admin-panel'\necho 'export SMS_API_SECRET=\"correct-key-from-admin-panel\"' >> ~/.bashrc\n\n# Restart the server\nsv restart sms-api\n# Or without termux-services: pkill -f termux-sms-api-server.py && cd ~/sms-server/android && python termux-sms-api-server.py\n
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#sms-not-sending","title":"SMS not sending","text":"
    Symptoms: Server responds successfully but messages don't arrive.
     
    Checks:
     
       
    1. SMS permissions granted? Go to Android Settings \u2192 Apps \u2192 Termux:API \u2192 Permissions \u2192 SMS
      2.  
    2. Active SIM card? The phone needs a working SIM with SMS capability
      3.  
    3. Message too long? Maximum 1600 characters per message
      4.  
    4. Rate limited? Minimum 1 second between messages (carrier may enforce longer delays)
      5.  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#termux-keeps-getting-killed","title":"Termux keeps getting killed","text":"
    Symptoms: Server stops after some time, especially when phone screen is off.
     
    Fix:
     
       
    1. Install termux-services (if not already): bash ~/sms-server/android/setup-services.sh \u2014 this uses runit, a proper service supervisor that auto-restarts the server immediately if it crashes
      2.  
    2. Disable battery optimization: Android Settings \u2192 Apps \u2192 Termux \u2192 Battery \u2192 Unrestricted
      3.  
    3. Lock Termux in recent apps \u2014 long-press the app card \u2192 Lock/Pin
      4.  
    4. Samsung: also add Termux, Termux:API, and Termux:Boot to Settings \u2192 Device Care \u2192 Battery \u2192 Never Sleeping Apps
      5.  
    5. Acquire wake lock: Run termux-wake-lock in Termux (included in boot script)
      6.  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#server-wont-start-missing-sms_api_secret","title":"Server won't start \u2014 \"Missing SMS_API_SECRET\"","text":"
    Symptoms: Server exits immediately with a security error.
     
    Fix: Set the API key environment variable:
     
    # Generate a new key if you don't have one\npython -c \"import secrets; print(secrets.token_hex(32))\"\n\n# Set it\nexport SMS_API_SECRET='your-generated-key'\necho 'export SMS_API_SECRET=\"your-key\"' >> ~/.bashrc\n
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#rcs-chat-features-interfering-with-replies","title":"RCS / Chat Features interfering with replies","text":"
    Symptoms: You send SMS messages successfully but some or all replies never appear in the system. Recipients say they replied, but the conversation shows no inbound messages.
     
    Cause: Google Messages enables RCS (Rich Communication Services) by default. When RCS is active, replies from recipients who also have RCS may be sent over data/Wi-Fi instead of the carrier SMS channel. The Termux server only reads the SMS inbox via termux-sms-list, so RCS messages are invisible to it.
     
    Fix: Disable RCS on the SMS phone:
     
       
    1. Open Google Messages on the phone
      2.  
    2. Tap the profile icon (top right) \u2192 Messages settings
      3.  
    3. Tap RCS chats (or \"Chat features\")
      4.  
    4. Turn off \"Turn on RCS chats\"
      5.  
     
    This must be done on the phone running the SMS server
     
    Disabling RCS on the server phone forces all outgoing messages to use plain SMS, and ensures replies also come back as SMS. You do not need recipients to change anything on their end \u2014 when the server phone sends a plain SMS, the reply will be plain SMS as well (unless the recipient's carrier forces RCS-only, which is rare).
     
    Additional checks:
     
       
    • Some carriers (e.g. Google Fi, Jio) enable RCS at the carrier level. If disabling in the app doesn't help, contact the carrier to disable RCS on the SIM.
      •  
    • If the phone has Samsung Messages instead of Google Messages, go to Samsung Messages \u2192 Settings \u2192 Chat settings \u2192 turn off.
      •  
    • After disabling RCS, restart the phone and verify by sending a test message \u2014 the send button should show an SMS label, not \"Chat\".
      •  
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/broadcast/sms/#updating-the-sms-server","title":"Updating the SMS server","text":"
    To pull the latest version of the server code:
     
    cd ~/sms-server\ngit pull\n\n# Restart the server\nsv restart sms-api\n# Or without termux-services: pkill -f termux-sms-api-server.py && cd android && python termux-sms-api-server.py\n
    ","tags":["guide","admin","broadcast","sms"]},{"location":"docs/admin/map/","title":"Map & Canvassing","text":"
    Manage locations, organize canvassing territories, schedule volunteer shifts, and coordinate door-to-door outreach.
    ","tags":["guide","admin","map"]},{"location":"docs/admin/map/#in-this-section","title":"In This Section","text":"
       
    • Locations \u2014 import addresses via CSV or NAR, geocode with multiple providers, and manage the location database
      •  
    • Areas \u2014 draw polygon territories on the map to organize canvassing regions
      •  
    • Shifts \u2014 schedule volunteer time slots with recurring patterns and calendar views
      •  
    • Canvassing \u2014 canvass dashboard, walk sheets, contact export, and session management
      •  
    • Data Quality \u2014 geocoding quality metrics, provider distribution, and confidence analysis
      •  
    • Map Settings \u2014 configure map center, zoom level, and QR code links
      •  
    ","tags":["guide","admin","map"]},{"location":"docs/admin/map/areas/","title":"Areas (Cuts)","text":"
    Draw polygon regions on the map to define canvassing territories. Areas organize locations into manageable chunks for volunteers.
     
    ","tags":["guide","admin","map","canvassing"]},{"location":"docs/admin/map/areas/#key-features","title":"Key Features","text":"
       
    • Polygon drawing \u2014 use the map editor at /app/map/cuts to draw, edit, and delete area boundaries
      •  
    • Automatic association \u2014 locations within an area's polygon boundary are automatically linked
      •  
    • Area stats \u2014 total addresses, visited count, coverage percentage per area
      •  
    • Color coding \u2014 assign colors to visually distinguish areas on the map
      •  
    ","tags":["guide","admin","map","canvassing"]},{"location":"docs/admin/map/areas/#area-import-wizard","title":"Area Import Wizard","text":"
    Bulk-import addresses into an area from multiple data sources:
     
       
    • OpenStreetMap (OSM) \u2014 pull building addresses from Nominatim within the area
      •  
    • NAR (National Address Register) \u2014 import from the Canadian federal address dataset
      •  
    • Reverse geocode grid \u2014 generate a grid of points and reverse-geocode to discover addresses
      •  
    • Deduplication \u2014 imported addresses are checked against existing locations to avoid duplicates
      •  
    • Progress tracking \u2014 real-time status per source during import
      •  
    ","tags":["guide","admin","map","canvassing"]},{"location":"docs/admin/map/areas/#admin-routes","title":"Admin Routes","text":"
       
    • /app/map/cuts \u2014 draw and manage canvassing areas
      •  
    • /app/map/cuts/:id/export \u2014 printable location report for a cut
      •  
    ","tags":["guide","admin","map","canvassing"]},{"location":"docs/admin/map/canvassing/","title":"Canvassing","text":"
    Coordinate and monitor volunteer door-to-door outreach with the canvass dashboard, walk sheets, and contact export tools.
     
    ","tags":["guide","admin","map","canvassing"]},{"location":"docs/admin/map/canvassing/#canvass-dashboard","title":"Canvass Dashboard","text":"
    From /app/map/canvass:
     
       
    • Active sessions \u2014 see which volunteers are currently canvassing and their real-time positions
      •  
    • Leaderboard \u2014 volunteer rankings by visit count
      •  
    • Activity feed \u2014 recent visit outcomes across all areas
      •  
    • Stats \u2014 total sessions, visits recorded, and outcome breakdowns
      •  
    ","tags":["guide","admin","map","canvassing"]},{"location":"docs/admin/map/canvassing/#walk-sheets-exports","title":"Walk Sheets & Exports","text":"
       
    • Walk sheet \u2014 printable form at /app/map/walk-sheet with space for recording visit outcomes; includes up to 3 configurable QR codes
      •  
    • Cut export \u2014 printable location report at /app/map/cuts/:id/export for a specific canvassing area
      •  
    ","tags":["guide","admin","map","canvassing"]},{"location":"docs/admin/map/canvassing/#canvass-contact-export","title":"Canvass Contact Export","text":"
    Bridge canvassing data with advocacy campaigns:
     
       
    • Filter by outcome \u2014 include specific visit outcomes (spoke with, left literature, come back later)
      •  
    • Support level range \u2014 filter by recorded support level
      •  
    • Area selection \u2014 limit export to specific areas
      •  
    • Campaign targeting \u2014 export contacts as recipients for an advocacy campaign
      •  
    ","tags":["guide","admin","map","canvassing"]},{"location":"docs/admin/map/canvassing/#admin-routes","title":"Admin Routes","text":"
       
    • /app/map/canvass \u2014 canvass dashboard
      •  
    • /app/map/walk-sheet \u2014 printable walk sheet
      •  
    ","tags":["guide","admin","map","canvassing"]},{"location":"docs/admin/map/data-quality/","title":"Data Quality","text":"
    Monitor geocoding accuracy and coverage from /app/map/data-quality.
     
    ","tags":["guide","admin","map","analytics"]},{"location":"docs/admin/map/data-quality/#key-metrics","title":"Key Metrics","text":"
       
    • Geocoding success rate \u2014 percentage of locations with valid coordinates
      •  
    • Provider distribution \u2014 breakdown of which geocoding provider was used per location
      •  
    • Confidence scores \u2014 distribution of geocoding confidence levels across the dataset
      •  
    • Missing data \u2014 locations without coordinates, postal codes, or province assignments
      •  
    • Bulk re-geocode \u2014 re-process failed or low-confidence locations with a different provider
      •  
    ","tags":["guide","admin","map","analytics"]},{"location":"docs/admin/map/data-quality/#admin-routes","title":"Admin Routes","text":"
       
    • /app/map/data-quality \u2014 geocoding quality dashboard
      •  
    ","tags":["guide","admin","map","analytics"]},{"location":"docs/admin/map/locations/","title":"Locations","text":"
    Import addresses via CSV or the Canadian National Address Register (NAR), geocode them with multiple providers, and manage the location database.
     
    ","tags":["guide","admin","map","locations"]},{"location":"docs/admin/map/locations/#adding-locations","title":"Adding Locations","text":"
       
    • Click-to-add \u2014 click on the admin map to drop a new location marker
      •  
    • Form entry \u2014 manually enter address details
      •  
    • CSV import \u2014 upload a CSV with address columns; the system geocodes each row
      •  
    • NAR import \u2014 import Canadian National Address Register data with province, city, postal code, and residential-only filters
      •  
    ","tags":["guide","admin","map","locations"]},{"location":"docs/admin/map/locations/#geocoding","title":"Geocoding","text":"
    Locations are geocoded automatically using a multi-provider system supporting Nominatim, ArcGIS, Photon, Mapbox, Google, and LocationIQ. Failed entries can be re-geocoded individually or in bulk.
    ","tags":["guide","admin","map","locations"]},{"location":"docs/admin/map/locations/#bulk-operations","title":"Bulk Operations","text":"
    Select multiple locations for:
     
       
    • Re-geocoding with a different provider
      •  
    • Tagging or re-tagging
      •  
    • Deletion
      •  
    • CSV export
      •  
    ","tags":["guide","admin","map","locations"]},{"location":"docs/admin/map/locations/#admin-routes","title":"Admin Routes","text":"
       
    • /app/map \u2014 location CRUD, CSV import/export, geocoding, area import wizard
      •  
    ","tags":["guide","admin","map","locations"]},{"location":"docs/admin/map/settings/","title":"Map Settings","text":"
    Configure the default map view and QR code links from /app/map/settings.
     
    ","tags":["guide","admin","map","configuration"]},{"location":"docs/admin/map/settings/#settings","title":"Settings","text":"
       
    • Map center \u2014 latitude and longitude for the default map center point
      •  
    • Default zoom \u2014 initial zoom level when maps load (1-18)
      •  
    • QR code links \u2014 up to 3 configurable URLs that appear as QR codes on printed walk sheets (e.g., campaign page, shift signup, volunteer portal)
      •  
    ","tags":["guide","admin","map","configuration"]},{"location":"docs/admin/map/settings/#admin-routes","title":"Admin Routes","text":"
       
    • /app/map/settings \u2014 map configuration
      •  
    ","tags":["guide","admin","map","configuration"]},{"location":"docs/admin/map/shifts/","title":"Shifts","text":"
    Schedule volunteer time slots and let people sign up through a public page. Shifts can be linked to specific areas so volunteers know where they'll be canvassing.
     
    ","tags":["guide","admin","map","shifts"]},{"location":"docs/admin/map/shifts/#creating-shifts","title":"Creating Shifts","text":"
       
    • Single shifts \u2014 set date, time, location description, and optional area assignment
      •  
    • Recurring shifts \u2014 create series with daily, weekly, or monthly frequency; weekly allows specific day selection
      •  
    • Calendar view \u2014 dedicated calendar tab showing shifts by date; click any date to create a new shift pre-filled
      •  
    ","tags":["guide","admin","map","shifts"]},{"location":"docs/admin/map/shifts/#series-management","title":"Series Management","text":"
       
    • Edit modes \u2014 when editing a recurring shift, choose: this shift only, this and future, or all in series
      •  
    • Date range \u2014 define start and optional end date; generates up to 12 weeks (capped at 100 shifts)
      •  
    • Detach \u2014 remove a shift from its series to edit independently
      •  
    ","tags":["guide","admin","map","shifts"]},{"location":"docs/admin/map/shifts/#signups","title":"Signups","text":"
       
    • Signup drawer \u2014 view all signups for a shift in the admin panel
      •  
    • Capacity \u2014 optionally set maximum volunteer count per shift
      •  
    • Confirmation emails \u2014 automatic email sent when a volunteer signs up or cancels
      •  
    ","tags":["guide","admin","map","shifts"]},{"location":"docs/admin/map/shifts/#admin-routes","title":"Admin Routes","text":"
       
    • /app/map/shifts \u2014 shift CRUD, calendar view, signup management
      •  
    ","tags":["guide","admin","map","shifts"]},{"location":"docs/admin/media/","title":"Media","text":"
    Upload, organize, and share campaign videos and photos with built-in analytics and engagement features. Enable with enableMediaFeatures in Settings.
    ","tags":["guide","admin","media"]},{"location":"docs/admin/media/#in-this-section","title":"In This Section","text":"
       
    • Library \u2014 upload videos and photos, manage metadata, schedule publishing, and generate preview links
      •  
    • Analytics \u2014 view counts, watch time, completion rates, traffic sources, and viewer activity
      •  
    • Curated Gallery \u2014 playlists, shorts feed, and featured content for the public gallery
      •  
    • Moderation \u2014 comment review, word filters, and content moderation tools
      •  
    • Gallery Ads \u2014 promotional cards with audience targeting, scheduling, and click-through analytics
      •  
    ","tags":["guide","admin","media"]},{"location":"docs/admin/media/ads/","title":"Gallery Ads","text":"
    Create promotional cards that appear in the public media gallery and documentation site. Manage from /app/media/ads.
    ","tags":["guide","admin","media"]},{"location":"docs/admin/media/ads/#key-features","title":"Key Features","text":"
       
    • Ad CRUD \u2014 create ads with title, description, image, and click-through URL
      •  
    • Placement targeting \u2014 assign ads to specific placements (gallery sidebar, gallery feed, docs sidebar)
      •  
    • Scheduling \u2014 set start and end dates for time-limited promotions
      •  
    • Click tracking \u2014 view impressions and click-through rates per ad
      •  
    • Priority ordering \u2014 control which ads appear first when multiple are active
      •  
    ","tags":["guide","admin","media"]},{"location":"docs/admin/media/ads/#admin-routes","title":"Admin Routes","text":"
       
    • /app/media/ads \u2014 gallery ad management and analytics
      •  
    ","tags":["guide","admin","media"]},{"location":"docs/admin/media/analytics/","title":"Analytics","text":"
    Track video engagement with GDPR-compliant analytics (IP hashing, 90-day retention).
     
    ","tags":["guide","admin","media","analytics"]},{"location":"docs/admin/media/analytics/#per-video-metrics","title":"Per-Video Metrics","text":"
    Each video tracks:
     
       
    • View count and unique viewers
      •  
    • Average watch time and completion rate
      •  
    • Traffic sources \u2014 direct, embedded, shared
      •  
    • Registered viewer activity (when logged in)
      •  
    ","tags":["guide","admin","media","analytics"]},{"location":"docs/admin/media/analytics/#global-dashboard","title":"Global Dashboard","text":"
    The analytics dashboard at /app/media/analytics provides:
     
       
    • Aggregate view counts across all videos
      •  
    • Top-performing content by views and completion rate
      •  
    • Viewer trends over time
      •  
    • Traffic source breakdown
      •  
    ","tags":["guide","admin","media","analytics"]},{"location":"docs/admin/media/analytics/#tracking","title":"Tracking","text":"
    Public endpoints record engagement:
     
       
    • View initiation
      •  
    • 10-second heartbeat intervals
      •  
    • navigator.sendBeacon for reliable end-of-session reporting
      •  
    ","tags":["guide","admin","media","analytics"]},{"location":"docs/admin/media/analytics/#admin-routes","title":"Admin Routes","text":"
       
    • /app/media/analytics \u2014 global analytics dashboard
      •  
    ","tags":["guide","admin","media","analytics"]},{"location":"docs/admin/media/curated/","title":"Curated Gallery","text":"
    Curate the public gallery experience with playlists, a shorts feed, and featured content.
     
    ","tags":["guide","admin","media","gallery"]},{"location":"docs/admin/media/curated/#playlists","title":"Playlists","text":"
    From /app/media/curated:
     
       
    • Three types \u2014 admin playlists (managed), user playlists (personal), and public playlists (community)
      •  
    • Drag-reorder \u2014 arrange videos within a playlist
      •  
    • Featured carousel \u2014 feature playlists on the gallery homepage
      •  
    • Dedicated viewer \u2014 full playlist playback page with up-next queue
      •  
    ","tags":["guide","admin","media","gallery"]},{"location":"docs/admin/media/curated/#shorts-feed","title":"Shorts Feed","text":"
    TikTok-style vertical video feed for clips under 60 seconds:
     
       
    • Automatic classification \u2014 videos under 60 seconds are flagged as shorts
      •  
    • Vertical feed \u2014 mobile-optimized swipeable interface at /gallery/shorts
      •  
    • Autoplay \u2014 continuous playback as viewers scroll
      •  
    ","tags":["guide","admin","media","gallery"]},{"location":"docs/admin/media/curated/#admin-routes","title":"Admin Routes","text":"
       
    • /app/media/curated \u2014 playlist management
      •  
    ","tags":["guide","admin","media","gallery"]},{"location":"docs/admin/media/library/","title":"Library","text":"
    The media library at /app/media/library is where you upload, organize, and publish video and photo content.
     
    ","tags":["guide","admin","media","videos"]},{"location":"docs/admin/media/library/#video-upload","title":"Video Upload","text":"
       
    • Drag-and-drop \u2014 single or batch upload (up to 10GB per file)
      •  
    • Supported formats \u2014 MP4, MOV, AVI, MKV, WebM, M4V, FLV
      •  
    • Automatic metadata \u2014 FFprobe extracts duration, dimensions, orientation, quality, and audio info
      •  
    • Quick actions \u2014 hover a video card for Edit (E), Preview (P), Analytics (A), Schedule (S) keyboard shortcuts
      •  
    ","tags":["guide","admin","media","videos"]},{"location":"docs/admin/media/library/#photo-management","title":"Photo Management","text":"
       
    • Albums \u2014 organize photos into named collections with cover images
      •  
    • Bulk uploads \u2014 drag-and-drop multiple photos with automatic metadata extraction
      •  
    • Photo picker \u2014 insert photos into landing pages and email templates via a modal picker
      •  
    ","tags":["guide","admin","media","videos"]},{"location":"docs/admin/media/library/#scheduled-publishing","title":"Scheduled Publishing","text":"
       
    • Publish/unpublish dates \u2014 set future dates for automatic state changes
      •  
    • Timezone support \u2014 11 supported timezones
      •  
    • Calendar view \u2014 visualize scheduled items on the Calendar tab
      •  
    • BullMQ automation \u2014 jobs fire at scheduled times
      •  
    ","tags":["guide","admin","media","videos"]},{"location":"docs/admin/media/library/#preview-links","title":"Preview Links","text":"
    Generate 24-hour JWT-authenticated preview links for unpublished videos \u2014 useful for stakeholder review before publishing.
    ","tags":["guide","admin","media","videos"]},{"location":"docs/admin/media/library/#admin-routes","title":"Admin Routes","text":"
       
    • /app/media/library \u2014 video and photo management
      •  
    • /app/media/jobs \u2014 processing job queue monitoring
      •  
    ","tags":["guide","admin","media","videos"]},{"location":"docs/admin/media/moderation/","title":"Moderation","text":"
    Admin tools for reviewing and managing comments across all media content at /app/media/moderation.
    ","tags":["guide","admin","media","moderation"]},{"location":"docs/admin/media/moderation/#moderation-dashboard","title":"Moderation Dashboard","text":"
       
    • Filter by status \u2014 pending, safe, flagged, hidden
      •  
    • Status counts \u2014 summary stats showing total, pending, flagged, hidden, and safe comments
      •  
    • Search \u2014 filter by video, date range, or text content
      •  
    ","tags":["guide","admin","media","moderation"]},{"location":"docs/admin/media/moderation/#moderation-actions","title":"Moderation Actions","text":"
    For each comment, admins can:
     
       
    • Approve \u2014 mark as safe and unhide if previously hidden
      •  
    • Hide \u2014 remove from public view with a reason (manual, word filter, spam, or link)
      •  
    • Unhide \u2014 restore a previously hidden comment
      •  
    • Delete \u2014 permanently remove
      •  
    • Add notes \u2014 internal moderation notes (not visible to users)
      •  
    ","tags":["guide","admin","media","moderation"]},{"location":"docs/admin/media/moderation/#word-filter","title":"Word Filter","text":"
    A configurable list of words with severity levels:
     Severity Action High Auto-blocks the comment Medium Auto-hides for review Low Flags for moderator attention Custom User-defined severity 
    The filter list is cached with a 1-minute TTL and invalidated on changes.
    ","tags":["guide","admin","media","moderation"]},{"location":"docs/admin/media/moderation/#admin-routes","title":"Admin Routes","text":"
       
    • /app/media/moderation \u2014 comment moderation and word filter management
      •  
    ","tags":["guide","admin","media","moderation"]},{"location":"docs/admin/payments/","title":"Payments","text":"
    Accept memberships, product sales, and donations through Stripe. Enable with enablePayments in Settings.
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/#in-this-section","title":"In This Section","text":"
       
    • Products \u2014 manage merchandise and one-time purchase items with inventory tracking
      •  
    • Donations \u2014 donation pages with goals, suggested amounts, and branded thank-you messages
      •  
    • Plans \u2014 recurring subscription plans with monthly and yearly billing
      •  
    • Settings \u2014 Stripe API key configuration with encrypted storage
      •  
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/#how-it-works","title":"How It Works","text":"
       
    1. Enable payments in Settings or .env (ENABLE_PAYMENTS=true)
      2.  
    2. Configure Stripe API keys in Settings > Payments (stored encrypted with ENCRYPTION_KEY)
      3.  
    3. Payment widgets become available on landing pages and MkDocs pages
      4.  
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/donations/","title":"Donations","text":"
    Create custom branded donation landing pages with independent branding and goals.
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/donations/#donation-pages","title":"Donation Pages","text":"
    From /app/donation-pages:
     
       
    • Custom branding \u2014 each page has its own title, description, and cover image
      •  
    • Configurable amounts \u2014 set suggested donation amounts per page
      •  
    • Thank-you messages \u2014 customizable post-donation confirmation
      •  
    • Public slugs \u2014 shareable URL at /donate/:slug
      •  
    • Goal tracking \u2014 fundraising goals with progress indicators
      •  
    • Multiple campaigns \u2014 run several pages simultaneously with independent tracking
      •  
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/donations/#donation-management","title":"Donation Management","text":"
    From /app/donations:
     
       
    • View all donations with date, amount, donor info, and status
      •  
    • Filter by donation page, date range, or amount
      •  
    • Export to CSV for accounting and tax receipts
      •  
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/donations/#admin-routes","title":"Admin Routes","text":"
       
    • /app/donations \u2014 donation management
      •  
    • /app/donation-pages \u2014 donation page CRUD
      •  
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/plans/","title":"Plans","text":"
    Create and manage recurring subscription plans for campaign supporters at /app/plans.
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/plans/#key-features","title":"Key Features","text":"
       
    • Tiered plans \u2014 multiple subscription tiers with different pricing and benefits
      •  
    • Billing cycles \u2014 monthly and yearly billing options
      •  
    • Stripe integration \u2014 subscriptions managed through Stripe for reliable recurring payments
      •  
    • Subscriber tracking \u2014 view active subscribers, MRR, and churn metrics
      •  
    • Public pricing page \u2014 plans displayed at /pricing
      •  
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/plans/#admin-routes","title":"Admin Routes","text":"
       
    • /app/plans \u2014 subscription plan management
      •  
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/products/","title":"Products","text":"
    Manage campaign merchandise and one-time purchase items at /app/products.
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/products/#key-features","title":"Key Features","text":"
       
    • Product CRUD \u2014 create products with title, description, price, and images
      •  
    • Inventory management \u2014 track stock levels and set low-stock alerts
      •  
    • Stripe checkout \u2014 seamless payment flow via Stripe
      •  
    • Public shop \u2014 products displayed at /shop for public browsing and purchase
      •  
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/products/#admin-routes","title":"Admin Routes","text":"
       
    • /app/products \u2014 product management
      •  
    ","tags":["guide","admin","payments"]},{"location":"docs/admin/payments/settings/","title":"Payment Settings","text":"
    Configure Stripe integration from Settings > Payments.
    ","tags":["guide","admin","payments","configuration"]},{"location":"docs/admin/payments/settings/#stripe-configuration","title":"Stripe Configuration","text":"
       
    • Publishable key \u2014 used by the frontend for Stripe Elements and Checkout
      •  
    • Secret key \u2014 used by the API for creating charges and managing subscriptions
      •  
    • Encrypted storage \u2014 both keys are stored encrypted in the database using the ENCRYPTION_KEY environment variable (AES encryption)
      •  
    ","tags":["guide","admin","payments","configuration"]},{"location":"docs/admin/payments/settings/#webhook","title":"Webhook","text":"
    Stripe webhooks are automatically configured to handle:
     
       
    • Successful payments and subscription renewals
      •  
    • Failed payments and subscription cancellations
      •  
    • Refunds and disputes
      •  
    ","tags":["guide","admin","payments","configuration"]},{"location":"docs/admin/payments/settings/#admin-routes","title":"Admin Routes","text":"
       
    • /app/settings (Payments tab) \u2014 Stripe key configuration
      •  
    ","tags":["guide","admin","payments","configuration"]},{"location":"docs/admin/services/","title":"Services","text":"
    Manage the platform's infrastructure services, monitoring stack, and third-party integrations.
    ","tags":["guide","admin","services"]},{"location":"docs/admin/services/#in-this-section","title":"In This Section","text":"
       
    • Tunnel \u2014 Pangolin tunnel management for public access without port forwarding
      •  
    • CrowdSec & Security \u2014 CrowdSec Manager, Tinyauth forward-auth, ISP whitelisting, and Turnstile captcha on the Pangolin server
      •  
    • Monitoring \u2014 Prometheus metrics, Grafana dashboards, and Alertmanager
      •  
    • Integrations \u2014 Chat, video conferencing, password manager, whiteboard, Git hosting, automation, and QR codes
      •  
    • User Provisioning \u2014 automatic account sync across integrated services
      •  
    ","tags":["guide","admin","services"]},{"location":"docs/admin/services/crowdsec/","title":"CrowdSec Manager & Security Configuration","text":"
    This page covers the CrowdSec Manager web UI on the Pangolin server, protected behind Tinyauth authentication, along with tuning of CrowdSec security rules and enabling Cloudflare Turnstile captcha for the CrowdSec bouncer.
    ","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#architecture","title":"Architecture","text":"
    graph LR\n    User -->|HTTPS| Traefik\n    Traefik -->|forwardAuth| Tinyauth\n    Tinyauth -->|authenticated| Traefik\n    Traefik -->|proxy| CrowdSec-Manager\n    CrowdSec-Manager -->|API| CrowdSec\n    Traefik -->|bouncer plugin| CrowdSec\n    CrowdSec -->|captcha decision| Turnstile[Cloudflare Turnstile]
     
    All services run on the same Docker Compose stack and share the pangolin network. Traefik reaches them through Gerbil's network namespace.
    ","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#components-added","title":"Components Added","text":"","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#crowdsec-manager","title":"CrowdSec Manager","text":"
    Image: hhftechnology/crowdsec-manager:1.1.0
     
    A web UI for managing CrowdSec operations \u2014 viewing alerts, decisions, managing bouncers, and configuring scenarios. It has read-only access to Traefik and CrowdSec configs and read-write access to its own data and backups.
     
    Accessible at: https://crowdsec.bnkserve.org
    ","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#tinyauth","title":"Tinyauth","text":"
    Image: ghcr.io/steveiliop56/tinyauth:v4
     
    A lightweight forward-auth middleware that protects the CrowdSec Manager dashboard with a login screen. Traefik's forwardAuth middleware checks every request to the manager against Tinyauth before allowing access.
     
    Login page at: https://auth.bnkserve.org
     
    User credentials are stored in a users file (/data/users) mounted from the host, using bcrypt-hashed passwords.
     
    Special Characters in Passwords
     
    Tinyauth v4 has a known issue where special characters (@, !, etc.) in passwords can cause login failures through the browser, even though the bcrypt hash verifies correctly via the CLI. Use alphanumeric passwords to avoid this.
    ","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#traefik-routing","title":"Traefik Routing","text":"","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#routers","title":"Routers","text":"Router Domain Middleware Purpose crowdsec-manager-router crowdsec.bnkserve.org security-headers, tinyauth Dashboard (HTTPS) crowdsec-manager-redirect crowdsec.bnkserve.org redirect-to-https HTTP \u2192 HTTPS redirect tinyauth-router auth.bnkserve.org security-headers Auth login page (HTTPS) tinyauth-redirect auth.bnkserve.org redirect-to-https HTTP \u2192 HTTPS redirect 
    No tinyauth middleware on the tinyauth router
     
    The tinyauth-router must not have the tinyauth forwardAuth middleware applied \u2014 this would create an infinite redirect loop.
    ","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#middleware","title":"Middleware","text":"
    The tinyauth forwardAuth middleware forwards every request to http://tinyauth:3000/api/auth/traefik. If the user has a valid session cookie (scoped to .bnkserve.org), the request passes through. Otherwise, the user is redirected to the Tinyauth login page.
     
    tinyauth:\n  forwardAuth:\n    address: http://tinyauth:3000/api/auth/traefik\n    trustForwardHeader: true\n    authResponseHeaders:\n      - X-Forwarded-User\n
    ","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#crowdsec-tuning","title":"CrowdSec Tuning","text":"","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#relaxed-crawl-detection","title":"Relaxed Crawl Detection","text":"
    The crowdsecurity/http-crawl-non_statics scenario was triggering on legitimate Canadian users browsing the site. The local override at /etc/crowdsec/scenarios/http-crawl-non_statics.yaml (replacing the hub symlink) has relaxed thresholds:
     Parameter Before After Effect capacity 40 80 Twice as many distinct pages before triggering leakspeed 0.5s 0.25s Bucket drains twice as fast 
    Combined effect: 4x more lenient \u2014 a user must hit 80+ distinct non-static pages faster than 1 every 0.25 seconds to trigger a captcha.
    ","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#canadian-isp-whitelist","title":"Canadian ISP Whitelist","text":"
    A whitelist expression in /etc/crowdsec/parsers/s02-enrich/mywhitelists.yaml exempts traffic from major Canadian ISPs from all CrowdSec scenarios:
     
    expression:\n  - evt.Meta.ASNNumber in ['812', '852', '6327', '5645', '20365', '25668', '577']\n
     AS Number ISP 812 Rogers Communications 852 TELUS Communications 6327 Shaw Communications 5645 TekSavvy 20365 Freedom Mobile 25668 CipherKey 577 Bell Canada 
    Field name
     
    The GeoIP enricher populates evt.Meta.ASNNumber (not ASNumber). This can be verified by inspecting /etc/crowdsec/parsers/s02-enrich/geoip-enrich.yaml.
    ","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#cloudflare-turnstile-captcha","title":"Cloudflare Turnstile Captcha","text":"
    Previously, CrowdSec captcha decisions resulted in a hard 403 block because no captcha provider was configured. Now, users with a captcha decision see a Cloudflare Turnstile challenge page and can proceed after solving it.
     
    Configuration added to the CrowdSec bouncer plugin in dynamic_config.yml:
     
    captchaProvider: turnstile\ncaptchaSiteKey: <site-key>\ncaptchaSecretKey: <secret-key>\ncaptchaHTMLFilePath: /etc/traefik/captcha.html\n
     
    Captcha HTML template path
     
    The captcha.html template is copied from the plugin source to /etc/traefik/captcha.html (the mounted config volume). Do not reference the /plugins-storage/ path directly \u2014 the hash in that path changes on every Traefik restart.
    ","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#dns-records","title":"DNS Records","text":"
    Two A records pointing to 72.11.155.21:
     Record Purpose crowdsec.bnkserve.org CrowdSec Manager dashboard auth.bnkserve.org Tinyauth login page","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/crowdsec/#verification","title":"Verification","text":"
    # Check containers are running and healthy\ndocker ps --filter name=crowdsec-manager --filter name=tinyauth\n\n# Check both are on the pangolin network\ndocker network inspect pangolin --format '{{range .Containers}}{{.Name}} {{end}}'\n\n# Verify no Canadian ISPs in active decisions\ndocker exec crowdsec cscli decisions list | grep \"CA\"\n\n# Check CrowdSec whitelist is loaded\ndocker exec crowdsec cscli parsers inspect mywhitelists\n\n# Check Traefik logs for captcha errors\ndocker logs traefik 2>&1 | grep -i captcha\n
    ","tags":["guide","admin","services","security"]},{"location":"docs/admin/services/integrations/","title":"Integrations","text":"
    Changemaker Lite integrates with several self-hosted services. Each runs as a Docker container and can be enabled independently.
    ","tags":["guide","admin","services","integrations"]},{"location":"docs/admin/services/integrations/#team-chat-rocketchat","title":"Team Chat (Rocket.Chat)","text":"
    Self-hosted team chat for volunteer coordination. Enable with enableChat in Settings.
     
       
    • Channels & DMs \u2014 organize conversations by topic, team, or campaign
      •  
    • Iframe integration \u2014 embedded in the admin dashboard and volunteer portal
      •  
    • Floating widget \u2014 minimizable chat FAB on admin pages (toggleable in Settings)
      •  
    • SSO-ready \u2014 iframe authentication for seamless login
      •  
    • Mobile apps \u2014 native Rocket.Chat apps work with your instance
      •  
    • Routes: /app/services/rocketchat, /volunteer/chat
      •  
    ","tags":["guide","admin","services","integrations"]},{"location":"docs/admin/services/integrations/#video-conferencing-jitsi-meet","title":"Video Conferencing (Jitsi Meet)","text":"
    Self-hosted video calls integrated with Rocket.Chat via JWT authentication. Enable with enableMeet in Settings.
     
       
    • One-click calls \u2014 start a call from any Rocket.Chat channel or DM
      •  
    • JWT auth \u2014 participants join automatically with no separate login
      •  
    • 4 containers \u2014 jitsi-web, jitsi-prosody (XMPP/JWT), jitsi-jicofo (conference focus), jitsi-jvb (video bridge)
      •  
    • Setup: Generate secrets, start containers, configure the Jitsi marketplace app in Rocket.Chat, set token expiration to now + 1hour
      •  
     
    Token Expiration
     
    Set the Jitsi app's Token Expiration to now + 1hour. A raw number like 120 is interpreted as Unix timestamp 120 (Jan 1970), causing all tokens to appear expired.
    ","tags":["guide","admin","services","integrations"]},{"location":"docs/admin/services/integrations/#password-manager-vaultwarden","title":"Password Manager (Vaultwarden)","text":"
    Bitwarden-compatible password vault for secure team credential sharing.
     
       
    • Bitwarden client compatible \u2014 use official browser extensions, desktop apps, and mobile apps
      •  
    • Auto-invite \u2014 initial admin user invited on first startup
      •  
    • User provisioning \u2014 new platform users can be auto-invited when provisioning is enabled
      •  
    • Client setup: Point Bitwarden clients to https://vault.DOMAIN
      •  
    ","tags":["guide","admin","services","integrations"]},{"location":"docs/admin/services/integrations/#whiteboard-excalidraw","title":"Whiteboard (Excalidraw)","text":"
    Collaborative whiteboard for brainstorming and campaign planning.
     
       
    • Real-time collaboration \u2014 multi-user drawing with WebSocket support
      •  
    • Embedded in admin \u2014 full-screen iframe at /app/services/excalidraw
      •  
    • Desktop only \u2014 requires a desktop browser for the drawing experience
      •  
    • Route: /app/services/excalidraw
      •  
    ","tags":["guide","admin","services","integrations"]},{"location":"docs/admin/services/integrations/#git-hosting-gitea","title":"Git Hosting (Gitea)","text":"
    Self-hosted Git repository hosting for campaign code and configuration.
     
       
    • Lightweight Git forge \u2014 repositories, issues, pull requests, and wikis
      •  
    • User provisioning \u2014 platform users can be auto-provisioned as Gitea accounts
      •  
    • Embedded \u2014 accessible at git.DOMAIN or embedded in admin at /app/services/gitea
      •  
    ","tags":["guide","admin","services","integrations"]},{"location":"docs/admin/services/integrations/#workflow-automation-n8n","title":"Workflow Automation (n8n)","text":"
    Self-hosted workflow automation for connecting platform events to external services.
     
       
    • Visual workflow editor \u2014 drag-and-drop automation builder
      •  
    • Webhook triggers \u2014 respond to platform events
      •  
    • Embedded \u2014 accessible at n8n.DOMAIN or embedded in admin at /app/services/n8n
      •  
    ","tags":["guide","admin","services","integrations"]},{"location":"docs/admin/services/integrations/#qr-code-generator-mini-qr","title":"QR Code Generator (Mini QR)","text":"
    Built-in QR code generation for walk sheets, volunteer invites, and campaign links.
     
       
    • Public API \u2014 QR code PNG generation at /api/qr
      •  
    • Walk sheet integration \u2014 QR codes embedded in printable walk sheets
      •  
    • Volunteer quick join \u2014 QR codes for instant volunteer onboarding
      •  
    • Embedded \u2014 admin interface at /app/services/qr
      •  
    ","tags":["guide","admin","services","integrations"]},{"location":"docs/admin/services/monitoring/","title":"Monitoring","text":"
    The monitoring stack runs as a Docker Compose profile and provides metrics collection, visualization, and alerting.
     
    ","tags":["guide","admin","services","monitoring"]},{"location":"docs/admin/services/monitoring/#starting-the-stack","title":"Starting the Stack","text":"
    docker compose --profile monitoring up -d\n
     
    This starts Prometheus, Grafana, Alertmanager, cAdvisor, Node Exporter, and Redis Exporter.
    ","tags":["guide","admin","services","monitoring"]},{"location":"docs/admin/services/monitoring/#custom-metrics","title":"Custom Metrics","text":"
    The platform exposes 12 custom cm_* Prometheus metrics:
     
       
    • API request rates and latencies
      •  
    • BullMQ queue sizes (email, SMS, video scheduling)
      •  
    • Active canvass sessions
      •  
    • External service health gauges
      •  
    ","tags":["guide","admin","services","monitoring"]},{"location":"docs/admin/services/monitoring/#grafana-dashboards","title":"Grafana Dashboards","text":"
    Three pre-configured dashboards auto-provisioned from configs/grafana/:
     
       
    • API Performance \u2014 request rates, latencies, error rates
      •  
    • Application Overview \u2014 queue sizes, active sessions, service health
      •  
    • System Health \u2014 container resources, host metrics, Redis stats
      •  
    ","tags":["guide","admin","services","monitoring"]},{"location":"docs/admin/services/monitoring/#alertmanager","title":"Alertmanager","text":"
    Alert rules in configs/prometheus/alerts.yml cover:
     
       
    • API downtime and high error rates
      •  
    • Queue backlogs
      •  
    • Service connectivity failures
      •  
    • Resource utilization thresholds
      •  
    ","tags":["guide","admin","services","monitoring"]},{"location":"docs/admin/services/monitoring/#admin-routes","title":"Admin Routes","text":"
       
    • /app/observability \u2014 embedded Grafana dashboards, alert status, and service health (3 tabs)
      •  
    ","tags":["guide","admin","services","monitoring"]},{"location":"docs/admin/services/monitoring/#direct-access","title":"Direct Access","text":"
       
    • Grafana: localhost:3001 or grafana.DOMAIN
      •  
    • Prometheus: localhost:9090
      •  
    • Alertmanager: localhost:9093
      •  
    ","tags":["guide","admin","services","monitoring"]},{"location":"docs/admin/services/tunnel/","title":"Tunnel (Pangolin)","text":"
    Pangolin provides secure tunneling to expose your self-hosted services to the internet without port forwarding or a static IP.
     
    ","tags":["guide","admin","services","networking"]},{"location":"docs/admin/services/tunnel/#setup","title":"Setup","text":"
    From /app/pangolin:
     
       
    • Automated setup \u2014 one-command deployment that creates the Pangolin site, updates .env with credentials, and restarts the Newt tunnel container
      •  
    • Manual setup \u2014 step-by-step instructions for connecting to an existing Pangolin instance
      •  
    ","tags":["guide","admin","services","networking"]},{"location":"docs/admin/services/tunnel/#resource-management","title":"Resource Management","text":"
    The platform defines 12+ service resources in configs/pangolin/resources.yml:
     
       
    • Each resource maps a subdomain (e.g., api.DOMAIN, app.DOMAIN) to an internal service
      •  
    • Hourly sync \u2014 nginx cron job pushes resource definitions to Pangolin automatically
      •  
    • Status dashboard \u2014 view tunnel connection status and resource health
      •  
    ","tags":["guide","admin","services","networking"]},{"location":"docs/admin/services/tunnel/#newt-container","title":"Newt Container","text":"
    The Newt container runs alongside nginx and tunnels traffic to your services:
     
       
    • Configured via PANGOLIN_NEWT_ID and PANGOLIN_NEWT_SECRET environment variables
      •  
    • Depends on nginx (all resources route through nginx:80)
      •  
    • Auto-restarts on failure
      •  
    ","tags":["guide","admin","services","networking"]},{"location":"docs/admin/services/tunnel/#security","title":"Security","text":"
    The Pangolin server runs CrowdSec for intrusion detection with a web management UI protected by Tinyauth forward-auth. See CrowdSec & Security for details on:
     
       
    • CrowdSec Manager dashboard (crowdsec.bnkserve.org)
      •  
    • Tinyauth authentication (auth.bnkserve.org)
      •  
    • Canadian ISP whitelisting and crawl detection tuning
      •  
    • Cloudflare Turnstile captcha integration
      •  
    ","tags":["guide","admin","services","networking"]},{"location":"docs/admin/services/tunnel/#admin-routes","title":"Admin Routes","text":"
       
    • /app/pangolin \u2014 tunnel status, setup wizard, and resource management
      •  
    ","tags":["guide","admin","services","networking"]},{"location":"docs/admin/services/user-provisioning/","title":"User Provisioning","text":"
    Automatically create and sync user accounts across integrated services when new platform users are registered. Enable with enableUserProvisioning in Settings.
    ","tags":["guide","admin","services"]},{"location":"docs/admin/services/user-provisioning/#supported-services","title":"Supported Services","text":"Service Mode Notes Rocket.Chat Always lazy SSO on first access Gitea Eager or lazy Admin API provisioning Vaultwarden Eager or lazy Invite-based (no password management) Listmonk Eager or lazy Subscriber sync","tags":["guide","admin","services"]},{"location":"docs/admin/services/user-provisioning/#configuration","title":"Configuration","text":"
    From Settings > User Provisioning:
     
       
    • Toggle provisioning per service
      •  
    • Choose eager (create immediately on user registration) or lazy (create on first access)
      •  
    • View provisioning status per user in the Service Accounts panel on the Users page
      •  
    ","tags":["guide","admin","services"]},{"location":"docs/admin/services/user-provisioning/#bulk-sync","title":"Bulk Sync","text":"
    Trigger a bulk sync from /api/users/provisioning/sync to provision all existing users across enabled services. Useful after enabling a new service.
    ","tags":["guide","admin","services"]},{"location":"docs/admin/services/user-provisioning/#admin-routes","title":"Admin Routes","text":"
       
    • /app/users (edit drawer) \u2014 per-user service account status and actions
      •  
    • /app/settings (User Provisioning tab) \u2014 per-service toggle and timing
      •  
    ","tags":["guide","admin","services"]},{"location":"docs/admin/web/","title":"Web Content","text":"
    Manage the public-facing web presence \u2014 landing pages, the dynamic homepage, navigation menu, and documentation site.
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/#in-this-section","title":"In This Section","text":"
       
    • Landing Pages \u2014 build campaign microsites with the GrapesJS drag-and-drop editor
      •  
    • Homepage \u2014 dynamic public landing page aggregating campaigns, shifts, media, and events
      •  
    • Navigation \u2014 customize the public navigation menu with toggles, custom links, and reordering
      •  
    • Documentation \u2014 MkDocs site management, page analytics, and comment moderation
      •  
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/#social-sharing","title":"Social Sharing","text":"
    All public content (campaigns, landing pages, gallery videos) automatically generates Open Graph and Twitter Card meta tags for rich link previews when shared on social media, messaging apps, and search engines. OG responses are cached in Redis for 10 minutes.
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/documentation/","title":"Documentation","text":"
    Manage the MkDocs documentation site, track page engagement, and moderate visitor comments.
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/documentation/#mkdocs-management","title":"MkDocs Management","text":"
    From Docs (/app/docs):
     
       
    • View MkDocs build status and health
      •  
    • Browse the documentation file tree
      •  
    • Export landing pages to MkDocs as Jinja2 Material theme overrides
      •  
    • Configure documentation settings from MkDocs Settings (/app/docs/settings)
      •  
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/documentation/#documentation-analytics","title":"Documentation Analytics","text":"
    Track how visitors interact with documentation pages using the MkDocs Material theme's custom analytics provider and navigation.tracking.
     
       
    • Navigation tracking \u2014 updates the browser URL as users scroll through sections, enabling section-level engagement tracking
      •  
    • Custom provider \u2014 integrates with any third-party analytics tool (Plausible, Umami, Google Analytics) via template overrides in docs/overrides/
      •  
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/documentation/#comments","title":"Comments","text":"
    Visitors can leave comments on documentation pages using a Gitea-backed comment system.
     
       
    • Anonymous posting \u2014 visitors can comment without creating an account
      •  
    • Gitea-backed \u2014 comments stored as Gitea issues (one issue per page) for version control and searchability
      •  
    • Moderation \u2014 admin panel at /app/docs-comments for approving, hiding, or deleting comments
      •  
    • OAuth login \u2014 optional Gitea OAuth for authenticated commenting
      •  
    • Per-page threads \u2014 each documentation page gets its own comment thread
      •  
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/documentation/#admin-routes","title":"Admin Routes","text":"
       
    • /app/docs \u2014 MkDocs management (file tree, config, build triggers)
      •  
    • /app/docs/settings \u2014 documentation configuration
      •  
    • /app/docs-comments \u2014 moderate documentation comments
      •  
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/homepage/","title":"Public Homepage","text":"
    A dynamic public landing page that showcases your organization and aggregates content from across the platform.
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/homepage/#sections","title":"Sections","text":"
    The homepage assembles its content from enabled modules. Sections are only displayed when their corresponding module is active and has data to show.
     
       
    • Hero banner \u2014 organization name, logo, tagline (configurable via Settings), and call-to-action buttons for campaigns and volunteer signups
      •  
    • Stats counters \u2014 active campaigns, total emails sent, and volunteer signups (shown only when counts are greater than zero)
      •  
    • Featured campaigns \u2014 up to 3 active campaigns, sorted by highlight status then creation date, with email counts and descriptions
      •  
    • Upcoming shifts \u2014 up to 3 open shifts with date, time, location, and spots remaining
      •  
    • Latest videos \u2014 up to 4 recently published videos from the media library, displayed in a horizontal scroll strip with thumbnails and durations
      •  
    • Upcoming events \u2014 up to 3 future events from Gancio with date, location, and tags
      •  
    • Recent activity \u2014 a compact activity feed showing the latest platform actions
      •  
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/homepage/#data-caching","title":"Data & Caching","text":"
    All homepage data is fetched from a single API endpoint (/api/homepage) and cached in Redis for 2 minutes. Individual section queries use Promise.allSettled so that a failure in one module (e.g., Gancio being offline) does not prevent the rest of the page from loading.
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/homepage/#configuration","title":"Configuration","text":"
       
    • Organization name and logo \u2014 set via Settings > Organization
      •  
    • Homepage tagline \u2014 set via the homepageTagline field in site settings
      •  
    • Module visibility \u2014 controlled by feature flags (enableInfluence, enableMap, enableMediaFeatures, enableEvents, enablePayments, enableLandingPages)
      •  
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/homepage/#public-routes","title":"Public Routes","text":"
       
    • /home \u2014 public homepage
      •  
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/landing-pages/","title":"Landing Pages","text":"
    Build campaign microsites with a drag-and-drop visual editor.
     
    ","tags":["guide","admin","content","landing-pages"]},{"location":"docs/admin/web/landing-pages/#how-it-works","title":"How It Works","text":"
       
    1. Create a new page from the admin panel
      2.  
    2. Open the GrapesJS visual editor \u2014 drag blocks, edit text, adjust styles
      3.  
    3. Save and publish \u2014 the page goes live at /p/:slug
      4.  
    4. Optionally export to MkDocs for inclusion in the documentation site
      5.  
    ","tags":["guide","admin","content","landing-pages"]},{"location":"docs/admin/web/landing-pages/#admin-routes","title":"Admin Routes","text":"
       
    • /app/pages \u2014 list and manage landing pages
      •  
    • /app/pages/:id/edit \u2014 full-screen GrapesJS editor
      •  
    ","tags":["guide","admin","content","landing-pages"]},{"location":"docs/admin/web/landing-pages/#public-routes","title":"Public Routes","text":"
       
    • /p/:slug \u2014 view a published landing page
      •  
    ","tags":["guide","admin","content","landing-pages"]},{"location":"docs/admin/web/navigation/","title":"Navigation Settings","text":"
    Customize the public-facing navigation menu from the admin panel. The navigation bar appears on all public pages, the admin header, the Gancio events page, and the MkDocs documentation site.
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/navigation/#key-features","title":"Key Features","text":"
       
    • Per-item toggle -- enable or disable each navigation item with a switch
      •  
    • Custom links -- add external links or internal paths to the navigation
      •  
    • Reorder -- move items up and down to arrange them in any order
      •  
    • Editable labels and paths -- rename any item or change its destination
      •  
    • Feature flag awareness -- builtin items tied to a feature flag (e.g., Campaigns requires enableInfluence) are automatically hidden when that feature is disabled
      •  
    • Visitor control -- determine exactly what public visitors can access
      •  
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/navigation/#builtin-items","title":"Builtin Items","text":"
    The platform ships with 11 builtin navigation items that cover the main public routes:
     
    Home, Campaigns, Map, Shifts, Events, Gallery, Pricing, Shop, Donate, Website (landing page), and Docs (documentation site).
     
    Each builtin item has a default icon and path. Some paths use special $ tokens (e.g., $landing, $docs) that are automatically resolved to the correct external URL based on the deployment environment.
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/navigation/#custom-links","title":"Custom Links","text":"
    Add any number of custom links via the \"Add Custom Link\" button. Custom links support:
     
       
    • Internal paths (e.g., /blog)
      •  
    • External URLs (e.g., https://example.com) -- automatically detected and opened in a new tab
      •  
     
    Custom links can be deleted from the navigation; builtin items can only be toggled off.
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/navigation/#mobile-handling","title":"Mobile Handling","text":"
    On mobile devices, the navigation collapses into a hamburger menu that opens a full-height drawer. On desktop, the nav bar also supports a collapse mode that hides labels and shows only icons, toggled via a fold/unfold button. The collapse state is persisted in local storage.
    ","tags":["guide","admin","content"]},{"location":"docs/admin/web/navigation/#admin-routes","title":"Admin Routes","text":"
       
    • /app/navigation -- navigation editor with per-item toggle, reorder, label editing, and custom link management
      •  
    ","tags":["guide","admin","content"]},{"location":"docs/api/","title":"API Reference","text":"
    Changemaker Lite exposes two REST APIs sharing a single PostgreSQL database.
     Server Framework Port Purpose Main API Express.js 4000 Auth, campaigns, map, shifts, canvassing, pages, email, settings Media API Fastify 4100 Video library, analytics, playlists, reactions, comments 
    Both APIs use JWT Bearer authentication and return JSON. All request/response bodies are application/json unless noted otherwise.
    ","tags":["reference","developer","API"]},{"location":"docs/api/#authentication","title":"Authentication","text":"","tags":["reference","developer","API"]},{"location":"docs/api/#token-flow","title":"Token Flow","text":"
    sequenceDiagram\n    participant Client\n    participant API\n    participant DB\n\n    Client->>API: POST /api/auth/login {email, password}\n    API->>DB: Verify credentials\n    DB-->>API: User record\n    API-->>Client: {accessToken, refreshToken}\n    Note over Client: Store tokens\n\n    Client->>API: GET /api/campaigns (Authorization: Bearer <accessToken>)\n    API-->>Client: 200 OK\n\n    Note over Client: Access token expires (15 min)\n\n    Client->>API: POST /api/auth/refresh {refreshToken}\n    API->>DB: Rotate token (atomic transaction)\n    DB-->>API: New token pair\n    API-->>Client: {accessToken, refreshToken}
    ","tags":["reference","developer","API"]},{"location":"docs/api/#headers","title":"Headers","text":"
    All authenticated requests require:
     
    Authorization: Bearer <accessToken>\n
     
    The Media API also accepts tokens via query parameter for SSE streams:
     
    GET /api/public/:id/chat-stream?token=<accessToken>\n
    ","tags":["reference","developer","API"]},{"location":"docs/api/#roles","title":"Roles","text":"Role Access Level SUPER_ADMIN Full platform access INFLUENCE_ADMIN Campaign and advocacy management MAP_ADMIN Map, locations, shifts, canvassing USER Volunteer portal, public features TEMP Limited access (auto-created on public shift signup)","tags":["reference","developer","API"]},{"location":"docs/api/#middleware-reference","title":"Middleware Reference","text":"Middleware Effect authenticate Requires valid JWT. Sets req.user with id, email, role. Returns 401 if missing or invalid. optionalAuth Same as authenticate but continues without user if token is absent. requireRole(...roles) Checks user role against allowed list. Returns 403 if not authorized. requireNonTemp Blocks TEMP users. Returns 403. validate(schema, source) Validates request body/query/params against a Zod schema. Returns 400 on failure.","tags":["reference","developer","API"]},{"location":"docs/api/#error-responses","title":"Error Responses","text":"
    All errors follow a consistent format:
     
    {\n  \"error\": {\n    \"message\": \"Human-readable error description\",\n    \"code\": \"ERROR_CODE\",\n    \"statusCode\": 400\n  }\n}\n
     Status Code Meaning 400 VALIDATION_ERROR Request body/query failed schema validation 401 UNAUTHORIZED Missing or invalid access token 403 FORBIDDEN Valid token but insufficient role 404 NOT_FOUND Resource does not exist 429 RATE_LIMITED Too many requests (see Rate Limits) 500 INTERNAL_ERROR Unexpected server error 
    Enumeration Prevention
     
    Auth endpoints (/login, /register, /forgot-password) return generic success messages to prevent user enumeration. A 401 from /api/auth/me does not reveal whether the user exists.
    ","tags":["reference","developer","API"]},{"location":"docs/api/#rate-limits","title":"Rate Limits","text":"
    Rate limits are Redis-backed and keyed by IP address.
     Endpoint Group Window Max Requests Redis Prefix Auth (login, register, refresh) 15 min 10 rl:auth: Email sending 1 hour 30 rl:email: Response submission 1 hour 10 rl:response: Shift signup 1 hour 10 rl:shift-signup: Canvass visits 1 min 30 rl:canvass-visit: Canvass bulk visits 1 min 5 rl:canvass-visit-bulk: GPS tracking 1 min 6 rl:gps-tracking: Canvass geocode 1 min 10 rl:canvass-geocode: Observability 1 min 20 rl:observability: Health/metrics 1 min 30 rl:health-metrics: Global (all other) Configurable Configurable rl:global: 
    When rate-limited, the API returns:
     
    {\n  \"error\": {\n    \"message\": \"Too many requests, please try again later\",\n    \"code\": \"RATE_LIMITED\",\n    \"statusCode\": 429\n  }\n}\n
    ","tags":["reference","developer","API"]},{"location":"docs/api/#main-api-express-port-4000","title":"Main API (Express \u2014 Port 4000)","text":"","tags":["reference","developer","API"]},{"location":"docs/api/#health-metrics","title":"Health & Metrics","text":"Method Path Auth Description GET /api/health Health check \u2014 PostgreSQL + Redis ping GET /api/metrics Prometheus metrics (text/plain) Health response 
    {\n  \"status\": \"healthy\",\n  \"checks\": {\n    \"database\": \"ok\",\n    \"redis\": \"ok\"\n  }\n}\n
    ","tags":["reference","developer","API"]},{"location":"docs/api/#auth","title":"Auth","text":"
    Prefix: /api/auth
     Method Path Auth Rate Limited Description POST /api/auth/login Email + password login POST /api/auth/register Create account (always USER role) POST /api/auth/verify-email Verify email with token POST /api/auth/resend-verification Resend verification email POST /api/auth/forgot-password Send password reset email POST /api/auth/reset-password Set new password with reset token POST /api/auth/refresh Rotate refresh token \u2192 new token pair POST /api/auth/logout Invalidate refresh token GET /api/auth/me Current user profile Login request & response 
    Request: 
    {\n  \"email\": \"admin@example.com\",\n  \"password\": \"SecurePass123!\"\n}\n
     Response: 
    {\n  \"accessToken\": \"eyJhbG...\",\n  \"refreshToken\": \"eyJhbG...\",\n  \"user\": {\n    \"id\": \"uuid\",\n    \"email\": \"admin@example.com\",\n    \"name\": \"Admin\",\n    \"role\": \"SUPER_ADMIN\"\n  }\n}\n
     
    Password Policy
     
    Passwords must be at least 12 characters with at least one uppercase letter, one lowercase letter, and one digit.
    ","tags":["reference","developer","API"]},{"location":"docs/api/#users","title":"Users","text":"
    Prefix: /api/users \u00b7 Auth: All routes require authentication
     Method Path Role Description GET /api/users Admin Paginated user list with search, role, and status filters GET /api/users/:id Admin or self Single user profile POST /api/users Admin Create user PUT /api/users/:id Admin or self Update user (non-admins cannot change role/status) POST /api/users/:id/approve Admin Approve pending user; sends approval email POST /api/users/:id/reject Admin Reject pending user DELETE /api/users/:id Admin Delete user 
    Query parameters for GET /api/users:
     Param Type Description page number Page number (default 1) limit number Items per page (default 20) search string Search by name or email role string Filter by role status string Filter by status","tags":["reference","developer","API"]},{"location":"docs/api/#dashboard","title":"Dashboard","text":"
    Prefix: /api/dashboard \u00b7 Auth: Admin roles required
     Method Path Role Description GET /api/dashboard/summary Any admin Platform-wide counts (users, campaigns, locations, shifts) GET /api/dashboard/system SUPER_ADMIN Hardware + OS info (CPU, memory, disk) GET /api/dashboard/containers SUPER_ADMIN Docker container statuses GET /api/dashboard/weather Any admin Current weather at map center coordinates GET /api/dashboard/api-metrics SUPER_ADMIN Prometheus API performance metrics GET /api/dashboard/time-series SUPER_ADMIN Prometheus time-series data GET /api/dashboard/container-resources SUPER_ADMIN cAdvisor CPU/memory/network per container 
    Query parameters for GET /api/dashboard/time-series:
     Param Type Description metrics string Comma-separated metric keys (whitelist-validated) range string Time range (e.g., 1h, 24h, 7d) step string Sample interval (e.g., 5m, 1h)","tags":["reference","developer","API"]},{"location":"docs/api/#campaigns","title":"Campaigns","text":"","tags":["reference","developer","API"]},{"location":"docs/api/#admin-crud","title":"Admin CRUD","text":"
    Prefix: /api/campaigns \u00b7 Auth: Admin roles
     Method Path Description GET /api/campaigns Paginated campaign list GET /api/campaigns/:id Single campaign detail POST /api/campaigns Create campaign PUT /api/campaigns/:id Update campaign DELETE /api/campaigns/:id Delete campaign","tags":["reference","developer","API"]},{"location":"docs/api/#public","title":"Public","text":"Method Path Auth Description GET /api/campaigns/public List all active campaigns GET /api/campaigns/:slug/details Campaign detail by slug (ACTIVE only)","tags":["reference","developer","API"]},{"location":"docs/api/#user-submissions","title":"User Submissions","text":"
    Auth: Authenticated, non-TEMP users
     Method Path Description POST /api/campaigns/user/submit Submit campaign for moderation (5/hour limit) GET /api/campaigns/user/my-campaigns List own submitted campaigns PUT /api/campaigns/user/:id Edit own pending campaign","tags":["reference","developer","API"]},{"location":"docs/api/#moderation","title":"Moderation","text":"
    Auth: Admin roles
     Method Path Description GET /api/campaigns/moderation/queue Campaigns pending moderation GET /api/campaigns/moderation/stats Moderation queue statistics PATCH /api/campaigns/moderation/:id Approve or reject campaign","tags":["reference","developer","API"]},{"location":"docs/api/#campaign-emails","title":"Campaign Emails","text":"Method Path Auth Description POST /api/campaigns/:slug/send-email Send advocacy email to representatives (rate limited: 30/hour) POST /api/campaigns/:slug/track-mailto Track mailto link click GET /api/campaigns/:id/emails Admin Paginated emails for campaign GET /api/campaigns/:id/email-stats Admin Email statistics","tags":["reference","developer","API"]},{"location":"docs/api/#responses","title":"Responses","text":"
    Prefix: /api/campaigns (public) and /api/responses (admin + actions)
    ","tags":["reference","developer","API"]},{"location":"docs/api/#public_1","title":"Public","text":"Method Path Auth Description GET /api/campaigns/:slug/responses List approved public responses GET /api/campaigns/:slug/response-stats Response statistics POST /api/campaigns/:slug/responses Submit response (rate limited: 10/hour) POST /api/responses/:id/upvote Optional Upvote a response DELETE /api/responses/:id/upvote Optional Remove upvote GET /api/responses/:id/verify/:token Verify response via email link","tags":["reference","developer","API"]},{"location":"docs/api/#admin","title":"Admin","text":"
    Auth: Admin roles
     Method Path Description GET /api/responses All responses with filters PATCH /api/responses/:id/status Approve or reject response POST /api/responses/:id/resend-verification Resend verification email DELETE /api/responses/:id Delete response","tags":["reference","developer","API"]},{"location":"docs/api/#representatives","title":"Representatives","text":"
    Prefix: /api/representatives
     Method Path Auth Description GET /api/representatives/by-postal/:postalCode Lookup representatives by postal code (cache-first) GET /api/representatives/test-connection Represent API health check GET /api/representatives/cache-stats Admin Cache statistics GET /api/representatives Admin Paginated cached representatives GET /api/representatives/:id Admin Single cached representative DELETE /api/representatives/by-postal/:postalCode Admin Clear cache for postal code DELETE /api/representatives/:id Admin Delete cached representative 
    Query parameters for postal code lookup:
     Param Type Description refresh boolean Force API call, bypass cache","tags":["reference","developer","API"]},{"location":"docs/api/#email-queue","title":"Email Queue","text":"
    Prefix: /api/email-queue \u00b7 Auth: Admin roles
     Method Path Description GET /api/email-queue/stats BullMQ queue statistics (waiting, active, completed, failed) POST /api/email-queue/pause Pause email processing POST /api/email-queue/resume Resume email processing POST /api/email-queue/clean Clean completed jobs","tags":["reference","developer","API"]},{"location":"docs/api/#locations","title":"Locations","text":"
    Prefix: /api/map/locations
    ","tags":["reference","developer","API"]},{"location":"docs/api/#public_2","title":"Public","text":"Method Path Description GET /api/map/locations/public All geocoded locations for map (no PII); optional ?bounds=","tags":["reference","developer","API"]},{"location":"docs/api/#admin_1","title":"Admin","text":"
    Auth: SUPER_ADMIN or MAP_ADMIN
     Method Path Description GET /api/map/locations Paginated locations with filters GET /api/map/locations/stats Location statistics GET /api/map/locations/all All geocoded locations for admin map GET /api/map/locations/export-csv CSV export GET /api/map/locations/:id Single location GET /api/map/locations/:id/history Edit history POST /api/map/locations Create location PUT /api/map/locations/:id Update location DELETE /api/map/locations/:id Delete location POST /api/map/locations/bulk-delete Bulk delete POST /api/map/locations/geocode Geocode single address POST /api/map/locations/geocode-missing Batch geocode all ungeocoded POST /api/map/locations/reverse-geocode Reverse geocode lat/lng to address POST /api/map/locations/import-csv Import from CSV (10 MB limit) POST /api/map/locations/import-bulk Bulk NAR or standard CSV import (100 MB limit)","tags":["reference","developer","API"]},{"location":"docs/api/#bulk-geocode","title":"Bulk Geocode","text":"
    Prefix: /api/map/locations/bulk-geocode \u00b7 Auth: Map admins
     Method Path Description POST /api/map/locations/bulk-geocode Start BullMQ bulk geocoding job GET /api/map/locations/bulk-geocode/:jobId Poll job status GET /api/map/locations/bulk-geocode/stats Queue statistics","tags":["reference","developer","API"]},{"location":"docs/api/#nar-import","title":"NAR Import","text":"
    Prefix: /api/map/nar-import \u00b7 Auth: Map admins
     Method Path Description GET /api/map/nar-import/datasets Available NAR datasets by province POST /api/map/nar-import Start province import (fire-and-forget) GET /api/map/nar-import/status/:importId Poll import progress NAR Import body 
    {\n  \"provinceCode\": \"24\",\n  \"filterType\": \"city\",\n  \"filterCity\": \"Edmonton\",\n  \"residentialOnly\": true,\n  \"deduplicateRadius\": 10,\n  \"batchSize\": 500\n}\n
    ","tags":["reference","developer","API"]},{"location":"docs/api/#area-import","title":"Area Import","text":"
    Prefix: /api/map/area-import \u00b7 Auth: Map admins
     Method Path Description POST /api/map/area-import/preview Preview bounds + estimated record counts POST /api/map/area-import Start area import (fire-and-forget) GET /api/map/area-import/status/:importId Poll import progress","tags":["reference","developer","API"]},{"location":"docs/api/#cuts-polygons","title":"Cuts (Polygons)","text":"
    Prefix: /api/map/cuts
     Method Path Auth Description GET /api/map/cuts/public All public cuts as GeoJSON GET /api/map/cuts Map admin Paginated cuts list GET /api/map/cuts/:id Map admin Single cut POST /api/map/cuts Map admin Create cut (polygon GeoJSON) PUT /api/map/cuts/:id Map admin Update cut DELETE /api/map/cuts/:id Map admin Delete cut GET /api/map/cuts/:id/locations Map admin All locations within cut polygon GET /api/map/cuts/:id/statistics Map admin Support level breakdown GET /api/map/cuts/export-geojson Map admin All cuts as GeoJSON FeatureCollection GET /api/map/cuts/:id/export-geojson Map admin Single cut as GeoJSON Feature POST /api/map/cuts/import-geojson Map admin Import cuts from GeoJSON file","tags":["reference","developer","API"]},{"location":"docs/api/#shifts","title":"Shifts","text":"
    Prefix: /api/map/shifts
    ","tags":["reference","developer","API"]},{"location":"docs/api/#public_3","title":"Public","text":"Method Path Description GET /api/map/shifts/public List upcoming public shifts POST /api/map/shifts/public/:id/signup Public signup (creates TEMP user if needed; rate limited: 10/hour)","tags":["reference","developer","API"]},{"location":"docs/api/#volunteer","title":"Volunteer","text":"
    Auth: Any authenticated user
     Method Path Description GET /api/map/shifts/volunteer/upcoming Upcoming shifts with signup status GET /api/map/shifts/volunteer/my-signups Own confirmed signups POST /api/map/shifts/volunteer/:id/signup Sign up for shift DELETE /api/map/shifts/volunteer/:id/signup Cancel signup","tags":["reference","developer","API"]},{"location":"docs/api/#admin_2","title":"Admin","text":"
    Auth: Map admins
     Method Path Description GET /api/map/shifts Paginated shifts with filters GET /api/map/shifts/stats Statistics GET /api/map/shifts/calendar Calendar data (?startDate=&endDate=) GET /api/map/shifts/:id Single shift with signups POST /api/map/shifts Create shift PUT /api/map/shifts/:id Update shift DELETE /api/map/shifts/:id Delete shift POST /api/map/shifts/:id/signups Admin-add volunteer DELETE /api/map/shifts/:id/signups/:signupId Remove volunteer POST /api/map/shifts/:id/email-details Email details to all volunteers","tags":["reference","developer","API"]},{"location":"docs/api/#shift-series","title":"Shift Series","text":"
    Auth: Map admins
     Method Path Description POST /api/map/shifts/series Create recurring shift series GET /api/map/shifts/series/:id Get series PUT /api/map/shifts/series/:id Update series DELETE /api/map/shifts/series/:id Delete series","tags":["reference","developer","API"]},{"location":"docs/api/#canvassing","title":"Canvassing","text":"
    Prefix: /api/map/canvass
    ","tags":["reference","developer","API"]},{"location":"docs/api/#volunteer_1","title":"Volunteer","text":"
    Auth: Any authenticated user
     Method Path Description GET /api/map/canvass/my/assignments Shift assignments GET /api/map/canvass/my/stats Personal canvass statistics GET /api/map/canvass/my/visits Visit history GET /api/map/canvass/my/session Active canvass session POST /api/map/canvass/sessions Start canvass session POST /api/map/canvass/sessions/:id/end End session GET /api/map/canvass/cuts/:cutId/locations Locations in cut with visit annotations GET /api/map/canvass/cuts/:cutId/route Walking route algorithm for cut GET /api/map/canvass/locations All locations with visit annotations PUT /api/map/canvass/locations/:id Edit address (role-gated fields) POST /api/map/canvass/locations Create location POST /api/map/canvass/reverse-geocode Reverse geocode lat/lng POST /api/map/canvass/geocode-search Geocode address for map (rate limited: 10/min) POST /api/map/canvass/visits Record door knock (rate limited: 30/min) POST /api/map/canvass/visits/bulk Record visit for all unvisited units (rate limited: 5/min)","tags":["reference","developer","API"]},{"location":"docs/api/#admin_3","title":"Admin","text":"
    Auth: SUPER_ADMIN or MAP_ADMIN
     Method Path Description GET /api/map/canvass/stats Platform-wide canvass statistics GET /api/map/canvass/stats/cuts/:cutId Statistics for specific cut GET /api/map/canvass/activity Recent activity feed GET /api/map/canvass/volunteers All volunteers with canvass activity GET /api/map/canvass/volunteers/:userId Individual volunteer statistics GET /api/map/canvass/visits All visits with filters","tags":["reference","developer","API"]},{"location":"docs/api/#gps-tracking","title":"GPS Tracking","text":"
    Prefix: /api/map/tracking
    ","tags":["reference","developer","API"]},{"location":"docs/api/#volunteer_2","title":"Volunteer","text":"
    Auth: Any authenticated user
     Method Path Description POST /api/map/tracking/sessions Start GPS tracking session POST /api/map/tracking/sessions/:id/end End tracking session POST /api/map/tracking/sessions/:id/points Submit GPS point batch (rate limited: 6/min) POST /api/map/tracking/sessions/:id/link-canvass Link to canvass session GET /api/map/tracking/my/session Active tracking session GET /api/map/tracking/my/sessions Own historical sessions GET /api/map/tracking/my/sessions/:id/route Full route for own session","tags":["reference","developer","API"]},{"location":"docs/api/#admin_4","title":"Admin","text":"
    Auth: Map admins
     Method Path Description GET /api/map/tracking/live Live volunteer positions + trails GET /api/map/tracking/sessions All historical tracking sessions GET /api/map/tracking/sessions/:id/route Full route for any session","tags":["reference","developer","API"]},{"location":"docs/api/#map-settings","title":"Map Settings","text":"
    Prefix: /api/map/settings
     Method Path Auth Description GET /api/map/settings Public map settings (center, zoom, walk sheet config) PUT /api/map/settings Map admin Update map settings","tags":["reference","developer","API"]},{"location":"docs/api/#geocoding","title":"Geocoding","text":"
    Prefix: /api/map/geocoding \u00b7 Auth: Map admins
     Method Path Description GET /api/map/geocoding/search Geocode address search (?q=&limit=1-10)","tags":["reference","developer","API"]},{"location":"docs/api/#landing-pages","title":"Landing Pages","text":"
    Prefix: /api/pages and /api/page-blocks
    ","tags":["reference","developer","API"]},{"location":"docs/api/#public_4","title":"Public","text":"Method Path Auth Description GET /api/pages/:slug/view Get published page by slug","tags":["reference","developer","API"]},{"location":"docs/api/#admin_5","title":"Admin","text":"
    Auth: Admin roles
     Method Path Description GET /api/pages Paginated landing pages GET /api/pages/:id Single page POST /api/pages Create page PUT /api/pages/:id Update page DELETE /api/pages/:id Delete page POST /api/pages/sync Sync MkDocs overrides from filesystem POST /api/pages/validate Validate and repair MkDocs exports","tags":["reference","developer","API"]},{"location":"docs/api/#block-library","title":"Block Library","text":"
    Auth: Admin roles
     Method Path Description GET /api/page-blocks List blocks GET /api/page-blocks/:id Single block POST /api/page-blocks Create block PUT /api/page-blocks/:id Update block DELETE /api/page-blocks/:id Delete block","tags":["reference","developer","API"]},{"location":"docs/api/#email-templates","title":"Email Templates","text":"
    Prefix: /api/email-templates \u00b7 Auth: Admin roles (seed/cache require SUPER_ADMIN)
     Method Path Description GET /api/email-templates List templates GET /api/email-templates/:id Single template POST /api/email-templates Create template PUT /api/email-templates/:id Update template DELETE /api/email-templates/:id Delete template GET /api/email-templates/:id/versions Version history GET /api/email-templates/:id/versions/:versionNumber Specific version POST /api/email-templates/:id/rollback Rollback to prior version POST /api/email-templates/validate Validate Handlebars syntax POST /api/email-templates/:id/test Send test email (rate limited: 10/15min) GET /api/email-templates/:id/test-logs Test send logs POST /api/email-templates/seed Seed templates from filesystem POST /api/email-templates/clear-cache Clear template cache","tags":["reference","developer","API"]},{"location":"docs/api/#qr-codes","title":"QR Codes","text":"Method Path Auth Description GET /api/qr Generate QR code PNG (?text=&size=50-500) 
    Cached for 1 hour. Returns image/png.
    ","tags":["reference","developer","API"]},{"location":"docs/api/#site-settings","title":"Site Settings","text":"
    Prefix: /api/settings
     Method Path Auth Description GET /api/settings Public site settings (SMTP credentials stripped) GET /api/settings/admin SUPER_ADMIN Full settings including SMTP credentials PUT /api/settings SUPER_ADMIN Update settings POST /api/settings/email/test-connection SUPER_ADMIN Test SMTP connection POST /api/settings/email/test-send SUPER_ADMIN Send test email","tags":["reference","developer","API"]},{"location":"docs/api/#listmonk-newsletter-sync","title":"Listmonk (Newsletter Sync)","text":"
    Prefix: /api/listmonk \u00b7 Auth: SUPER_ADMIN
     Method Path Description GET /api/listmonk Sync status + connection check GET /api/listmonk/stats Subscriber counts from Listmonk POST /api/listmonk/test-connection Health check POST /api/listmonk/sync/participants Sync campaign participants POST /api/listmonk/sync/locations Sync locations POST /api/listmonk/sync/users Sync users POST /api/listmonk/sync/all Run all sync operations POST /api/listmonk/reinitialize Reinitialize Listmonk lists GET /api/listmonk/proxy-url Proxy port + JWT for iframe","tags":["reference","developer","API"]},{"location":"docs/api/#documentation-management","title":"Documentation Management","text":"
    Prefix: /api/docs \u00b7 Auth: Authenticated, non-TEMP (write operations require SUPER_ADMIN)
     Method Path Description GET /api/docs/status MkDocs + Code Server availability GET /api/docs/config Port numbers for iframe URLs GET /api/docs/mkdocs-config Read raw mkdocs.yml PUT /api/docs/mkdocs-config Write mkdocs.yml POST /api/docs/build Trigger MkDocs build POST /api/docs/upload Upload asset (20 MB, whitelisted extensions) GET /api/docs/files File tree (?force=true bypasses cache) POST /api/docs/files/rename Rename or move file GET /api/docs/files/* Read file content PUT /api/docs/files/* Write file content POST /api/docs/files/* Create file or folder DELETE /api/docs/files/* Delete file or empty folder","tags":["reference","developer","API"]},{"location":"docs/api/#services","title":"Services","text":"
    Prefix: /api/services \u00b7 Auth: SUPER_ADMIN
     Method Path Description GET /api/services/status Health check all managed services (NocoDB, n8n, Gitea, MailHog, Mini QR, Excalidraw, Homepage) GET /api/services/config Port numbers + subdomain info","tags":["reference","developer","API"]},{"location":"docs/api/#pangolin-tunnel-management","title":"Pangolin (Tunnel Management)","text":"
    Prefix: /api/pangolin \u00b7 Auth: SUPER_ADMIN
     Method Path Description GET /api/pangolin/status Tunnel health + connection info GET /api/pangolin/config Current env configuration GET /api/pangolin/newt-status Newt container status POST /api/pangolin/newt-restart Restart Newt container GET /api/pangolin/sites List Pangolin sites GET /api/pangolin/exit-nodes Available exit nodes GET /api/pangolin/resource-definitions Resource definitions from YAML GET /api/pangolin/resources List resources POST /api/pangolin/setup Create site + all resources (rate limited: \u2157min) POST /api/pangolin/sync Sync resources (create missing, update changed) PUT /api/pangolin/resource/:id Update resource DELETE /api/pangolin/resource/:id Delete resource GET /api/pangolin/resource/:id/clients Connected clients GET /api/pangolin/certificate/:domainId/:domain Certificate info POST /api/pangolin/certificate/:certId Update certificate","tags":["reference","developer","API"]},{"location":"docs/api/#observability","title":"Observability","text":"
    Prefix: /api/observability \u00b7 Auth: SUPER_ADMIN \u00b7 Rate limited: 20/min
     Method Path Description GET /api/observability/status Check 7 monitoring services GET /api/observability/metrics-summary Key metrics from Prometheus GET /api/observability/alerts Active alerts from Alertmanager","tags":["reference","developer","API"]},{"location":"docs/api/#payments","title":"Payments","text":"
    Prefix: /api/payments
    ","tags":["reference","developer","API"]},{"location":"docs/api/#public_5","title":"Public","text":"Method Path Auth Description GET /api/payments/config Stripe publishable key + donation settings GET /api/payments/plans Active subscription plans GET /api/payments/products Active products (?type=) POST /api/payments/subscribe Create subscription checkout POST /api/payments/purchase Optional Product checkout (guest or logged-in) POST /api/payments/donate Donation checkout GET /api/payments/my-subscription Current subscription POST /api/payments/my-subscription/cancel Cancel subscription POST /api/payments/webhook Stripe webhook (raw body)","tags":["reference","developer","API"]},{"location":"docs/api/#admin_6","title":"Admin","text":"
    Auth: SUPER_ADMIN
     Method Path Description GET /api/payments/admin/settings Payment settings (secrets masked) PUT /api/payments/admin/settings Update payment settings POST /api/payments/admin/settings/test-connection Test Stripe connection GET /api/payments/admin/dashboard Subscription + donation statistics GET /api/payments/admin/plans All subscription plans POST /api/payments/admin/plans Create plan PUT /api/payments/admin/plans/:id Update plan DELETE /api/payments/admin/plans/:id Delete plan POST /api/payments/admin/plans/:id/sync-stripe Sync plan to Stripe GET /api/payments/admin/subscriptions All subscriptions with filters POST /api/payments/admin/subscriptions/:id/cancel Cancel subscription GET /api/payments/admin/products All products POST /api/payments/admin/products Create product PUT /api/payments/admin/products/:id Update product DELETE /api/payments/admin/products/:id Delete product POST /api/payments/admin/products/:id/sync-stripe Sync product to Stripe GET /api/payments/admin/orders List orders POST /api/payments/admin/orders/:id/refund Refund order GET /api/payments/admin/donations List donations GET /api/payments/admin/export CSV export of completed orders","tags":["reference","developer","API"]},{"location":"docs/api/#media-api-fastify-port-4100","title":"Media API (Fastify \u2014 Port 4100)","text":"
    The Media API is a separate Fastify server sharing the same PostgreSQL database. It handles all video-related functionality.
    ","tags":["reference","developer","API"]},{"location":"docs/api/#health","title":"Health","text":"Method Path Auth Description GET /health Media API health check","tags":["reference","developer","API"]},{"location":"docs/api/#videos-admin","title":"Videos (Admin)","text":"
    Prefix: /api/videos \u00b7 Auth: Admin roles
    ","tags":["reference","developer","API"]},{"location":"docs/api/#crud-publishing","title":"CRUD & Publishing","text":"Method Path Description GET /api/videos List videos (?limit=&offset=&search=&orientation=&producers=&isShort=) GET /api/videos/producers Distinct producer list GET /api/videos/health Video count health check GET /api/videos/:id Single video detail PATCH /api/videos/:id Update metadata (title, producer, tags, quality, etc.) POST /api/videos/:id/publish Publish to category POST /api/videos/:id/unpublish Unpublish POST /api/videos/bulk-publish Bulk publish POST /api/videos/bulk-unpublish Bulk unpublish POST /api/videos/:id/lock Lock published video POST /api/videos/:id/unlock Unlock video POST /api/videos/:id/generate-thumbnail Generate thumbnail via FFmpeg POST /api/videos/bulk-generate-thumbnails Bulk thumbnail generation","tags":["reference","developer","API"]},{"location":"docs/api/#upload","title":"Upload","text":"Method Path Description POST /api/videos/upload Single video upload (multipart, 10 GB limit, streams to disk) POST /api/videos/upload/batch Batch upload (returns 207 multi-status)","tags":["reference","developer","API"]},{"location":"docs/api/#actions","title":"Actions","text":"Method Path Description POST /api/videos/:id/duplicate Duplicate video record POST /api/videos/:id/replace Replace video file, keep metadata GET /api/videos/:id/analytics Detailed analytics (?startDate=&endDate=) POST /api/videos/:id/reset-analytics Reset all analytics GET /api/videos/:id/preview-link Generate 24-hour JWT preview link GET /api/videos/analytics/top Top videos (?metric=views|watchTime&limit=) GET /api/videos/analytics/overview Global analytics overview","tags":["reference","developer","API"]},{"location":"docs/api/#scheduling","title":"Scheduling","text":"Method Path Description POST /api/videos/:id/schedule-publish Schedule future publish ({publishAt, timezone?}) POST /api/videos/:id/schedule-unpublish Schedule future unpublish DELETE /api/videos/:id/schedule/:action Cancel scheduled operation GET /api/videos/schedules/upcoming Upcoming scheduled operations GET /api/videos/:id/schedule-history Schedule history for video GET /api/videos/schedules/stats Schedule queue statistics POST /api/videos/schedules/pause Pause schedule queue POST /api/videos/schedules/resume Resume schedule queue POST /api/videos/schedules/cleanup Clean old completed jobs","tags":["reference","developer","API"]},{"location":"docs/api/#video-fetch","title":"Video Fetch","text":"Method Path Description POST /api/videos/fetch Submit fetch job ({urls: string[]}, 1\u201320 URLs) GET /api/videos/fetch/jobs List recent fetch jobs GET /api/videos/fetch/jobs/:jobId Job detail + log GET /api/videos/fetch/jobs/:jobId/log SSE log stream (Redis pub/sub) DELETE /api/videos/fetch/jobs/:jobId Cancel fetch job","tags":["reference","developer","API"]},{"location":"docs/api/#streaming-public","title":"Streaming (Public)","text":"
    Prefix: /api/videos
     Method Path Auth Description GET /api/videos/stream/health Streaming health check GET /api/videos/:id/stream Optional HTTP range-supporting video stream GET /api/videos/:id/thumbnail Optional Serve thumbnail image GET /api/videos/:id/metadata Public video metadata for embedding 
    Note
     
    Admins can stream unpublished videos by providing a valid JWT.
    ","tags":["reference","developer","API"]},{"location":"docs/api/#public-gallery","title":"Public Gallery","text":"
    Prefix: /api/public
     Method Path Auth Description GET /api/public Optional Published videos (?limit=&offset=&search=&sort=recent|popular|oldest&category=) GET /api/public/categories Optional Categories with video counts GET /api/public/producers Optional Published producers GET /api/public/:id Optional Single published video GET /api/public/:id/thumbnail Optional Published thumbnail GET /api/public/:id/stream Optional Published video stream","tags":["reference","developer","API"]},{"location":"docs/api/#tracking","title":"Tracking","text":"
    Prefix: /api/track \u00b7 Auth: None required
     Method Path Description GET /api/track/health Tracking health check POST /api/track/view Record video view (returns {viewId}) POST /api/track/event Record play/pause/seek/complete event POST /api/track/heartbeat Update watch time (10s interval, sendBeacon) POST /api/track/batch Batch up to 50 tracking events Tracking is GDPR-compliant 
    IP addresses are hashed with a daily-rotating salt. Raw IPs are never stored. Tracking data is retained for 90 days.
    ","tags":["reference","developer","API"]},{"location":"docs/api/#reactions","title":"Reactions","text":"
    Prefix: /api/reactions
     Method Path Auth Description GET /api/reactions/config Available reaction types + emoji mappings GET /api/reactions List reactions (?mediaId=&userId=&limit=) GET /api/reactions/:mediaId/chat Reactions in chat timeline format POST /api/reactions Add reaction (30s cooldown per type) 
    Available types: like, love, laugh, wow, sad, angry
    ","tags":["reference","developer","API"]},{"location":"docs/api/#comments-chat","title":"Comments & Chat","text":"","tags":["reference","developer","API"]},{"location":"docs/api/#public-comments","title":"Public Comments","text":"Method Path Auth Description GET /api/public/:id/comments List comments (?limit=&offset=) POST /api/public/:id/comments Optional Create comment (word-filtered; rate limited: 5/min) GET /api/public/:id/chat-stream SSE stream for real-time chat (30s keepalive)","tags":["reference","developer","API"]},{"location":"docs/api/#comment-admin","title":"Comment Admin","text":"
    Prefix: /api/media/admin/comments \u00b7 Auth: Admin roles
     Method Path Description GET /api/media/admin/comments/stats Counts by status GET /api/media/admin/comments All comments with filters PATCH /api/media/admin/comments/:id/approve Approve comment PATCH /api/media/admin/comments/:id/hide Hide comment PATCH /api/media/admin/comments/:id/unhide Unhide comment PUT /api/media/admin/comments/:id/notes Update moderation notes DELETE /api/media/admin/comments/:id Delete comment","tags":["reference","developer","API"]},{"location":"docs/api/#word-filters","title":"Word Filters","text":"
    Prefix: /api/media/admin/word-filters \u00b7 Auth: Admin roles
     Method Path Description GET /api/media/admin/word-filters List filter entries grouped by level POST /api/media/admin/word-filters Add word ({word, level: low|medium|high|custom}) DELETE /api/media/admin/word-filters/:id Remove word","tags":["reference","developer","API"]},{"location":"docs/api/#chat-threads-notifications","title":"Chat Threads & Notifications","text":"
    Auth: Authenticated
     Method Path Description GET /api/media/chat/threads Videos with user's comments + unread counts POST /api/media/chat/threads/:mediaId/read Mark thread as read GET /api/media/notifications/stream Per-user SSE notification stream (?token=)","tags":["reference","developer","API"]},{"location":"docs/api/#shorts","title":"Shorts","text":"Method Path Auth Description GET /api/shorts Optional Shorts feed (?sort=recent|popular|random) POST /api/shorts/scan Admin Auto-classify short videos by duration","tags":["reference","developer","API"]},{"location":"docs/api/#upvotes","title":"Upvotes","text":"Method Path Auth Description POST /api/public/:id/upvote Toggle upvote (session-based via X-Session-ID header) GET /api/public/:id/upvote-status Check upvote status for current session","tags":["reference","developer","API"]},{"location":"docs/api/#playlists","title":"Playlists","text":"","tags":["reference","developer","API"]},{"location":"docs/api/#public_6","title":"Public","text":"
    Prefix: /api/playlists
     Method Path Auth Description GET /api/playlists/featured Optional Featured playlists GET /api/playlists/popular Optional Popular public playlists (?search=) GET /api/playlists/share/:token Optional Playlist by share token GET /api/playlists/:id Optional Playlist detail (public, owner, or share token) POST /api/playlists/:id/view Optional Record playlist view","tags":["reference","developer","API"]},{"location":"docs/api/#user-playlists","title":"User Playlists","text":"
    Auth: Authenticated
     Method Path Description GET /api/playlists/my Own playlists POST /api/playlists Create playlist PUT /api/playlists/:id Update playlist (ownership check) DELETE /api/playlists/:id Delete playlist POST /api/playlists/:id/videos Add video ({mediaId}) DELETE /api/playlists/:id/videos/:mediaId Remove video PUT /api/playlists/:id/videos/reorder Reorder videos POST /api/playlists/:id/share Generate share token DELETE /api/playlists/:id/share Revoke share token","tags":["reference","developer","API"]},{"location":"docs/api/#playlist-admin","title":"Playlist Admin","text":"
    Prefix: /api/media/playlists \u00b7 Auth: Admin roles
     Method Path Description GET /api/media/playlists All playlists GET /api/media/playlists/featured Featured playlists with admin info POST /api/media/playlists/:id/feature Feature a playlist DELETE /api/media/playlists/:id/feature Unfeature a playlist PUT /api/media/playlists/featured/reorder Reorder featured playlists PUT /api/media/playlists/:id Admin update any playlist POST /api/media/playlists/:id/duplicate Duplicate playlist DELETE /api/media/playlists/:id Admin delete any playlist","tags":["reference","developer","API"]},{"location":"docs/api/#user-profile","title":"User Profile","text":"
    Prefix: /api/media/me \u00b7 Auth: Authenticated
     Method Path Description GET /api/media/me/stats User stats + 30-day activity + achievements GET /api/media/me/watch-history Paginated watch history POST /api/media/me/stats/recalculate Recompute stats from raw data GET /api/media/me/settings Privacy settings PUT /api/media/me/settings Update privacy settings PUT /api/media/me/profile Update display name PUT /api/media/me/password Change password","tags":["reference","developer","API"]},{"location":"docs/api/#route-summary","title":"Route Summary","text":"API Module Endpoint Count Express Auth 9 Users 7 Dashboard 7 Campaigns (CRUD + public + user + moderation + emails) 16 Responses 10 Email Queue 4 Representatives 7 Locations (CRUD + geocode + import) 21 Cuts 11 Shifts (CRUD + series) 19 Canvassing 20 GPS Tracking 10 Map Settings + Geocoding 3 Pages + Blocks 12 Email Templates 13 QR Codes 1 Site Settings 5 Listmonk 9 Docs Management 11 Services 2 Pangolin 16 Observability 3 Payments (public + admin) 29 Health + Metrics 3 Express Total ~248 Fastify Videos (CRUD + upload + actions + schedule + fetch) 39 Streaming 4 Public Gallery 6 Tracking 5 Reactions 4 Comments + Chat 13 Shorts + Upvotes 4 Playlists (public + user + admin) 18 User Profile 7 Health 1 Fastify Total ~101 Grand Total ~349","tags":["reference","developer","API"]},{"location":"docs/architecture/","title":"Architecture","text":"
    Changemaker Lite uses a dual-API architecture with a shared PostgreSQL database, a React single-page application, and Nginx for subdomain routing across 30+ services.
    ","tags":["reference","developer","architecture"]},{"location":"docs/architecture/#system-diagram","title":"System Diagram","text":"
    graph LR\n    Browser[\"Browser\"] --> Nginx[\"Nginx<br/>(reverse proxy)\"]\n    Nginx --> Admin[\"React Admin GUI<br/>port 3000\"]\n    Nginx --> API[\"Express API<br/>port 4000\"]\n    Nginx --> MediaAPI[\"Fastify Media API<br/>port 4100\"]\n    Nginx --> MkDocs[\"MkDocs<br/>port 4003/4004\"]\n    Nginx --> Services[\"Other Services<br/>(Gitea, NocoDB, etc.)\"]\n\n    API --> PostgreSQL[(\"PostgreSQL 16<br/>30+ tables\")]\n    MediaAPI --> PostgreSQL\n    API --> Redis[(\"Redis<br/>cache + queues\")]\n    API --> BullMQ[\"BullMQ<br/>(email, video jobs)\"]\n    BullMQ --> Redis\n\n    subgraph Tunnel [\"Public Access\"]\n        Newt[\"Newt Client\"] --> Pangolin[\"Pangolin Server\"]\n    end\n    Newt --> Nginx
    ","tags":["reference","developer","architecture"]},{"location":"docs/architecture/#key-components","title":"Key Components","text":"Component Technology Role Main API Express.js + TypeScript + Prisma Auth, campaigns, map, shifts, pages, canvassing, email Media API Fastify + TypeScript + Prisma Video library, analytics, uploads, scheduling Admin GUI React 19 + Vite + Ant Design + Zustand Admin dashboard, public pages, volunteer portal, media gallery Database PostgreSQL 16 Shared by both APIs (30+ models via Prisma) Cache Redis 7 Rate limiting, BullMQ job queues, geocoding cache Proxy Nginx Subdomain routing, security headers, WebSocket upgrade Tunnel Pangolin + Newt Expose services without port forwarding Monitoring Prometheus + Grafana + Alertmanager Metrics collection, dashboards, alerting","tags":["reference","developer","architecture"]},{"location":"docs/architecture/#dual-api-design","title":"Dual API Design","text":"
    The platform runs two independent API servers sharing one PostgreSQL database:
     Express API (port 4000)Fastify Media API (port 4100) 
    The main API handles all core platform logic:
     
       
    • Authentication \u2014 JWT access/refresh tokens, RBAC middleware
      •  
    • Modules \u2014 Influence (campaigns, responses), Map (locations, cuts, shifts, canvassing), Pages, Email Templates, Settings, Users, Payments, Social, Calendar
      •  
    • Services \u2014 Email queue (BullMQ), geocoding queue, Listmonk sync, Pangolin client, user provisioning
      •  
    • ORM \u2014 Prisma with 30+ models and migration history
      •  
     
    A separate server optimized for media handling:
     
       
    • Video CRUD \u2014 Upload with FFprobe metadata extraction
      •  
    • Scheduled Publishing \u2014 BullMQ queue with timezone support
      •  
    • Analytics \u2014 View tracking, watch time, completion rates (GDPR-compliant)
      •  
    • Public Gallery \u2014 Playlists, reactions, comments, SSE chat
      •  
    • ORM \u2014 Prisma (migrated from Drizzle, Feb 2026)
      •  
     
    Both servers connect to the same database and share the same Prisma schema. This separation allows the media API to handle large file uploads and streaming independently from the main API's request/response cycle.
    ","tags":["reference","developer","architecture"]},{"location":"docs/architecture/#authentication-flow","title":"Authentication Flow","text":"
    sequenceDiagram\n    participant Client\n    participant API\n    participant DB\n    participant Redis\n\n    Client->>API: POST /api/auth/login {email, password}\n    API->>Redis: Check rate limit (10/min per IP)\n    Redis-->>API: OK\n    API->>DB: Verify bcrypt password\n    DB-->>API: User record\n    API->>DB: Create refresh token\n    API-->>Client: {accessToken (15min), refreshToken (7d)}\n\n    Note over Client: Authenticated requests\n    Client->>API: GET /api/campaigns<br/>Authorization: Bearer <accessToken>\n    API->>API: Verify JWT + check role (RBAC)\n    API-->>Client: 200 OK\n\n    Note over Client: Token expired\n    Client->>API: POST /api/auth/refresh {refreshToken}\n    API->>DB: Atomic rotation (delete old, create new)\n    API-->>Client: {new accessToken, new refreshToken}
    ","tags":["reference","developer","architecture"]},{"location":"docs/architecture/#security-features","title":"Security Features","text":"
       
    • Password policy \u2014 12+ characters, uppercase, lowercase, digit (schema-enforced)
      •  
    • Refresh token rotation \u2014 Atomic Prisma transaction prevents race conditions
      •  
    • User enumeration prevention \u2014 Returns 401 (not 404) for missing users
      •  
    • Rate limiting \u2014 10 requests/minute on auth endpoints via Redis
      •  
    • 11 roles \u2014 SUPER_ADMIN (implicit bypass), 8 module-specific admin roles, USER, TEMP
      •  
    • Encryption \u2014 AES-256-GCM for sensitive DB fields (ENCRYPTION_KEY env var)
      •  
    ","tags":["reference","developer","architecture"]},{"location":"docs/architecture/#request-lifecycle","title":"Request Lifecycle","text":"
    graph TD\n    A[\"Incoming Request\"] --> B[\"Nginx\"]\n    B -->|\"Host: api.domain\"| C[\"Express API\"]\n    B -->|\"Host: media.domain\"| D[\"Fastify Media API\"]\n    B -->|\"Host: app.domain\"| E[\"React Admin GUI\"]\n    C --> F[\"Rate Limiter (Redis)\"]\n    F --> G[\"Auth Middleware (JWT)\"]\n    G --> H[\"Role Check (RBAC)\"]\n    H --> I[\"Validation (Zod)\"]\n    I --> J[\"Route Handler\"]\n    J --> K[\"Service Layer\"]\n    K --> L[\"Prisma ORM\"]\n    L --> M[(\"PostgreSQL\")]\n    J --> N[\"Response + Metrics\"]
    ","tags":["reference","developer","architecture"]},{"location":"docs/architecture/#database-schema","title":"Database Schema","text":"
    The database contains 30+ Prisma models organized by module:
     Module Key Models Auth User, RefreshToken Influence Campaign, CampaignEmail, CampaignResponse, Representative, PostalCode Map Location, Address, Cut, Shift, ShiftSignup Canvass CanvassSession, CanvassVisit, TrackingSession, TrackingPoint Pages Page, PageBlock, EmailTemplate Media Video, VideoReaction, VideoComment, VideoView, Playlist, PlaylistVideo Payments StripeProduct, StripePrice, StripeDonationPage, StripeOrder Social Friendship, SocialNotification, CalendarLayer, CalendarItem SMS SmsContactList, SmsCampaign, SmsMessage, SmsConversation People Contact, ContactAddress, ContactEmail, ContactPhone, ContactConnection Settings SiteSettings, MapSettings","tags":["reference","developer","architecture"]},{"location":"docs/architecture/#docker-compose-architecture","title":"Docker Compose Architecture","text":"
    Services are organized into categories with dependency management:
     
    graph TD\n    subgraph Core [\"Core (always started)\"]\n        PG[\"PostgreSQL\"] --> API[\"Express API\"]\n        Redis --> API\n        PG --> Media[\"Fastify Media API\"]\n        API --> Admin[\"React Admin\"]\n        Admin --> Nginx\n        API --> Nginx\n        Media --> Nginx\n    end\n\n    subgraph Communication [\"Communication (optional)\"]\n        RC[\"Rocket.Chat\"] --> MongoDB\n        Jitsi[\"Jitsi Meet (4 containers)\"]\n        Gancio[\"Gancio Events\"]\n    end\n\n    subgraph Monitoring [\"Monitoring (profile)\"]\n        Prometheus --> Grafana\n        Prometheus --> Alertmanager\n        cAdvisor --> Prometheus\n        NodeExporter --> Prometheus\n    end\n\n    subgraph Tunnel [\"Tunnel\"]\n        Newt --> Nginx\n    end
     
    Docker healthchecks ensure proper startup order: PostgreSQL and Redis must be healthy before the API starts. The API runs migrations and seeding automatically via its entrypoint script.
    ","tags":["reference","developer","architecture"]},{"location":"docs/architecture/#subdomain-routing","title":"Subdomain Routing","text":"
    Nginx routes requests based on the Host header. All services run on the changemaker-lite Docker bridge network.
     Pattern Target app.DOMAIN Admin GUI (admin + public + volunteer + gallery) api.DOMAIN Express API media.DOMAIN Fastify Media API DOMAIN (root) MkDocs static site *.DOMAIN 15+ additional service subdomains 
    See Services for the complete subdomain table.
    ","tags":["reference","developer","architecture"]},{"location":"docs/deployment/","title":"Deployment","text":"
    This guide covers how to take Changemaker Lite from a local development setup to a publicly accessible production deployment. The main decision is how to expose your services to the internet.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#architecture-overview","title":"Architecture Overview","text":"
    Regardless of which exposure method you choose, the internal architecture is the same:
     
    Internet \u2192 [Your exposure method] \u2192 Nginx (port 80) \u2192 Backend Services\n
     
    Nginx handles all subdomain routing internally. Every service is accessed through nginx on port 80, which proxies to the correct container based on the Host header.
     Subdomain Service Container Port app.DOMAIN Admin GUI + public pages 3000 api.DOMAIN Express API 4000 media.DOMAIN Fastify Media API 4100 DOMAIN (root) MkDocs documentation site 4004 db.DOMAIN NocoDB 8091 docs.DOMAIN MkDocs live preview 4003 code.DOMAIN Code Server 8888 git.DOMAIN Gitea 3030 n8n.DOMAIN Workflow automation 5678 home.DOMAIN Homepage dashboard 3010 listmonk.DOMAIN Newsletter manager 9001 mail.DOMAIN MailHog (dev email) 8025 qr.DOMAIN Mini QR generator 8089 draw.DOMAIN Excalidraw whiteboard 8090 vault.DOMAIN Vaultwarden password manager 8445 chat.DOMAIN Rocket.Chat team chat \u2014 events.DOMAIN Gancio event management 8092 grafana.DOMAIN Monitoring dashboards 3005","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#exposure-methods","title":"Exposure Methods","text":"","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#pangolin","title":"Option 1: Pangolin + Newt Tunnel (Recommended)","text":"
    Admin GUI: Tunnel Management Page
     
    The admin dashboard includes a dedicated Tunnel Management page at Admin \u2192 Settings \u2192 Tunnel. This page provides:
     
       
    • Live status of the Pangolin connection and Newt container health
      •  
    • Step-by-step setup instructions if credentials aren't configured yet
      •  
    • Full resource table listing every service, its domain, and target \u2014 useful as a reference when creating resources in the Pangolin dashboard
      •  
    • API-based site creation as an alternative to the Pangolin dashboard UI
      •  
    • Restart Newt button for quick container restarts without the terminal
      •  
     
    If you're unsure about any step above, the Tunnel page walks you through the same process interactively.
     
    Pangolin is a self-hosted tunnel server. The Newt client container runs alongside your stack and establishes an outbound connection to your Pangolin server, which then routes public traffic back through the tunnel. No port forwarding or static IP required.
     
    Advantages:
     
       
    • No port forwarding needed on your router/firewall
      •  
    • Works behind CGNAT, double NAT, or restrictive networks
      •  
    • SSL/TLS handled by the Pangolin server
      •  
    • Self-hosted \u2014 you control the tunnel infrastructure
      •  
    • Built-in access control (optional per-resource authentication)
      •  
     
    Requirements:
     
       
    • A Pangolin server (self-hosted on a VPS with a public IP)
      •  
    • A domain with DNS pointing to the Pangolin server
      •  
    • Pangolin API key and organization ID
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#step-1-configure-pangolin-credentials","title":"Step 1: Configure Pangolin Credentials","text":"
    If you used config.sh, you may have already set these. Otherwise, add to your .env:
     
    PANGOLIN_API_URL=https://api.your-pangolin-server.org/v1\nPANGOLIN_API_KEY=your_api_key_here\nPANGOLIN_ORG_ID=your_org_id\n
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#step-2-create-a-site-in-pangolin","title":"Step 2: Create a Site in Pangolin","text":"
    Log in to your Pangolin dashboard and create a new site:
     
       
    1. Navigate to Sites \u2192 Create New Site
      2.  
    2. Choose type: Newt
      3.  
    3. Enter a name (e.g., changemaker-yourdomain.org)
      4.  
    4. Choose a subnet (e.g., 100.90.128.3/24)
      5.  
    5. Select an exit node (if applicable)
      6.  
    6. Click Create Site
      7.  
    7. Copy the credentials \u2014 you'll need the Site ID, Newt ID, and Newt Secret
      8.  
     
    Save the credentials
     
    The Newt Secret is only shown once during site creation. Copy it immediately.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#step-3-update-env-with-site-credentials","title":"Step 3: Update .env with Site Credentials","text":"
    PANGOLIN_SITE_ID=your_site_id\nPANGOLIN_ENDPOINT=https://your-pangolin-server.org\nPANGOLIN_NEWT_ID=your_newt_id\nPANGOLIN_NEWT_SECRET=your_newt_secret\n
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#step-4-start-the-newt-container","title":"Step 4: Start the Newt Container","text":"
    docker compose up -d newt\n
     
    The Newt container connects to nginx (its only dependency) and establishes the tunnel:
     
    # From docker-compose.yml\nnewt:\n  image: fosrl/newt\n  container_name: newt-changemaker\n  restart: unless-stopped\n  environment:\n    - PANGOLIN_ENDPOINT=${PANGOLIN_ENDPOINT}\n    - NEWT_ID=${PANGOLIN_NEWT_ID}\n    - NEWT_SECRET=${PANGOLIN_NEWT_SECRET}\n  depends_on:\n    - nginx\n
     
    Verify the connection:
     
    docker compose logs newt --tail 20\n
     
    You should see a successful connection message.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#step-5-create-public-http-resources","title":"Step 5: Create Public HTTP Resources","text":"
    In the Pangolin dashboard, create an HTTP resource for each service you want exposed. All resources point to nginx:80 \u2014 nginx handles the routing internally.
     
    Required resources (minimum for a working deployment):
     Resource Name Domain Target Auth Admin GUI app.yourdomain.org nginx:80 Not Protected API Server api.yourdomain.org nginx:80 Not Protected Public Site yourdomain.org nginx:80 Not Protected 
    Optional resources (add as needed):
     Resource Name Domain Target Media API media.yourdomain.org nginx:80 NocoDB db.yourdomain.org nginx:80 Documentation docs.yourdomain.org nginx:80 Code Server code.yourdomain.org nginx:80 Gitea git.yourdomain.org nginx:80 Grafana grafana.yourdomain.org nginx:80 
    Set resources to Not Protected
     
    By default, Pangolin may enable authentication on new resources. This causes 302 redirects to the Pangolin login page instead of reaching your services. Set each resource to Not Protected (public access) unless you intentionally want Pangolin SSO in front of it.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#step-6-update-cors-for-production","title":"Step 6: Update CORS for Production","text":"
    Add your production domain to CORS_ORIGINS in .env:
     
    CORS_ORIGINS=https://app.yourdomain.org,http://localhost:3000,http://localhost\n
     
    Then restart the API:
     
    docker compose restart api\n
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#step-7-verify","title":"Step 7: Verify","text":"
    # Should return JSON (not a 302 redirect)\ncurl https://api.yourdomain.org/api/health\n\n# Admin GUI should load\ncurl -I https://app.yourdomain.org\n
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#cloudflare","title":"Option 2: Cloudflare Tunnel","text":"
    Cloudflare Tunnel (cloudflared) provides a similar zero-trust tunnel approach using Cloudflare's network. No port forwarding needed, and you get Cloudflare's CDN and DDoS protection.
     
    Advantages:
     
       
    • Free tier available
      •  
    • Built-in CDN and DDoS protection
      •  
    • No port forwarding needed
      •  
    • Managed SSL certificates
      •  
     
    Disadvantages:
     
       
    • Proprietary service (not self-hosted)
      •  
    • Cloudflare sees all traffic (no end-to-end encryption to your origin)
      •  
    • Subject to Cloudflare's Terms of Service
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#setup","title":"Setup","text":"
       
    1.  
      Create a Cloudflare Tunnel in the Zero Trust dashboard
       
      2.  
    2.  
      Add a cloudflared service to your docker-compose.yml:
       
      cloudflared:\n  image: cloudflare/cloudflared:latest\n  container_name: cloudflared-changemaker\n  restart: unless-stopped\n  command: tunnel run\n  environment:\n    - TUNNEL_TOKEN=${CLOUDFLARE_TUNNEL_TOKEN}\n  depends_on:\n    - nginx\n  networks:\n    - changemaker-lite\n
       
      3.  
    3.  
      Add your tunnel token to .env:
       
      CLOUDFLARE_TUNNEL_TOKEN=your_tunnel_token_here\n
       
      4.  
    4.  
      Configure public hostnames in the Cloudflare dashboard, all pointing to http://nginx:80:
       Hostname Service app.yourdomain.org http://nginx:80 api.yourdomain.org http://nginx:80 yourdomain.org http://nginx:80 (add more as needed) http://nginx:80 
      5.  
    5.  
      Start the tunnel:
       
      docker compose up -d cloudflared\n
       
      6.  
     
    Note
     
    The cloudflared service is not included in the default docker-compose.yml. Add it manually if you choose this method. The Newt service can be removed or left stopped.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#direct","title":"Option 3: Direct DNS + Reverse Proxy","text":"
    If your server has a public IP address (e.g., a VPS or dedicated server), you can point DNS directly to it and use nginx with SSL certificates.
     
    Advantages:
     
       
    • No tunnel overhead or third-party dependency
      •  
    • Full control over the network path
      •  
    • Lowest latency
      •  
     
    Disadvantages:
     
       
    • Requires a public IP and open ports (80, 443)
      •  
    • You manage SSL certificates yourself
      •  
    • Server IP is exposed
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#setup_1","title":"Setup","text":"
       
    1.  
      Point DNS for your domain and all subdomains to your server's IP:
       
      A     yourdomain.org        \u2192 YOUR_SERVER_IP\nA     *.yourdomain.org      \u2192 YOUR_SERVER_IP\n
       
      Or use individual A records for each subdomain if your DNS provider doesn't support wildcards.
       
      2.  
    2.  
      Open ports 80 and 443 on your server's firewall.
       
      3.  
    3.  
      Install Certbot (or another ACME client) for SSL certificates:
       
      # Ubuntu/Debian\nsudo apt install certbot\n\n# Get a wildcard certificate with DNS challenge\nsudo certbot certonly --manual --preferred-challenges dns \\\n  -d yourdomain.org -d '*.yourdomain.org'\n
       
      Alternatively, use the Certbot Docker image or a Let's Encrypt companion container.
       
      4.  
    4.  
      Update nginx to listen on 443 with your certificates. Add an SSL server block to nginx/conf.d/ssl.conf:
       
      server {\n    listen 443 ssl;\n    server_name app.yourdomain.org;\n\n    ssl_certificate /etc/nginx/ssl/fullchain.pem;\n    ssl_certificate_key /etc/nginx/ssl/privkey.pem;\n\n    location / {\n        proxy_pass http://changemaker-v2-admin:3000;\n        proxy_set_header Host $host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header X-Forwarded-Proto $scheme;\n        proxy_set_header Upgrade $http_upgrade;\n        proxy_set_header Connection \"upgrade\";\n    }\n}\n\n# Repeat for api.yourdomain.org, media.yourdomain.org, etc.\n# Or use a single server block with $host matching\n
       
      5.  
    5.  
      Mount certificates into the nginx container via docker-compose.yml:
       
      nginx:\n  volumes:\n    - /etc/letsencrypt/live/yourdomain.org:/etc/nginx/ssl:ro\n
       
      6.  
    6.  
      Set up auto-renewal with a cron job or systemd timer:
       
      0 3 * * * certbot renew --quiet && docker compose restart nginx\n
       
      7.  
     
    Traefik alternative
     
    If you prefer automatic SSL and don't want to manage nginx SSL config manually, consider replacing nginx with Traefik. Traefik can auto-discover Docker containers and provision Let's Encrypt certificates automatically. This would require adapting the container labels and removing the nginx service.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#tailscale","title":"Option 4: Tailscale / WireGuard (Private Access)","text":"
    For deployments that should only be accessible to specific people (not the general public), a mesh VPN like Tailscale or plain WireGuard gives you private networking without exposing anything to the internet.
     
    Use cases:
     
       
    • Internal team deployments
      •  
    • Development/staging servers
      •  
    • Access from mobile devices without public exposure
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#tailscale-setup","title":"Tailscale Setup","text":"
       
    1. Install Tailscale on your server and client devices
      2.  
    2. Access services via Tailscale IP (e.g., http://100.x.x.x:3000)
      3.  
    3. Optionally use Tailscale Funnel to selectively expose specific services publicly
      4.  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#wireguard-setup","title":"WireGuard Setup","text":"
       
    1. Set up a WireGuard server on your host
      2.  
    2. Connect client devices via WireGuard config
      3.  
    3. Access services via the WireGuard interface IP
      4.  
     
    Note
     
    With private access methods, you may not need subdomain routing at all. Access services directly by port: http://server-ip:3000 (admin), http://server-ip:4000 (API), etc.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#production-checklist","title":"Production Checklist","text":"
    Before going live, verify each item:
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#security","title":"Security","text":"
       
    •  All placeholder passwords changed (grep -c \"REQUIRED_STRONG\" .env should return 0)
      •  
    •  NODE_ENV=production set in .env
      •  
    •  ENCRYPTION_KEY set and differs from JWT secrets
      •  
    •  EMAIL_TEST_MODE=false (unless you want MailHog in production)
      •  
    •  CORS_ORIGINS includes your production domain
      •  
    •  Admin password changed after first login
      •  
    •  Redis password set (REDIS_PASSWORD)
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#networking","title":"Networking","text":"
       
    •  DNS records configured for your domain and subdomains
      •  
    •  SSL/TLS working (tunnel handles this, or manual certs)
      •  
    •  All Pangolin resources set to \"Not Protected\" (if using Pangolin)
      •  
    •  curl https://api.yourdomain.org/api/health returns JSON
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#services","title":"Services","text":"
       
    •  Core services running: docker compose ps shows api, admin, v2-postgres, redis, nginx healthy
      •  
    •  Database migrated: docker compose exec api npx prisma migrate deploy
      •  
    •  Database seeded: docker compose exec api npx prisma db seed
      •  
    •  Admin GUI accessible at https://app.yourdomain.org
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#backups","title":"Backups","text":"
       
    •  Backup script tested: ./scripts/backup.sh
      •  
    •  Backup cron job configured (see Backups below)
      •  
    •  Restore procedure tested at least once
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#monitoring-optional","title":"Monitoring (Optional)","text":"
       
    •  Monitoring stack started: docker compose --profile monitoring up -d
      •  
    •  Grafana accessible and dashboards loading
      •  
    •  Alert rules configured in Alertmanager
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#backups_1","title":"Backups","text":"
    The included backup script dumps PostgreSQL databases, archives uploads, and optionally uploads to S3.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#running-a-backup","title":"Running a Backup","text":"
    ./scripts/backup.sh\n
     
    This creates a timestamped directory under ./backups/ containing:
     
       
    • changemaker_v2.sql.gz \u2014 Main PostgreSQL dump (compressed)
      •  
    • listmonk.sql.gz \u2014 Listmonk database dump (if running)
      •  
    • uploads.tar.gz \u2014 Media uploads archive
      •  
    • manifest.json \u2014 Backup metadata
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#options","title":"Options","text":"
    # Upload to S3 (requires AWS CLI + S3_BUCKET env var)\n./scripts/backup.sh --s3\n\n# Custom retention (delete local backups older than N days)\n./scripts/backup.sh --retention 14\n
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#automated-backups","title":"Automated Backups","text":"
    Add a cron job for daily backups:
     
    # Edit crontab\ncrontab -e\n\n# Add daily backup at 3 AM\n0 3 * * * /path/to/changemaker.lite/scripts/backup.sh >> /var/log/changemaker-backup.log 2>&1\n\n# With S3 upload\n0 3 * * * /path/to/changemaker.lite/scripts/backup.sh --s3 >> /var/log/changemaker-backup.log 2>&1\n
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#restore","title":"Restore","text":"
    # Restore main database\ngunzip -c backups/changemaker-v2-backup-TIMESTAMP/changemaker_v2.sql.gz | \\\n  docker compose exec -T v2-postgres psql -U changemaker changemaker_v2\n\n# Restore Listmonk database\ngunzip -c backups/changemaker-v2-backup-TIMESTAMP/listmonk.sql.gz | \\\n  docker compose exec -T listmonk-db psql -U listmonk listmonk\n\n# Restore uploads\ntar xzf backups/changemaker-v2-backup-TIMESTAMP/uploads.tar.gz -C ./\n
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#monitoring","title":"Monitoring","text":"
    The monitoring stack runs behind a Docker Compose profile and is not started by default.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#starting-the-monitoring-stack","title":"Starting the Monitoring Stack","text":"
    docker compose --profile monitoring up -d\n
     
    This starts:
     Service Port Purpose Prometheus 9090 Metrics collection and queries Grafana 3005 Dashboards and visualization Alertmanager 9093 Alert routing and notifications cAdvisor 8086 Container resource metrics Node Exporter 9100 Host system metrics Redis Exporter 9121 Redis metrics Gotify 8889 Push notifications","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#pre-configured-dashboards","title":"Pre-configured Dashboards","text":"
    Grafana includes 3 auto-provisioned dashboards:
     
       
    1. API Overview \u2014 HTTP request rates, latency, error rates, active sessions
      2.  
    2. Infrastructure \u2014 Container CPU/memory, PostgreSQL connections, Redis memory
      3.  
    3. Campaign Activity \u2014 Email queue size, campaign sends, response submissions
      4.  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#custom-metrics","title":"Custom Metrics","text":"
    The API exposes 12 custom Prometheus metrics with the cm_ prefix:
     
       
    • cm_api_uptime_seconds \u2014 API uptime
      •  
    • cm_email_queue_size \u2014 BullMQ pending emails
      •  
    • cm_active_canvass_sessions \u2014 Active canvassing sessions
      •  
    • cm_locations_total \u2014 Total locations in database
      •  
    • And more \u2014 see api/src/utils/metrics.ts
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#alert-rules","title":"Alert Rules","text":"
    Pre-configured alerts in configs/prometheus/alerts.yml:
     
       
    • API down for more than 5 minutes
      •  
    • High error rate (>5% of requests returning 5xx)
      •  
    • Database connection failures
      •  
    • Redis connection failures
      •  
    • Email queue backlog
      •  
    • Disk space warnings
      •  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#upgrading","title":"Upgrading","text":"","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#pulling-updates","title":"Pulling Updates","text":"
    # Pull latest code\ngit pull origin main\n\n# Rebuild and restart containers\ndocker compose build api admin\ndocker compose up -d api admin\n\n# Run any new migrations\ndocker compose exec api npx prisma migrate deploy\n
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#database-migrations","title":"Database Migrations","text":"
    Always run migrations after pulling updates:
     
    docker compose exec api npx prisma migrate deploy\n
     
    Back up first
     
    Always run ./scripts/backup.sh before applying migrations in production. Migrations may alter table structures and are not easily reversible.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#troubleshooting-production-issues","title":"Troubleshooting Production Issues","text":"","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#pangolin-302-redirects-instead-of-content","title":"Pangolin: 302 Redirects Instead of Content","text":"
    Symptom: API returns 302 redirects to the Pangolin authentication page.
     
    Fix: In the Pangolin dashboard, edit each resource and set Authentication to Not Protected.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#cors-errors","title":"CORS Errors","text":"
    Symptom: Browser console shows CORS errors when accessing the production domain.
     
    Fix: Add your production app. subdomain to CORS_ORIGINS in .env, then docker compose restart api.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#newt-wont-connect","title":"Newt Won't Connect","text":"
    Check in order:
     
       
    1. Credentials: Verify PANGOLIN_NEWT_ID and PANGOLIN_NEWT_SECRET in .env
      2.  
    2. Endpoint: Confirm PANGOLIN_ENDPOINT matches your Pangolin server URL
      3.  
    3. Logs: docker compose logs newt --tail 50
      4.  
    4. Nginx running: Newt depends on nginx \u2014 docker compose ps nginx
      5.  
    5. Network: Ensure outbound HTTPS is not blocked by your firewall
      6.  
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/deployment/#services-unreachable-via-tunnel","title":"Services Unreachable via Tunnel","text":"
       
    1. Verify nginx is running: docker compose ps nginx
      2.  
    2. Test locally first: curl http://localhost:4000/api/health
      3.  
    3. Check nginx logs: docker compose logs nginx --tail 50
      4.  
    4. Verify DNS: dig app.yourdomain.org should point to your Pangolin server
      5.  
     
    See Troubleshooting for more common issues.
    ","tags":["guide","operator","deployment","docker"]},{"location":"docs/getting-started/","title":"Getting Started","text":"
    This guide walks you through installing Changemaker Lite, running your first deployment, and logging into the admin dashboard.
     
    ","tags":["guide","getting-started","operator"],"boost":2},{"location":"docs/getting-started/#prerequisites","title":"Prerequisites","text":"
       
    • Docker 24+ and Docker Compose v2
      •  
    • OpenSSL (for secret generation)
      •  
    • A Linux server (Ubuntu 22.04+ recommended) or macOS for development
      •  
    • At least 2 GB RAM and 10 GB disk space
      •  
    • A domain name (optional, but recommended for production)
      •  
    ","tags":["guide","getting-started","operator"],"boost":2},{"location":"docs/getting-started/#quick-install-pre-built-images","title":"Quick Install (Pre-built Images)","text":"
    The fastest way to deploy \u2014 no source code, no compilation:
     
    curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/main/scripts/install.sh | bash\n
     
    This downloads a lightweight release package (~2 MB), runs the configuration wizard, and pulls pre-built Docker images. First startup takes ~2 minutes. See Installation for details.
    ","tags":["guide","getting-started","operator"],"boost":2},{"location":"docs/getting-started/#quick-start-from-source","title":"Quick Start (From Source)","text":"
    For development or customization, clone the full repository:
     
    git clone https://gitea.bnkops.com/admin/changemaker.lite\ncd changemaker.lite\n
     
    bash config.sh\n
     
    docker compose up -d\n
     
    Open http://localhost:3000 and sign in with the admin email and password you configured. The API container automatically runs database migrations and seeding on first startup \u2014 no manual steps needed.
     
    Change your password
     
    If you used the wizard's generated password, change it immediately from the admin dashboard.
     
    For the full setup walkthrough, see Installation.
    ","tags":["guide","getting-started","operator"],"boost":2},{"location":"docs/getting-started/#configuration-wizard","title":"Configuration Wizard","text":"
    The config.sh wizard produces a fully populated .env file in 14 steps:
     Step What It Does 1. Prerequisites Verifies Docker, Docker Compose, and OpenSSL 2. Environment file Creates .env from .env.example (backs up existing) 3. Domain Sets root domain + 14 derived variables, updates mkdocs.yml 4. Admin credentials Email + password (enforces 12+ chars, mixed case, digit) 5. Secrets Auto-generates 21 unique secrets (JWT, encryption, database, service passwords) 6. Email MailHog (dev) or production SMTP, optionally shared with Listmonk 7. Feature flags 9 toggles: Media, Listmonk, Payments, Chat, Events, Meet, SMS, Docs Comments, Bunker Ops 8. Tunnel Pangolin credentials for secure public access 9. CORS Auto-calculated allowed origins from domain 10. Nginx Renders .conf.template files with domain substitution 11. Homepage Generates services.yaml with 27 service entries 12. Permissions Creates 12 directories with container-friendly permissions 13. Upgrade watcher Installs systemd units for GUI-triggered upgrades (optional, requires sudo) 14. Summary Displays configuration summary + next steps 
    See Installation for detailed documentation of each step.
    ","tags":["guide","getting-started","operator"],"boost":2},{"location":"docs/getting-started/#services","title":"Services","text":"
    Changemaker Lite includes 30+ Docker services organized into 8 categories:
     Category Services Startup Core API, Admin, PostgreSQL, Redis, Nginx docker compose up -d v2-postgres redis api admin nginx Media Fastify media API docker compose up -d media-api Communication Rocket.Chat, Gancio, Jitsi Meet Individual docker compose up -d commands Newsletter & Email Listmonk, MailHog docker compose up -d listmonk-app Developer Tools Code Server, MkDocs, Gitea, NocoDB, n8n Individual docker compose up -d commands Utilities Mini QR, Excalidraw, Vaultwarden, Homepage docker compose up -d mini-qr excalidraw vaultwarden homepage Monitoring Prometheus, Grafana, Alertmanager, exporters docker compose --profile monitoring up -d Infrastructure Newt tunnel, Docker socket proxy Auto-starts with tunnel configuration 
    See Services Overview for the complete catalog with ports, feature flags, and detailed descriptions.
    ","tags":["guide","getting-started","operator"],"boost":2},{"location":"docs/getting-started/#next-steps","title":"Next Steps","text":"
       
    • Installation \u2014 detailed setup walkthrough and manual configuration
      •  
    • Services Overview \u2014 complete service catalog (30+ containers)
      •  
    • Environment Variables \u2014 complete .env reference
      •  
    • First Steps \u2014 create your first campaign and add locations
      •  
    • Updates & Upgrades \u2014 keep your installation current
      •  
    • Control Panel (CCP) \u2014 multi-instance management
      •  
    • Features at a Glance \u2014 visual overview of every module
      •  
    • Admin Guide \u2014 full administration reference
      •  
    • Deployment \u2014 production setup with SSL and tunneling
      •  
    ","tags":["guide","getting-started","operator"],"boost":2},{"location":"docs/getting-started/control-panel/","title":"Changemaker Control Panel (CCP)","text":"
    The Changemaker Control Panel is a multi-tenant management layer for operators who run multiple Changemaker Lite instances from a single server. It provides a web UI to provision, monitor, and maintain a fleet of instances without manual configuration.
     
    Single instance?
     
    If you're running a single Changemaker Lite instance, you don't need CCP. Skip this page and continue with First Steps.
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#when-to-use-ccp","title":"When to Use CCP","text":"
    CCP is designed for:
     
       
    • Campaign organizations managing instances for multiple chapters or regions
      •  
    • Hosting providers offering Changemaker Lite as a managed service
      •  
    • Development teams spinning up isolated test instances
      •  
     
    CCP handles the entire instance lifecycle: provisioning, configuration, health monitoring, backups, and upgrades \u2014 all from a single dashboard.
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#architecture","title":"Architecture","text":"
    CCP runs as 4 Docker containers alongside (but independent from) your CML instances:
     
    \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502   CCP Admin GUI (5100)   \u2502  React + Vite + Ant Design\n\u2502   Dark theme, SPA        \u2502  Zustand auth store\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n             \u2502\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25bc\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502   CCP API (5000)         \u2502  Express + TypeScript\n\u2502   JWT auth, RBAC         \u2502  Prisma ORM \u2192 PostgreSQL\n\u2502   Docker socket access   \u2502  Winston logger\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n             \u2502\n    \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n    \u25bc        \u25bc        \u25bc\nccp-postgres ccp-redis  Docker Socket\n(port 5480)  (port 6399)\n
     Service Container Port Description CCP API ccp-api 5000 Express API with Docker CLI access CCP Admin ccp-admin 5100 React admin GUI CCP PostgreSQL ccp-postgres 5480 CCP metadata database CCP Redis ccp-redis 6399 Rate limiting, caching 
    Each managed CML instance gets its own isolated set of containers and PostgreSQL database, with ports allocated from non-overlapping ranges.
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#setup","title":"Setup","text":"","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#1-run-the-setup-script","title":"1. Run the Setup Script","text":"
    cd changemaker-control-panel\nchmod +x setup.sh\n./setup.sh\n
     
    The setup script:
     
       
    • Detects the installation directory and resolves absolute paths
      •  
    • Creates instances/ and backups/ directories
      •  
    • Copies .env.example to .env if not present
      •  
    • Sets INSTANCES_BASE_PATH, BACKUP_STORAGE_PATH, and CML_SOURCE_PATH
      •  
    • Generates random secrets for any placeholder values
      •  
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#2-review-environment","title":"2. Review Environment","text":"
    Edit .env and verify the key settings:
     Variable Default Description JWT_ACCESS_SECRET Auto-generated JWT signing key JWT_REFRESH_SECRET Auto-generated Refresh token signing key ENCRYPTION_KEY Auto-generated AES-256 key for instance secrets at rest INITIAL_ADMIN_EMAIL admin@example.com Bootstrap admin email INITIAL_ADMIN_PASSWORD ChangeMe2025!! Bootstrap admin password INSTANCES_BASE_PATH ./instances Where instance directories are created CML_SOURCE_PATH Auto-detected Path to CML source repo for provisioning BACKUP_STORAGE_PATH ./backups Backup archive storage PANGOLIN_API_URL \u2014 Pangolin API for tunnel management PANGOLIN_API_KEY \u2014 Pangolin authentication PANGOLIN_ORG_ID \u2014 Pangolin organization","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#3-start-ccp","title":"3. Start CCP","text":"
    docker compose up -d\n\n# Run database migrations and seed the admin user\ndocker compose exec ccp-api npx prisma migrate deploy\ndocker compose exec ccp-api npx prisma db seed\n
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#4-log-in","title":"4. Log In","text":"
    Open http://localhost:5100 and sign in with the admin credentials from .env.
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#creating-an-instance","title":"Creating an Instance","text":"
    The Create Instance wizard walks through 5 steps:
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#step-1-basic-information","title":"Step 1: Basic Information","text":"
       
    • Instance name \u2014 human-readable label (e.g., \"Edmonton Chapter\")
      •  
    • Slug \u2014 URL-safe identifier (e.g., edmonton), used for directory names and compose project
      •  
    • Domain \u2014 the domain this instance will serve (e.g., edmonton.example.org)
      •  
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#step-2-features","title":"Step 2: Features","text":"
    Toggle which platform features to enable for this instance:
     
       
    • Media Manager
      •  
    • Listmonk newsletter sync
      •  
    • Payments
      •  
    • Rocket.Chat
      •  
    • Gancio events
      •  
    • Jitsi Meet
      •  
    • SMS Campaigns
      •  
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#step-3-email","title":"Step 3: Email","text":"
    Configure SMTP for the instance, or use MailHog for testing.
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#step-4-tunnel","title":"Step 4: Tunnel","text":"
    Optionally configure Pangolin tunnel credentials for public access.
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#step-5-review","title":"Step 5: Review","text":"
    Review all settings, then click Create to start provisioning.
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#provisioning-flow","title":"Provisioning Flow","text":"
    When you create an instance, CCP runs a 13-step async provisioning process:
     Step What Happens 1 Validate uniqueness (slug + domain) 2 Allocate 4 ports from ranges 3 Generate 14 secrets (passwords, JWT keys, encryption keys) 4 Create Instance record (status: PROVISIONING) 5 Create instance directory 6 Copy CML source code (rsync, excluding node_modules/.git/.env) 7 Decrypt secrets and build template context 8 Render 7 config files from Handlebars templates (docker-compose.yml, .env, nginx configs, Pangolin, Prometheus) 9 Copy static files (nginx.conf) 10 docker compose pull (non-fatal if images are cached) 11 docker compose build 12 Start infrastructure (PostgreSQL + Redis), wait for healthy 13 Start API (runs migrations + seed), then start all remaining services 
    The admin GUI polls every 3 seconds during provisioning to show progress. When complete, the instance status changes to RUNNING.
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#port-allocation","title":"Port Allocation","text":"
    CCP allocates ports from 4 non-overlapping ranges to prevent conflicts between instances:
     Range Start End Purpose API 14000 14999 Express API server Admin 13000 13999 React admin GUI PostgreSQL 15400 15499 Database Nginx 10000 10999 Reverse proxy 
    Each new instance receives one port from each range. Ports are tracked in the database and released when instances are deleted.
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#pages-overview","title":"Pages Overview","text":"","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#dashboard","title":"Dashboard","text":"
    At-a-glance fleet status:
     
       
    • Total instances, running, healthy, degraded, stopped, error counts
      •  
    • Instance cards with status indicators and quick actions
      •  
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#instance-list","title":"Instance List","text":"
    Searchable, filterable table of all instances with status, domain, health, and creation date.
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#instance-detail","title":"Instance Detail","text":"
    5-tab view for each instance:
     Tab Content Overview Status, domain, ports, features, health summary Services Per-container status grid with restart and log-view actions Logs Real-time log viewer with service filter, tail count, and time range Backups Backup list with create, download, and delete actions Tunnel Pangolin tunnel status and configuration","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#backups","title":"Backups","text":"
    Cross-instance backup management:
     
       
    • All backups in one table with instance filter
      •  
    • Stats: total count, total size, last backup time
      •  
    • \"Backup All Running\" bulk action
      •  
    • Download and delete individual archives
      •  
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#audit-log","title":"Audit Log","text":"
    Filterable activity trail with 18 action types:
     
       
    • Instance lifecycle: CREATE, UPDATE, DELETE, START, STOP, RESTART, UPGRADE
      •  
    • Backups: CREATE, DELETE
      •  
    • Tunnel: PANGOLIN_SETUP, PANGOLIN_SYNC
      •  
    • Users: LOGIN, CREATE, UPDATE, DELETE
      •  
    • Settings: UPDATE
      •  
     
    Each entry includes timestamp, user, action, instance, IP address, and details (expandable JSON).
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#settings","title":"Settings","text":"
    CCP-level configuration:
     
       
    • Port ranges
      •  
    • Pangolin credentials
      •  
    • Default feature flags for new instances
      •  
    • Health check interval
      •  
    • Backup retention period
      •  
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#roles","title":"Roles","text":"Role Capabilities SUPER_ADMIN Full access: create/delete instances, manage users, view secrets, delete backups OPERATOR Manage instances: create, start/stop/restart, backups, health checks VIEWER Read-only: view instances, logs, health, backups, audit log","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#security","title":"Security","text":"
       
    • JWT authentication with 15-minute access tokens and 7-day refresh tokens (atomic rotation)
      •  
    • AES-256-GCM encryption for instance secrets stored in the database
      •  
    • Audit logging on all operations with IP address capture
      •  
    • Role-based access control on all API endpoints
      •  
    • Docker socket access restricted to the CCP API container only
      •  
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/control-panel/#next-steps","title":"Next Steps","text":"
       
    • Services Overview \u2014 learn about the services CCP provisions for each instance
      •  
    • Updates & Upgrades \u2014 upgrading CML instances
      •  
    • Deployment \u2014 production setup with tunneling and SSL
      •  
    ","tags":["guide","operator","multi-tenant"]},{"location":"docs/getting-started/environment-variables/","title":"Environment Variables","text":"
    Changemaker Lite uses a single .env file at the project root to configure all services. Copy the example file to get started:
     
    cp .env.example .env\n
     
    Security Essentials
     
       
    • Change every REQUIRED_STRONG_PASSWORD_CHANGE_THIS value before starting services
      •  
    • Generate secrets with openssl rand -hex 32 (or -hex 16 where noted)
      •  
    • Never commit .env to version control
      •  
    • Use unique values for each secret \u2014 do not reuse JWT secrets as encryption keys
      •  
    ","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#quick-reference","title":"Quick Reference","text":"
    Variables are grouped by service. Each table marks whether a variable is required for a basic deployment or optional (has a sensible default or only needed for specific features).
     Symbol Meaning Must be set before first run Has a working default; change for production Feature flag \u2014 opt-in","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#general","title":"General","text":"Variable Default Description NODE_ENV development Set to production for production deployments. Controls logging, error detail, and security checks. DOMAIN cmlite.org Root domain. Used for nginx subdomain routing (app.DOMAIN, api.DOMAIN, etc.). The root domain serves the MkDocs documentation site; all application routes live under app.DOMAIN. USER_ID 1000 UID for container file ownership. Match your host user's UID (id -u). GROUP_ID 1000 GID for container file ownership. Match your host user's GID (id -g). DOCKER_GROUP_ID 984 GID of the docker group on the host. Needed for containers that access the Docker socket. Find with getent group docker.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#postgresql-main-database","title":"PostgreSQL (Main Database)","text":"
    The primary database for both the Express API and the Fastify Media API (shared).
     Variable Default Description V2_POSTGRES_USER changemaker Database username. V2_POSTGRES_PASSWORD \u2014 Must change. Database password. V2_POSTGRES_DB changemaker_v2 Database name. V2_POSTGRES_PORT 5433 Host port mapping. The container listens on 5432 internally. 
    Connection string
     
    The DATABASE_URL is constructed automatically inside Docker. If running locally, set: 
    DATABASE_URL=postgresql://changemaker:YOUR_PASSWORD@localhost:5433/changemaker_v2\n
    ","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#jwt-authentication","title":"JWT Authentication","text":"Variable Default Description JWT_ACCESS_SECRET \u2014  Secret for signing access tokens. Generate with openssl rand -hex 32. JWT_REFRESH_SECRET \u2014  Secret for signing refresh tokens. Must differ from the access secret. JWT_ACCESS_EXPIRY 15m Access token lifetime. Short-lived by design. JWT_REFRESH_EXPIRY 7d Refresh token lifetime. Tokens are rotated atomically on each refresh.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#encryption-key","title":"Encryption Key","text":"Variable Default Description ENCRYPTION_KEY \u2014  AES key for encrypting secrets stored in the database (SMTP passwords, API keys, etc.). Generate with openssl rand -hex 32. Must not reuse a JWT secret. Required in all environments (no longer falls back to JWT secret in development).","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#initial-admin-account","title":"Initial Admin Account","text":"
    These credentials create the first super-admin user during database seeding (npx prisma db seed).
     Variable Default Description INITIAL_ADMIN_EMAIL admin@cmlite.org Email address for the initial admin. INITIAL_ADMIN_PASSWORD \u2014 Must change. Must be 12+ characters with uppercase, lowercase, and a digit. Change this password after first login.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#api-server","title":"API Server","text":"Variable Default Description API_PORT 4000 Host port for the Express API. API_URL http://localhost:4000 Public URL of the API. Used for generating links in emails and QR codes. CORS_ORIGINS http://localhost:3000,http://localhost Comma-separated list of allowed CORS origins. Add your production domain (e.g., https://app.yourdomain.org) for production. 
    Production CORS
     
    If you deploy behind a tunnel (Pangolin, Cloudflare) and API requests fail with CORS errors, add your production app. subdomain here: 
    CORS_ORIGINS=https://app.betteredmonton.org,http://localhost:3000,http://localhost\n
     Then restart the API: docker compose restart api
    ","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#admin-gui","title":"Admin GUI","text":"Variable Default Description ADMIN_PORT 3000 Host port for the React admin dashboard. ADMIN_URL http://localhost:3000 Public URL of the admin GUI.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#nginx-reverse-proxy","title":"Nginx Reverse Proxy","text":"Variable Default Description NGINX_HTTP_PORT 80 HTTP port. All subdomains route through nginx. NGINX_HTTPS_PORT 443 HTTPS port. SSL is typically handled by the tunnel provider (Pangolin/Cloudflare).","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#redis","title":"Redis","text":"
    Shared by rate limiting, BullMQ job queues, geocoding cache, and session data.
     Variable Default Description REDIS_PASSWORD \u2014 Must change. Redis requires authentication. REDIS_URL redis://:${REDIS_PASSWORD}@redis-changemaker:6379 Full connection URL. Uses the password variable automatically.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#payments-stripe","title":"Payments (Stripe)","text":"Variable Default Description ENABLE_PAYMENTS false  Set to true to enable the payments feature (memberships, products, donations). Stripe API keys are stored encrypted in the database via the admin settings page.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#email-smtp","title":"Email / SMTP","text":"Variable Default Description SMTP_HOST mailhog-changemaker SMTP server. Default points to the MailHog dev container. SMTP_PORT 1025 SMTP port. 1025 for MailHog, 587 for most production SMTP. SMTP_USER (empty) SMTP username. Not needed for MailHog. SMTP_PASS (empty) SMTP password. SMTP_FROM noreply@cmlite.org \"From\" address on outgoing emails. SMTP_FROM_NAME Changemaker Lite Display name for the \"From\" header. EMAIL_TEST_MODE true When true, all emails go to MailHog instead of real SMTP. Set to false in production. TEST_EMAIL_RECIPIENT admin@cmlite.org Catch-all recipient when test mode is on. 
    Development email
     
    With EMAIL_TEST_MODE=true, all outgoing email is captured in MailHog at http://localhost:8025. No real emails are sent.
    ","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#listmonk-newsletters","title":"Listmonk (Newsletters)","text":"
    Listmonk handles newsletter/marketing campaigns. Sync with the main platform is opt-in.
     Variable Default Description LISTMONK_PORT 9001 Listmonk web UI port. LISTMONK_DB_PORT 5434 Listmonk's own PostgreSQL port (separate from the main DB). Uses 5434 to avoid conflict with the main PostgreSQL (5432 internal / 5433 host). LISTMONK_DB_USER listmonk Listmonk database user. LISTMONK_DB_PASSWORD \u2014  Listmonk database password. LISTMONK_DB_NAME listmonk Listmonk database name. LISTMONK_WEB_ADMIN_USER admin Login for the Listmonk web dashboard. LISTMONK_WEB_ADMIN_PASSWORD \u2014  Password for the Listmonk web dashboard. LISTMONK_API_USER v2-api API user for programmatic access (auto-created by init container). LISTMONK_API_TOKEN \u2014 Token for API user. Generate with openssl rand -hex 16. LISTMONK_ADMIN_USER v2-api Same as LISTMONK_API_USER (used by the sync service). LISTMONK_ADMIN_PASSWORD \u2014 Same as LISTMONK_API_TOKEN. LISTMONK_SYNC_ENABLED false  Set to true to sync participants/locations/users to Listmonk lists. LISTMONK_WEBHOOK_SECRET (empty) Shared secret for Listmonk webhook callbacks. LISTMONK_PROXY_PORT 9002 Nginx proxy port for Listmonk. Listmonk SMTP settings 
    Listmonk has its own SMTP configuration, separate from the main platform's:
     Variable Default Description LISTMONK_SMTP_HOST mailhog-changemaker SMTP host for Listmonk. LISTMONK_SMTP_PORT 1025 SMTP port. LISTMONK_SMTP_USER (empty) SMTP username. LISTMONK_SMTP_PASSWORD (empty) SMTP password. LISTMONK_SMTP_TLS_TYPE none TLS mode: none, STARTTLS, or TLS. LISTMONK_SMTP_FROM Changemaker Lite <noreply@cmlite.org> From address for newsletters.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#represent-api-canadian-electoral-data","title":"Represent API (Canadian Electoral Data)","text":"Variable Default Description REPRESENT_API_URL https://represent.opennorth.ca OpenNorth Represent API endpoint. Used for postal code \u2192 representative lookups. No API key required.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#nocodb-data-browser","title":"NocoDB (Data Browser)","text":"
    Read-only database browser. Useful for inspecting data without SQL.
     Variable Default Description NOCODB_V2_PORT / NOCODB_PORT 8091 Host port for the NocoDB web UI. NOCODB_URL http://changemaker-v2-nocodb:8080 Internal Docker URL. NC_ADMIN_EMAIL admin@cmlite.org NocoDB admin email. NC_ADMIN_PASSWORD \u2014  NocoDB admin password.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#media-manager","title":"Media Manager","text":"
    Video library with upload, analytics, scheduling, and a public gallery.
     Variable Default Description ENABLE_MEDIA_FEATURES false  Set to true to enable the media system. MEDIA_API_PORT 4100 Fastify media API port. MEDIA_API_PUBLIC_URL http://media-api:4100 Internal URL for the media API container. MEDIA_ROOT /media/library Path to the video library inside the container. MEDIA_UPLOADS /media/uploads Path for upload processing. MAX_UPLOAD_SIZE_GB 10 Maximum single-file upload size in gigabytes. PUBLIC_MEDIA_PORT 3100 Public media gallery server port. VIDEO_PLAYER_DEBUG false Enable verbose video player logging. Analytics & scheduling settings Variable Default Description VIDEO_ANALYTICS_RETENTION_DAYS 90 Days to retain analytics data. GDPR-compliant with IP hashing. VIDEO_ANALYTICS_IP_HASHING_ENABLED true Hash viewer IPs for privacy. VIDEO_SCHEDULE_DEFAULT_TIMEZONE UTC Default timezone for scheduled publishing. VIDEO_SCHEDULE_NOTIFICATION_ENABLED true Notify on scheduled publish/unpublish. VIDEO_PREVIEW_LINK_EXPIRY_HOURS 24 Preview link JWT expiry (hours).","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#gitea-git-hosting","title":"Gitea (Git Hosting)","text":"
    Self-hosted Git repository. Optional service.
     Variable Default Description GITEA_URL http://gitea-changemaker:3000 Internal container URL for Gitea. GITEA_PORT / GITEA_WEB_PORT 3030 Gitea web UI port. GITEA_SSH_PORT 2222 Gitea SSH port for git operations. GITEA_DB_TYPE mysql Database type (Gitea uses its own MySQL). GITEA_DB_HOST gitea-db:3306 Internal database host. GITEA_DB_NAME gitea Database name. GITEA_DB_USER gitea Database user. GITEA_DB_PASSWD \u2014  Gitea database password. GITEA_DB_ROOT_PASSWORD \u2014  MySQL root password for Gitea. GITEA_ROOT_URL https://git.cmlite.org Public-facing URL for Gitea. GITEA_DOMAIN git.cmlite.org Domain used in git clone URLs. Gitea Docs Comments 
    Enable comments on MkDocs documentation pages, backed by Gitea Issues.
     Variable Default Description GITEA_COMMENTS_ENABLED false  Enable comments on MkDocs pages. GITEA_API_TOKEN (empty) Personal access token with repo write scope. Create in Gitea \u2192 Settings \u2192 Applications. GITEA_COMMENTS_REPO_OWNER (empty) Gitea username that owns the docs-comments repo. GITEA_COMMENTS_REPO_NAME docs-comments Repository name (auto-created via admin setup). GITEA_OAUTH_CLIENT_ID (empty) OAuth2 application client ID (create in Gitea \u2192 Settings \u2192 Applications \u2192 OAuth2). GITEA_OAUTH_CLIENT_SECRET (empty) OAuth2 application client secret.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#n8n-workflow-automation","title":"n8n (Workflow Automation)","text":"Variable Default Description N8N_PORT 5678 n8n web UI port. N8N_HOST n8n.cmlite.org Public hostname for n8n. N8N_ENCRYPTION_KEY \u2014  Encryption key for n8n credentials storage. N8N_USER_EMAIL admin@example.com Initial n8n admin email. N8N_USER_PASSWORD \u2014  Initial n8n admin password. GENERIC_TIMEZONE UTC Timezone for n8n cron triggers.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#mkdocs-documentation","title":"MkDocs (Documentation)","text":"Variable Default Description MKDOCS_PORT 4003 MkDocs dev server port (live preview). MKDOCS_SITE_SERVER_PORT 4004 MkDocs static site server port. BASE_DOMAIN https://cmlite.org Base URL for generated documentation links. MKDOCS_PREVIEW_URL http://mkdocs:8000 Internal container URL. MKDOCS_DOCS_PATH /mkdocs/docs Documentation source directory inside the container.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#code-server-web-ide","title":"Code Server (Web IDE)","text":"Variable Default Description CODE_SERVER_PORT 8888 Code Server web UI port. CODE_SERVER_URL http://code-server-changemaker:8443 Internal container URL.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#homepage-service-dashboard","title":"Homepage (Service Dashboard)","text":"Variable Default Description HOMEPAGE_PORT 3010 Homepage web UI port. HOMEPAGE_EMBED_PORT 8887 Port for iframe embedding in admin. HOMEPAGE_VAR_BASE_URL http://localhost Base URL used in Homepage service links.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#mini-qr-qr-code-generator","title":"Mini QR (QR Code Generator)","text":"Variable Default Description MINI_QR_PORT 8089 Mini QR direct access port. MINI_QR_URL http://mini-qr:8080 Internal container URL. MINI_QR_EMBED_PORT 8885 Port for iframe embedding (walk sheets, cut exports).","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#excalidraw-whiteboard","title":"Excalidraw (Whiteboard)","text":"Variable Default Description EXCALIDRAW_PORT 8090 Excalidraw web UI port. EXCALIDRAW_URL http://excalidraw-changemaker:80 Internal container URL. EXCALIDRAW_EMBED_PORT 8886 Port for iframe embedding. EXCALIDRAW_WS_URL wss://draw.cmlite.org WebSocket URL for real-time collaboration.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#vaultwarden-password-manager","title":"Vaultwarden (Password Manager)","text":"
    Self-hosted Bitwarden-compatible password manager. Optional service.
     Variable Default Description VAULTWARDEN_PORT 8445 Vaultwarden web UI port. VAULTWARDEN_URL http://vaultwarden-changemaker:80 Internal container URL. VAULTWARDEN_EMBED_PORT 8890 Port for iframe embedding in admin. VAULTWARDEN_ADMIN_TOKEN (empty) Admin panel token (access at /admin). Generate with openssl rand -hex 32. VAULTWARDEN_DOMAIN https://vault.cmlite.org Public-facing URL. Must use HTTPS \u2014 Bitwarden web vault enforces HTTPS for account creation. Set to your Pangolin tunnel URL. VAULTWARDEN_SIGNUPS_ALLOWED false Allow new user self-registration. Keep false and use admin panel invites. VAULTWARDEN_WEBSOCKET_ENABLED true Enable WebSocket notifications for real-time sync. VAULTWARDEN_SMTP_SECURITY off SMTP security mode: off for MailHog, starttls or force_tls for production. Uses the main SMTP_* variables for host/credentials. 
    Initial setup
     
    The vaultwarden-init container automatically invites the INITIAL_ADMIN_EMAIL user when starting. Check MailHog (or your SMTP) for the invitation email.
    ","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#rocketchat-team-chat","title":"Rocket.Chat (Team Chat)","text":"
    Self-hosted team chat for volunteer coordination. Requires MongoDB (auto-configured).
     Variable Default Description ENABLE_CHAT false  Set to true to enable the Rocket.Chat integration. The initial default; once saved in admin Settings, the DB value is authoritative. ROCKETCHAT_ADMIN_USER rcadmin Rocket.Chat admin username. ROCKETCHAT_ADMIN_PASSWORD \u2014  Rocket.Chat admin password. ROCKETCHAT_URL http://rocketchat-changemaker:3000 Internal container URL. ROCKETCHAT_EMBED_PORT 8891 Port for iframe embedding in admin. MONGO_ROOT_USER rocketchat MongoDB admin username. MONGO_ROOT_PASSWORD \u2014  MongoDB admin password. MongoDB runs with --auth enabled.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#gancio-event-management","title":"Gancio (Event Management)","text":"
    Self-hosted event management platform. Uses the shared PostgreSQL database (auto-created by init-gancio-db.sh).
     Variable Default Description GANCIO_PORT 8092 Gancio web UI port. GANCIO_URL http://gancio-changemaker:13120 Internal container URL. GANCIO_EMBED_PORT 8892 Port for iframe embedding in admin. GANCIO_BASE_URL https://events.cmlite.org Public-facing URL for Gancio. Used in event links. GANCIO_ADMIN_USER admin Gancio admin username for shift-to-event sync (OAuth login). GANCIO_ADMIN_PASSWORD \u2014  Gancio admin password. GANCIO_SYNC_ENABLED false  Set to true to enable automatic shift \u2192 Gancio event synchronization.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#jitsi-meet-video-conferencing","title":"Jitsi Meet (Video Conferencing)","text":"
    Self-hosted video conferencing with JWT authentication. Integrates with Rocket.Chat for in-channel video calls.
     Variable Default Description ENABLE_MEET false  Set to true to enable the Jitsi Meet integration. The initial default; once saved in admin Settings, the DB value is authoritative. JITSI_APP_ID changemaker JWT application ID. Must match across Jitsi Prosody, Rocket.Chat app settings, and JWT_ACCEPTED_ISSUERS/JWT_ACCEPTED_AUDIENCES. JITSI_APP_SECRET \u2014  JWT secret for signing Jitsi tokens. Generate with openssl rand -hex 32. Shared between Jitsi Prosody, Rocket.Chat, and the API. JITSI_JICOFO_AUTH_PASSWORD \u2014 Internal XMPP password for Jicofo (conference focus). Generate with openssl rand -hex 16. JITSI_JVB_AUTH_PASSWORD \u2014 Internal XMPP password for JVB (video bridge). Generate with openssl rand -hex 16. JITSI_EMBED_PORT 8893 Port for iframe embedding in admin. JITSI_URL http://jitsi-web-changemaker:80 Internal container URL. JVB_ADVERTISE_IP (empty) Server's public IP address. Required in production for NAT traversal so remote participants can connect. JVB_PORT 10000 UDP port for media traffic. Must be open in your firewall. 
    Production requirements
     
       
    • JVB_ADVERTISE_IP must be set to your server's public IP for calls to work outside the local network.
      •  
    • Port 10000/udp must be open in your firewall for media traffic.
      •  
    • Calls must go through the production domain (not localhost) for SSL/JWT to work.
      •  
    ","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#sms-campaigns-termux-android-bridge","title":"SMS Campaigns (Termux Android Bridge)","text":"
    Send SMS messages via an Android phone running the Termux API server. The phone acts as an SMS gateway.
     Variable Default Description ENABLE_SMS false  Set to true to enable SMS campaigns. The initial default; once saved in admin Settings, the DB value is authoritative. TERMUX_API_URL http://10.0.0.193:5001 URL of the Termux API server running on the Android phone. TERMUX_API_KEY (empty) API key for authenticating with the Termux server (HMAC auth via X-API-Key header). SMS_DELAY_BETWEEN_MS 3000 Delay between sending individual SMS messages (ms). Prevents carrier throttling. SMS_MAX_RETRIES 3 Maximum retry attempts for failed SMS sends. SMS_RESPONSE_SYNC_INTERVAL_MS 30000 How often to poll the phone's inbox for responses (ms). SMS_DEVICE_MONITOR_INTERVAL_MS 30000 How often to check device health \u2014 battery, connectivity (ms). 
    GUI configuration
     
    The Termux API URL and API key can also be configured from Admin \u2192 Settings \u2192 SMS. Database values override these env vars when set.
    ","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#mailhog-development-email","title":"MailHog (Development Email)","text":"Variable Default Description MAILHOG_SMTP_PORT 1025 SMTP port for capturing emails. MAILHOG_WEB_PORT 8025 Web UI to view captured emails.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#nar-national-address-register","title":"NAR (National Address Register)","text":"
    Canadian address data import for geographic canvassing.
     Variable Default Description NAR_DATA_DIR /data Path to extracted NAR data inside the container. Expects YYYYMM/Addresses/ and YYYYMM/Locations/ subdirectories. Mount via ./data:/data:ro in Docker Compose. 
    Download NAR data from Statistics Canada.
    ","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#geocoding","title":"Geocoding","text":"
    Multi-provider geocoding for address resolution. Works out of the box with free providers; optional paid providers improve accuracy.
     Variable Default Description MAPBOX_API_KEY (empty) Mapbox API key for improved geocoding accuracy. Free tier: 100k requests/month. Sign up. GEOCODING_RATE_LIMIT_MS 1100 Delay between requests to free providers (ms). Respects rate limits. GEOCODING_CACHE_ENABLED true Enable Redis-backed geocoding cache. GEOCODING_CACHE_TTL_HOURS 24 Cache lifetime in hours. GOOGLE_MAPS_API_KEY (empty) Google Maps API key. Most accurate but $0.005/request after free tier. GOOGLE_MAPS_ENABLED false Enable Google Maps as a geocoding provider. GEOCODING_PARALLEL_ENABLED true Enable parallel geocoding for bulk imports (~10x speedup). GEOCODING_BATCH_SIZE 10 Number of concurrent geocoding requests during bulk operations. BULK_GEOCODE_ENABLED true Enable bulk re-geocoding from the admin UI. BULK_GEOCODE_MAX_BATCH 5000 Maximum locations per bulk geocoding run.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#overpass-area-import","title":"Overpass / Area Import","text":"
    OpenStreetMap data import for map enrichment.
     Variable Default Description OVERPASS_API_URL https://overpass-api.de/api/interpreter Overpass API endpoint. Use a private instance for heavy usage. OVERPASS_MIN_DELAY_MS 30000 Minimum delay between requests (ms). The public API requires 30 seconds. AREA_IMPORT_MAX_GRID_POINTS 500 Maximum reverse-geocode grid points per area import.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#pangolin-tunnel","title":"Pangolin Tunnel","text":"
    Expose services to the internet without port forwarding, using a self-hosted Pangolin instance.
     Variable Default Description PANGOLIN_API_URL https://api.bnkserve.org/v1 Pangolin server API endpoint. PANGOLIN_API_KEY (empty) API key for Pangolin management. PANGOLIN_ORG_ID (empty) Organization ID in Pangolin. PANGOLIN_SITE_ID (empty) Site ID (populated after setup via admin GUI). PANGOLIN_ENDPOINT https://pangolin.bnkserve.org Pangolin tunnel endpoint. PANGOLIN_NEWT_ID (empty) Newt client ID (populated after setup). PANGOLIN_NEWT_SECRET (empty) Newt client secret (populated after setup). 
    Setup flow
     
    Configure the tunnel from Admin \u2192 Settings \u2192 Pangolin. The setup wizard walks you through creating a site, copying credentials, and connecting the Newt container. See Deployment for the full guide.
    ","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#monitoring","title":"Monitoring","text":"
    These services are behind the monitoring Docker Compose profile. Start them with:
     
    docker compose --profile monitoring up -d\n
     Variable Default Description PROMETHEUS_PORT 9090 Prometheus web UI / query port. GRAFANA_PORT 3005 Grafana dashboard port. GRAFANA_ADMIN_PASSWORD admin  Change in production. GRAFANA_ROOT_URL http://localhost:3005 Public URL for Grafana (used in links). CADVISOR_PORT 8086 cAdvisor container metrics port. NODE_EXPORTER_PORT 9100 Prometheus node exporter port. REDIS_EXPORTER_PORT 9121 Redis metrics exporter port. ALERTMANAGER_PORT 9093 Alertmanager web UI port. GOTIFY_PORT 8889 Gotify push notification port. GOTIFY_ADMIN_USER admin Gotify admin username. GOTIFY_ADMIN_PASSWORD admin  Change in production. GRAFANA_EMBED_PORT 8894 Port for iframe embedding Grafana in admin. ALERTMANAGER_EMBED_PORT 8895 Port for iframe embedding Alertmanager in admin.","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#bunker-ops-fleet-management","title":"Bunker Ops (Fleet Management)","text":"
    Remote metrics push for managing multiple Changemaker Lite instances from a central monitoring server.
     Variable Default Description INSTANCE_LABEL (empty) Unique label for this instance (used as a Prometheus metric label). Falls back to DOMAIN if empty. BUNKER_OPS_ENABLED false  Enable remote metrics push to a central VictoriaMetrics server. BUNKER_OPS_REMOTE_WRITE_URL (empty) VictoriaMetrics remote_write endpoint (e.g., https://ops.example.com/api/v1/write).","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#generating-secrets","title":"Generating Secrets","text":"
    Use these commands to generate all required secrets at once:
     
    # JWT secrets (two separate values)\necho \"JWT_ACCESS_SECRET=$(openssl rand -hex 32)\"\necho \"JWT_REFRESH_SECRET=$(openssl rand -hex 32)\"\n\n# Encryption key (must differ from JWT secrets)\necho \"ENCRYPTION_KEY=$(openssl rand -hex 32)\"\n\n# Database and Redis passwords\necho \"V2_POSTGRES_PASSWORD=$(openssl rand -hex 24)\"\necho \"REDIS_PASSWORD=$(openssl rand -hex 24)\"\n\n# Listmonk\necho \"LISTMONK_DB_PASSWORD=$(openssl rand -hex 24)\"\necho \"LISTMONK_WEB_ADMIN_PASSWORD=$(openssl rand -hex 16)\"\nLISTMONK_TOKEN=$(openssl rand -hex 16)\necho \"LISTMONK_API_TOKEN=$LISTMONK_TOKEN\"\necho \"LISTMONK_ADMIN_PASSWORD=$LISTMONK_TOKEN\"\n\n# Supporting services\necho \"GITEA_DB_PASSWD=$(openssl rand -hex 24)\"\necho \"GITEA_DB_ROOT_PASSWORD=$(openssl rand -hex 24)\"\necho \"N8N_ENCRYPTION_KEY=$(openssl rand -hex 32)\"\necho \"N8N_USER_PASSWORD=$(openssl rand -hex 16)\"\necho \"NC_ADMIN_PASSWORD=$(openssl rand -hex 16)\"\necho \"INITIAL_ADMIN_PASSWORD=$(openssl rand -base64 18)\"\n\n# Vaultwarden\necho \"VAULTWARDEN_ADMIN_TOKEN=$(openssl rand -hex 32)\"\n\n# Rocket.Chat + MongoDB\necho \"ROCKETCHAT_ADMIN_PASSWORD=$(openssl rand -hex 16)\"\necho \"MONGO_ROOT_PASSWORD=$(openssl rand -hex 24)\"\n\n# Gancio\necho \"GANCIO_ADMIN_PASSWORD=$(openssl rand -hex 16)\"\n\n# Jitsi Meet\necho \"JITSI_APP_SECRET=$(openssl rand -hex 32)\"\necho \"JITSI_JICOFO_AUTH_PASSWORD=$(openssl rand -hex 16)\"\necho \"JITSI_JVB_AUTH_PASSWORD=$(openssl rand -hex 16)\"\n
     
    Tip
     
    Copy the output and paste the values into your .env file. The INITIAL_ADMIN_PASSWORD uses base64 encoding to ensure it contains uppercase, lowercase, and digits (meeting the password policy).
    ","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/environment-variables/#minimal-vs-full-deployment","title":"Minimal vs Full Deployment","text":"Minimal (Core Only)Full Stack 
    For a basic deployment with campaigns, map, and admin:
     Required variables
    V2_POSTGRES_PASSWORD=...\nREDIS_PASSWORD=...\nJWT_ACCESS_SECRET=...\nJWT_REFRESH_SECRET=...\nENCRYPTION_KEY=...\nINITIAL_ADMIN_PASSWORD=...\n
     Start services
    docker compose up -d v2-postgres redis api admin\n
     
    For the complete platform including media, newsletters, monitoring, and all services:
     Additional variables needed
    # Everything above, plus:\nENABLE_MEDIA_FEATURES=true\nENABLE_PAYMENTS=true\nENABLE_CHAT=true\nENABLE_MEET=true\nENABLE_SMS=true\nLISTMONK_SYNC_ENABLED=true\nGANCIO_SYNC_ENABLED=true\nLISTMONK_DB_PASSWORD=...\nLISTMONK_WEB_ADMIN_PASSWORD=...\nLISTMONK_API_TOKEN=...\nNC_ADMIN_PASSWORD=...\nGITEA_DB_PASSWD=...\nGITEA_DB_ROOT_PASSWORD=...\nN8N_ENCRYPTION_KEY=...\nN8N_USER_PASSWORD=...\nVAULTWARDEN_ADMIN_TOKEN=...\nROCKETCHAT_ADMIN_PASSWORD=...\nMONGO_ROOT_PASSWORD=...\nGANCIO_ADMIN_PASSWORD=...\nJITSI_APP_SECRET=...\nJITSI_JICOFO_AUTH_PASSWORD=...\nJITSI_JVB_AUTH_PASSWORD=...\nJVB_ADVERTISE_IP=your.public.ip.here\nEMAIL_TEST_MODE=false\nSMTP_HOST=smtp.your-provider.com\nSMTP_PORT=587\nSMTP_USER=you@example.com\nSMTP_PASS=your-smtp-password\n
     Start services
    docker compose up -d\ndocker compose --profile monitoring up -d\n
    ","tags":["reference","getting-started","operator","configuration"]},{"location":"docs/getting-started/features/","title":"Features at a Glance","text":"
    Changemaker Lite bundles advocacy campaigns, geographic mapping, volunteer management, media hosting, and landing pages into a single self-hosted platform. Every feature can be toggled on or off from Settings in the admin panel.
    ","tags":["reference","getting-started"],"boost":2},{"location":"docs/getting-started/features/#core-features","title":"Core Features","text":"
       
    •  
       Advocacy Campaigns
       
      Help supporters contact elected representatives through email campaigns with postal code lookup and a public response wall.
       
       Campaign guide
       
      •  
    •  
       Map & Canvassing
       
      Manage locations, draw canvassing territories, schedule volunteer shifts, and run GPS-tracked door-to-door outreach.
       
       Map guide
       
      •  
    •  
       Media Manager
       
      Upload videos and photos, curate playlists, publish a shorts feed, and track engagement with built-in analytics.
       
       Media guide
       
      •  
    •  
       Landing Pages
       
      Build campaign microsites with a drag-and-drop GrapesJS visual editor and publish at custom slugs.
       
       Landing pages guide
       
      •  
    •  
       Payments (Stripe)
       
      Accept memberships, product sales, and donations with encrypted Stripe integration and branded donation pages.
       
       Payments guide
       
      •  
    •  
       SMS Campaigns
       
      Text message outreach via a Termux Android bridge with contact lists, templates, and response tracking.
       
       SMS guide
       
      •  
    •  
       Public Homepage
       
      Customizable landing page with hero section, live stats, featured campaigns, upcoming shifts, and activity feed.
       
       Homepage guide
       
      •  
    ","tags":["reference","getting-started"],"boost":2},{"location":"docs/getting-started/features/#communication-collaboration","title":"Communication & Collaboration","text":"
       
    •  
       Newsletter (Listmonk)
       
      Opt-in mailing lists and newsletter campaigns with automatic subscriber sync from shifts and contacts.
       
       Newsletter guide
       
      •  
    •  
       Email Templates
       
      Reusable email templates with variable substitution for campaign communications.
       
       Email templates guide
       
      •  
    •  
       Team Chat (Rocket.Chat)
       
      Self-hosted team chat with iframe integration, floating widget, and native mobile app support.
       
       Chat guide
       
      •  
    •  
       Video Conferencing (Jitsi)
       
      Self-hosted video calls integrated with Rocket.Chat via JWT authentication \u2014 no separate login required.
       
       Video conferencing guide
       
      •  
    ","tags":["reference","getting-started"],"boost":2},{"location":"docs/getting-started/features/#integrations-services","title":"Integrations & Services","text":"
       
    •  
       Events (Gancio)
       
      Self-hosted event management with automatic shift-to-event sync and an embeddable calendar widget.
       
       Events guide
       
      •  
    •  
       Password Manager (Vaultwarden)
       
      Bitwarden-compatible password vault for secure team credential sharing.
       
       Password manager guide
       
      •  
    •  
       User Provisioning
       
      Automatic account creation and sync across Rocket.Chat, Gitea, Vaultwarden, and Listmonk.
       
       User provisioning guide
       
      •  
    •  
       People / Contacts
       
      Centralized contact management for supporters, donors, and community members with cross-module linking.
       
       People guide
       
      •  
    •  
       Whiteboard (Excalidraw)
       
      Self-hosted collaborative whiteboard for brainstorming, planning, and visual collaboration.
       
       Whiteboard guide
       
      •  
    ","tags":["reference","getting-started"],"boost":2},{"location":"docs/getting-started/features/#volunteer-portal","title":"Volunteer Portal","text":"
       
    •  
       Social Connections
       
      Friend system, activity feed, groups, profiles, pokes, and privacy controls for volunteer community building.
       
       Social guide
       
      •  
    •  
       Achievements & Leaderboard
       
      Badge system with 11 achievements across 4 categories, progress tracking, and competitive leaderboards.
       
       Achievements guide
       
      •  
    •  
       Volunteer Quick Join
       
      QR code invite links for instant volunteer onboarding \u2014 scan, fill a short form, and start canvassing.
       
       Quick join guide
       
      •  
    ","tags":["reference","getting-started"],"boost":2},{"location":"docs/getting-started/features/#automation-analytics","title":"Automation & Analytics","text":"
       
    •  
       Email Automation
       
      Automated volunteer lifecycle emails \u2014 thank-you notes, shift reminders, weekly summaries, and re-engagement campaigns.
       
       Automation guide
       
      •  
    •  
       Data Quality Dashboard
       
      Geocoding quality metrics with per-provider stats, confidence tiers, and coverage analysis.
       
       Data quality guide
       
      •  
    •  
       Documentation Analytics
       
      Page view tracking and engagement metrics for MkDocs documentation pages.
       
       Docs analytics guide
       
      •  
    ","tags":["reference","getting-started"],"boost":2},{"location":"docs/getting-started/features/#admin-tools","title":"Admin Tools","text":"
       
    •  
       Docs Comments
       
      Gitea-backed comment system for documentation pages with anonymous posting and moderation.
       
       Docs comments guide
       
      •  
    •  
       Command Palette
       
      Global Ctrl+K search across pages, campaigns, locations, users, settings, and media.
       
       Command palette guide
       
      •  
    •  
       Navigation Settings
       
      Customize the public navigation menu with feature toggles, custom links, and drag-and-drop reordering.
       
       Navigation guide
       
      •  
    •  
       Platform Settings
       
      Five-tab settings page covering organization details, theme colors, email configuration, feature flags, and notifications.
       
       Settings guide
       
      •  
    •  
       Social Sharing (OG Tags)
       
      Open Graph meta tags for campaigns, landing pages, and gallery videos \u2014 rich link previews on social media.
       
       OG sharing guide
       
      •  
    •  
       Gallery Ads
       
      Internal ad system with 5 ad types, audience targeting, scheduling, frequency caps, and CTR analytics.
       
       Gallery ads guide
       
      •  
    •  
       Self-Service Contact Profile
       
      Token-based public profile pages where contacts can view and update their information and preferences.
       
       Contact profile guide
       
      •  
    ","tags":["reference","getting-started"],"boost":2},{"location":"docs/getting-started/first-steps/","title":"First Steps","text":"
    You've installed Changemaker Lite \u2014 here's what to do next.
    ","tags":["tutorial","getting-started","admin"],"boost":2},{"location":"docs/getting-started/first-steps/#1-log-in","title":"1. Log In","text":"
    Open the admin panel at http://localhost:3000 (or app.DOMAIN in production) and sign in with the admin email and password you configured during setup.
     
     
    Change your password
     
    If you used the wizard's generated password, change it immediately from Settings > Organization.
    ","tags":["tutorial","getting-started","admin"],"boost":2},{"location":"docs/getting-started/first-steps/#2-explore-the-dashboard","title":"2. Explore the Dashboard","text":"
    The dashboard gives you an at-a-glance view of platform activity. Initially it will be empty \u2014 that's normal.
     
    ","tags":["tutorial","getting-started","admin"],"boost":2},{"location":"docs/getting-started/first-steps/#3-configure-settings","title":"3. Configure Settings","text":"
    Visit Settings (/app/settings) to:
     
       
    • Set your organization name, logo, and tagline
      •  
    • Choose theme colors for admin and public interfaces
      •  
    • Enable feature modules (campaigns, map, media, payments, etc.)
      •  
    • Configure email delivery (MailHog for testing, production SMTP for live use)
      •  
    • Check the System tab to verify your installation and check for updates
      •  
     
    ","tags":["tutorial","getting-started","admin"],"boost":2},{"location":"docs/getting-started/first-steps/#4-create-your-first-campaign","title":"4. Create Your First Campaign","text":"
    Go to Campaigns (/app/campaigns) and click Create Campaign:
     
       
    1. Write a title and description
      2.  
    2. Compose the email template supporters will send
      3.  
    3. Select government levels to target
      4.  
    4. Publish \u2014 the campaign appears at /campaigns
      5.  
     
    ","tags":["tutorial","getting-started","admin"],"boost":2},{"location":"docs/getting-started/first-steps/#5-add-locations","title":"5. Add Locations","text":"
    Go to Locations (/app/map) and add addresses:
     
       
    • Click on the map to drop a marker
      •  
    • Import a CSV of addresses
      •  
    • Use the NAR (National Address Register) import for Canadian data
      •  
     
    ","tags":["tutorial","getting-started","admin"],"boost":2},{"location":"docs/getting-started/first-steps/#6-schedule-a-shift","title":"6. Schedule a Shift","text":"
    Go to Shifts (/app/map/shifts) and create your first volunteer shift:
     
       
    1. Set a date, time, and location description
      2.  
    2. Optionally link it to a canvassing area
      3.  
    3. Share the public shifts page (/shifts) with volunteers
      4.  
     
    ","tags":["tutorial","getting-started","admin"],"boost":2},{"location":"docs/getting-started/first-steps/#7-invite-volunteers","title":"7. Invite Volunteers","text":"
    Share the shifts page link or generate QR codes for in-person events. Volunteers sign up with just an email address.
    ","tags":["tutorial","getting-started","admin"],"boost":2},{"location":"docs/getting-started/first-steps/#next-steps","title":"Next Steps","text":"
       
    • Services Overview \u2014 complete catalog of all 30+ Docker services
      •  
    • Updates & Upgrades \u2014 keep your installation current
      •  
    • Features at a Glance \u2014 visual overview of every module
      •  
    • Admin Guide \u2014 full administration reference
      •  
    • Deployment \u2014 production setup with tunneling and SSL
      •  
    ","tags":["tutorial","getting-started","admin"],"boost":2},{"location":"docs/getting-started/installation/","title":"Installation","text":"
    Changemaker Lite runs as a set of Docker containers orchestrated by Docker Compose. The config.sh wizard handles all configuration \u2014 or you can set things up manually.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#prerequisites","title":"Prerequisites","text":"
       
    • Docker 24+ and Docker Compose v2
      •  
    • OpenSSL (for secret generation)
      •  
    • A Linux server (Ubuntu 22.04+ recommended) or macOS for development
      •  
    • At least 2 GB RAM for core services, 4 GB for the full stack
      •  
    • A domain name (optional for development, recommended for production)
      •  
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#quick-start","title":"Quick Start","text":"
    Clone the repository:
     
    git clone https://gitea.bnkops.com/admin/changemaker.lite\ncd changemaker.lite\n
     
    Run the configuration wizard:
     
    bash config.sh\n
     
    Start all services:
     
    docker compose up -d\n
     
    Open http://localhost:3000 and sign in with the admin credentials you configured. Database migrations and seeding run automatically on first startup.
     
    Change your password
     
    If you used the wizard's generated password, change it immediately from the admin dashboard.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#pre-built-image-installation","title":"Pre-built Image Installation","text":"
    For production deployments, you can skip cloning the source repository entirely. Pre-built Docker images are pulled from the Gitea container registry.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#one-line-install","title":"One-Line Install","text":"
    curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/main/scripts/install.sh | bash\n
     
    This script:
     
       
    1. Checks prerequisites (Docker, Docker Compose, OpenSSL)
      2.  
    2. Downloads the latest release package from Gitea
      3.  
    3. Extracts to ~/changemaker.lite/
      4.  
    4. Launches the configuration wizard (config.sh)
      5.  
     
    After the wizard completes, start everything with docker compose up -d.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#manual-download","title":"Manual Download","text":"
    If you prefer not to pipe to bash:
     
    # Download latest release\ncurl -LO https://gitea.bnkops.com/admin/changemaker.lite/releases/latest/download/changemaker-lite-latest.tar.gz\ntar xzf changemaker-lite-latest.tar.gz\ncd changemaker-lite\nbash config.sh\ndocker compose up -d\n
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#whats-different-from-source-install","title":"What's Different from Source Install","text":"Source Install Pre-built Install Download size ~200 MB (full repo) ~2 MB (config + scripts) First startup 10+ min (TypeScript compile + Docker build) ~2 min (image pull only) Requires Git, full repo Docker only Upgrades git pull + rebuild Download new release tarball Development Edit source, hot-reload Not for development 
    When to use which
     
    Use pre-built install for production deployments and quick evaluation. Use source install when you want to modify the platform code or contribute to development.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#configuration-wizard-configsh","title":"Configuration Wizard (config.sh)","text":"
    The wizard performs 14 steps to produce a fully configured .env file and prepare the system for startup. Each step is interactive with sensible defaults.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-1-prerequisites-check","title":"Step 1: Prerequisites Check","text":"
    Verifies that Docker, Docker Compose v2, and OpenSSL are installed. Exits immediately if any are missing, with links to installation guides.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-2-environment-file-setup","title":"Step 2: Environment File Setup","text":"
       
    • If no .env exists, copies .env.example as the starting point
      •  
    • If .env already exists, offers to back it up (timestamped copy) and create a fresh one, or update values in place
      •  
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-3-domain-configuration","title":"Step 3: Domain Configuration","text":"
    Prompts for your root domain (default: cmlite.org) and derives 14 environment variables from it:
     Variable Example Value DOMAIN example.org BASE_DOMAIN https://example.org GITEA_ROOT_URL https://git.example.org GITEA_DOMAIN git.example.org N8N_HOST n8n.example.org SMTP_FROM noreply@example.org INITIAL_ADMIN_EMAIL admin@example.org NC_ADMIN_EMAIL admin@example.org EXCALIDRAW_WS_URL wss://draw.example.org LISTMONK_SMTP_FROM Changemaker Lite <noreply@example.org> HOMEPAGE_VAR_BASE_URL https://example.org VAULTWARDEN_DOMAIN https://vault.example.org GANCIO_BASE_URL https://events.example.org TEST_EMAIL_RECIPIENT admin@example.org 
    Also updates mkdocs/mkdocs.yml with the new site_url and repo_url, and asks whether this is a production deployment (sets NODE_ENV=production).
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-4-admin-credentials","title":"Step 4: Admin Credentials","text":"
    Prompts for the initial super-admin email and password. The password is validated against the security policy:
     
       
    • Minimum 12 characters
      •  
    • At least one uppercase letter
      •  
    • At least one lowercase letter
      •  
    • At least one digit
      •  
    • Requires password confirmation
      •  
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-5-secret-generation","title":"Step 5: Secret Generation","text":"
    Auto-generates 21 unique secrets \u2014 no placeholder passwords remain after this step:
     Category Count Secrets JWT & Encryption 4 JWT_ACCESS_SECRET, JWT_REFRESH_SECRET, JWT_INVITE_SECRET (each 64-char hex), ENCRYPTION_KEY (64-char hex, must differ from JWT secrets) Database 2 V2_POSTGRES_PASSWORD, REDIS_PASSWORD (24-char alphanumeric) Listmonk 3 LISTMONK_DB_PASSWORD, LISTMONK_WEB_ADMIN_PASSWORD, LISTMONK_API_TOKEN NocoDB 1 NC_ADMIN_PASSWORD Gitea 2 GITEA_DB_PASSWD, GITEA_DB_ROOT_PASSWORD n8n 2 N8N_ENCRYPTION_KEY, N8N_USER_PASSWORD Monitoring 2 GRAFANA_ADMIN_PASSWORD, GOTIFY_ADMIN_PASSWORD Vaultwarden 1 VAULTWARDEN_ADMIN_TOKEN (64-char hex) Rocket.Chat 1 ROCKETCHAT_ADMIN_PASSWORD Gancio 1 GANCIO_ADMIN_PASSWORD Jitsi Meet 3 JITSI_APP_SECRET (64-char hex), JITSI_JICOFO_AUTH_PASSWORD, JITSI_JVB_AUTH_PASSWORD","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-6-email-configuration","title":"Step 6: Email Configuration","text":"
    Choose between:
     
       
    • MailHog (default) \u2014 captures all outgoing emails at http://localhost:8025 for development
      •  
    • Production SMTP \u2014 configures host, port, user, and password. Optionally shares credentials with Listmonk for newsletter delivery
      •  
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-7-feature-flags","title":"Step 7: Feature Flags","text":"
    Enable or disable 9 optional platform features:
     Flag Environment Variable What It Enables Media Manager ENABLE_MEDIA_FEATURES=true Video library, analytics, scheduled publishing Listmonk Sync LISTMONK_SYNC_ENABLED=true Newsletter subscriber sync from platform participants Payments ENABLE_PAYMENTS=true Stripe-based products, donations, and plans Rocket.Chat ENABLE_CHAT=true Team communication platform Gancio Events GANCIO_SYNC_ENABLED=true Shift-to-event sync with Gancio Jitsi Meet ENABLE_MEET=true Video conferencing (also prompts for server public IP) SMS Campaigns ENABLE_SMS=true Termux Android bridge for SMS (also prompts for API URL) Docs Comments GITEA_COMMENTS_ENABLED=true Gitea-backed page comments on documentation Bunker Ops BUNKER_OPS_ENABLED=true Fleet metrics push to central server (also prompts for remote write URL)","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-8-tunnel-configuration-pangolin","title":"Step 8: Tunnel Configuration (Pangolin)","text":"
    Optionally configures Pangolin tunnel credentials for secure public access:
     
       
    • PANGOLIN_API_URL \u2014 API endpoint (default: https://api.bnkserve.org/v1)
      •  
    • PANGOLIN_API_KEY \u2014 Authentication key
      •  
    • PANGOLIN_ORG_ID \u2014 Organization identifier
      •  
     
    Complete tunnel setup is done from the admin GUI at Settings > Tunnel after services are running.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-9-cors-origins","title":"Step 9: CORS Origins","text":"
    Automatically calculates allowed origins from your domain:
     
    http://app.DOMAIN,https://app.DOMAIN,http://DOMAIN,https://DOMAIN,http://localhost:3000,http://localhost,http://localhost:4003\n
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-10-nginx-config-generation","title":"Step 10: Nginx Config Generation","text":"
    Renders all .conf.template files in nginx/conf.d/ by substituting ${DOMAIN} with your configured domain. This produces the nginx configuration files that handle subdomain routing.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-11-homepage-services-yaml","title":"Step 11: Homepage Services YAML","text":"
    Generates configs/homepage/services.yaml with 27 service entries (both production and local development URLs) for the Homepage service dashboard.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-12-container-directory-permissions","title":"Step 12: Container Directory Permissions","text":"
    Creates and sets permissions (775) on 12 directories needed by containers:
     Directory Purpose configs/code-server/.config Code Server configuration configs/code-server/.local Code Server local data mkdocs/.cache MkDocs build cache mkdocs/site MkDocs built site output assets/uploads Listmonk uploads assets/images Shared images assets/icons Homepage icons media/local/inbox Media upload inbox media/local/thumbnails Video thumbnails media/public Public media files local-files n8n local files data NAR import data","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-13-upgrade-watcher-optional","title":"Step 13: Upgrade Watcher (Optional)","text":"
    Installs a systemd path watcher that enables the admin GUI's \"Check for Updates\" and \"Start Upgrade\" buttons. This step requires sudo and is optional \u2014 you can install it later or use the CLI upgrade script directly.
     
    The watcher installs two systemd units:
     
       
    • changemaker-upgrade.path \u2014 watches for data/upgrade/trigger.json
      •  
    • changemaker-upgrade.service \u2014 runs scripts/upgrade-watcher.sh when triggered
      •  
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#step-14-summary-next-steps","title":"Step 14: Summary & Next Steps","text":"
    Displays a configuration summary showing all choices made, then prints startup commands.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#what-gets-modified","title":"What Gets Modified","text":"
    After the wizard completes, the following files have been created or modified:
     File Action .env Created (or updated) with all configuration values mkdocs/mkdocs.yml Updated site_url and repo_url with domain nginx/conf.d/*.conf Generated from .conf.template files configs/homepage/services.yaml Generated with all service URLs 12 directories Created with container-friendly permissions systemd units (optional) Installed to /etc/systemd/system/","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#manual-setup-alternative","title":"Manual Setup (Alternative)","text":"
    If you prefer to configure by hand instead of using the wizard:
     
    cp .env.example .env\n
     
    At minimum, set these required secrets:
     
    # Generate cryptographic secrets\nV2_POSTGRES_PASSWORD=$(openssl rand -base64 48 | tr -dc 'a-zA-Z0-9' | head -c 24)\nREDIS_PASSWORD=$(openssl rand -base64 48 | tr -dc 'a-zA-Z0-9' | head -c 24)\nJWT_ACCESS_SECRET=$(openssl rand -hex 32)\nJWT_REFRESH_SECRET=$(openssl rand -hex 32)\nJWT_INVITE_SECRET=$(openssl rand -hex 32)\nENCRYPTION_KEY=$(openssl rand -hex 32)   # must differ from all JWT secrets\n
     
    Set your admin credentials (password must meet the 12+ char complexity requirement):
     
    INITIAL_ADMIN_EMAIL=admin@yourdomain.org\nINITIAL_ADMIN_PASSWORD=YourStrongPassword1\n
     
    Then configure optional sections:
     
       
    • Domain: Set DOMAIN and all derived variables (see Step 3 table above)
      •  
    • SMTP: Set SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, EMAIL_TEST_MODE=false
      •  
    • Feature flags: Enable features as needed (see Step 7 table above)
      •  
    • Tunnel: Set PANGOLIN_API_URL, PANGOLIN_API_KEY, PANGOLIN_ORG_ID
      •  
     
    See Environment Variables for every available option.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#full-stack-startup","title":"Full Stack Startup","text":"
    After configuration, start the entire platform:
     
    docker compose up -d\n
     
    That's it. Docker handles the startup order automatically:
     
       
    1. PostgreSQL and Redis start first (with healthchecks)
      2.  
    2. API waits for both to be healthy, then auto-runs database migrations and seeding
      3.  
    3. Admin GUI waits for the API
      4.  
    4. Nginx, media, communication, and all other services start in parallel
      5.  
    5. Init containers (nocodb-init, listmonk-init, etc.) run once and exit
      6.  
     
    Watch the startup progress:
     
    docker compose logs -f api --tail 20\n
     
    Once you see Starting server on port 4000, open http://localhost:3000 and log in.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#include-monitoring","title":"Include Monitoring","text":"
    The monitoring stack (Prometheus, Grafana, Alertmanager) uses a Docker Compose profile and isn't included by default:
     
    docker compose --profile monitoring up -d\n
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#start-only-core-services","title":"Start Only Core Services","text":"
    If you prefer a minimal startup (lower resource usage):
     
    docker compose up -d v2-postgres redis api admin nginx\n
     
    Manual migrations
     
    The API container runs migrations and seeding automatically on startup via its entrypoint script. You only need to run them manually if you're developing locally without Docker:
     
    cd api && npx prisma migrate deploy && npx prisma db seed\n
     
    See Services Overview for the complete service catalog.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#verifying-installation","title":"Verifying Installation","text":"
    After starting services, verify everything is healthy:
     
    # Check running containers\ndocker compose ps\n\n# API health check\ncurl -s http://localhost:4000/api/health | python3 -m json.tool\n\n# View API logs\ndocker compose logs api --tail 20\n\n# Check for containers in restart loops\ndocker compose ps | grep -i restarting\n
     
    You should see the API return {\"status\":\"ok\"} and all started containers in a \"running\" state.
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/installation/#next-steps","title":"Next Steps","text":"
       
    • Services Overview \u2014 complete service catalog with ports and startup commands
      •  
    • Environment Variables \u2014 complete .env reference
      •  
    • First Steps \u2014 create your first campaign and add locations
      •  
    • Updates & Upgrades \u2014 keep your installation up to date
      •  
    ","tags":["guide","getting-started","operator","docker"],"boost":2},{"location":"docs/getting-started/services/","title":"Services Overview","text":"
    Changemaker Lite runs as 30+ Docker containers orchestrated by Docker Compose. This page catalogs every service, organized by category.
     
    Quick reference
     
    Use docker compose ps to see which services are currently running, or docker compose ps -a to include stopped containers.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#core-required","title":"Core (Required)","text":"
    These services form the minimum viable platform. Start them first.
     Container Port Description changemaker-v2-api 4000 Express.js REST API (Prisma ORM) changemaker-v2-admin 3000 React admin GUI (Vite + Ant Design) changemaker-v2-postgres 5433 PostgreSQL 16 \u2014 primary database redis-changemaker 6379 Redis 7 \u2014 cache, rate limiting, job queues changemaker-v2-nginx 80 Nginx reverse proxy \u2014 subdomain routing 
    # Start core services only (minimal)\ndocker compose up -d v2-postgres redis api admin nginx\n\n# Or start everything at once\ndocker compose up -d\n
     
    The API container automatically runs database migrations and seeding on startup via its entrypoint script.
     
    Note
     
    Nginx is technically optional for local development (you can access services directly by port), but required for production subdomain routing.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#media","title":"Media","text":"Container Port Description Feature Flag changemaker-media-api 4100 Fastify media API \u2014 video library, analytics, scheduling ENABLE_MEDIA_FEATURES=true 
    docker compose up -d media-api\n
     
    The media API runs as a separate Fastify server sharing the same PostgreSQL database. It handles video upload (FFprobe metadata extraction), scheduled publishing via BullMQ, and GDPR-compliant view analytics.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#communication","title":"Communication","text":"","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#rocketchat-team-chat","title":"Rocket.Chat (Team Chat)","text":"Container Port Description Feature Flag rocketchat-changemaker 8891 Rocket.Chat server ENABLE_CHAT=true mongodb-changemaker \u2014 MongoDB (Rocket.Chat data store) \u2014 nats-changemaker \u2014 NATS (Rocket.Chat message bus) \u2014 
    docker compose up -d rocketchat mongodb nats\n
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#gancio-events","title":"Gancio (Events)","text":"Container Port Description Feature Flag gancio-changemaker 8092 Gancio event platform GANCIO_SYNC_ENABLED=true gancio-init \u2014 Init container \u2014 creates Gancio database \u2014 
    docker compose up -d gancio\n
     
    Init containers
     
    gancio-init runs once on first start to create the Gancio database in PostgreSQL, then exits. This is normal \u2014 don't worry about seeing it in a \"stopped\" state.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#jitsi-meet-video-conferencing","title":"Jitsi Meet (Video Conferencing)","text":"Container Port Description Feature Flag jitsi-web-changemaker 8893 Jitsi web interface ENABLE_MEET=true jitsi-prosody-changemaker \u2014 XMPP server (Prosody) \u2014 jitsi-jicofo-changemaker \u2014 Jitsi conference focus \u2014 jitsi-jvb-changemaker 10000/udp Jitsi video bridge \u2014 
    docker compose up -d jitsi-web jitsi-prosody jitsi-jicofo jitsi-jvb\n
     
    Firewall requirement
     
    Jitsi requires UDP port 10000 open in your firewall for video/audio media traffic. Set JVB_ADVERTISE_IP in .env to your server's public IP address.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#newsletter-email","title":"Newsletter & Email","text":"Container Port Description Feature Flag listmonk-app 9001 Listmonk newsletter platform LISTMONK_SYNC_ENABLED=true listmonk-db 5432 PostgreSQL (Listmonk's own database) \u2014 listmonk-init \u2014 Init container \u2014 creates API user \u2014 mailhog-changemaker 8025 MailHog email capture (development) EMAIL_TEST_MODE=true 
    # Newsletter platform\ndocker compose up -d listmonk-app\n\n# Email testing (captures all outgoing emails)\ndocker compose up -d mailhog\n
     
    Listmonk has its own PostgreSQL instance separate from the main database. The listmonk-init container auto-creates the API user for platform integration.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#developer-tools","title":"Developer Tools","text":"Container Port Description code-server-changemaker 8888 VS Code in the browser mkdocs-changemaker 4003 MkDocs live preview (hot reload) mkdocs-site-server-changemaker 4004 MkDocs static site server gitea-changemaker 3030 Gitea \u2014 self-hosted Git repository gitea-db \u2014 PostgreSQL (Gitea's database) changemaker-v2-nocodb 8091 NocoDB \u2014 read-only database browser nocodb-init \u2014 Init container \u2014 registers database n8n-changemaker 5678 n8n \u2014 workflow automation 
    # Start individual tools\ndocker compose up -d code-server\ndocker compose up -d mkdocs mkdocs-site-server\ndocker compose up -d gitea\ndocker compose up -d nocodb\ndocker compose up -d n8n\n
     
    Tip
     
    mkdocs (port 4003) provides live editing with hot reload for documentation authors. mkdocs-site-server (port 4004) serves the built static site for production visitors.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#utilities","title":"Utilities","text":"Container Port Description mini-qr 8089 QR code PNG generator excalidraw-changemaker 8090 Collaborative whiteboard vaultwarden-changemaker 8445 Vaultwarden \u2014 Bitwarden-compatible password manager vaultwarden-init \u2014 Init container \u2014 configures admin settings homepage-changemaker 3010 Homepage \u2014 service dashboard 
    docker compose up -d mini-qr excalidraw vaultwarden homepage\n
     
    Mini QR is used internally by walk sheets and cut export pages to generate printable QR codes.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#monitoring-docker-profile","title":"Monitoring (Docker Profile)","text":"
    Monitoring services are behind a Docker Compose profile and are not started by default.
     Container Port Description prometheus-changemaker 9090 Prometheus \u2014 metrics collection grafana-changemaker 3005 Grafana \u2014 monitoring dashboards alertmanager-changemaker 9093 Alertmanager \u2014 alert routing cadvisor-changemaker 8086 cAdvisor \u2014 container metrics node-exporter-changemaker 9100 Node Exporter \u2014 host system metrics redis-exporter-changemaker 9121 Redis Exporter \u2014 Redis metrics gotify-changemaker 8889 Gotify \u2014 push notifications 
    # Start the entire monitoring stack\ndocker compose --profile monitoring up -d\n
     
    The monitoring stack includes 3 pre-configured Grafana dashboards and 12 custom cm_* Prometheus metrics. See Monitoring for details.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#infrastructure","title":"Infrastructure","text":"Container Port Description newt \u2014 Pangolin tunnel connector (Newt) docker-socket-proxy \u2014 Docker socket proxy for secure container access 
    # Newt starts automatically if PANGOLIN_NEWT_ID and PANGOLIN_NEWT_SECRET are set\ndocker compose up -d newt\n
     
    The Newt container connects to a Pangolin tunnel server for secure public access without opening inbound ports. See Tunnel for setup.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#subdomain-routing","title":"Subdomain Routing","text":"
    When Nginx is running, services are accessible via subdomains. The root domain serves documentation only; all application routes are at app.DOMAIN.
     Subdomain Target Purpose app.DOMAIN Admin (3000) All application routes (admin, public pages, campaigns, map, shifts, media gallery) api.DOMAIN Express API (4000) REST API media.DOMAIN Fastify Media API (4100) Media API DOMAIN MkDocs Static (4004) Documentation / marketing site db.DOMAIN NocoDB (8091) Database browser docs.DOMAIN MkDocs Live (4003) Live documentation preview code.DOMAIN Code Server (8888) Web IDE n8n.DOMAIN n8n (5678) Workflow automation git.DOMAIN Gitea (3030) Git hosting home.DOMAIN Homepage (3010) Service dashboard grafana.DOMAIN Grafana (3005) Metrics visualization listmonk.DOMAIN Listmonk (9001) Newsletter platform qr.DOMAIN Mini QR (8089) QR code generator draw.DOMAIN Excalidraw (8090) Collaborative whiteboard vault.DOMAIN Vaultwarden (8445) Password manager events.DOMAIN Gancio (8092) Event platform chat.DOMAIN Rocket.Chat (8891) Team chat meet.DOMAIN Jitsi Meet (8893) Video conferencing mail.DOMAIN MailHog (8025) Email capture (dev)","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#init-containers","title":"Init Containers","text":"
    Several services use init containers \u2014 lightweight containers that run once on first startup to bootstrap databases or configuration, then exit with code 0. This pattern is borrowed from Kubernetes.
     Init Container Purpose listmonk-init Creates the Listmonk API user for platform integration gancio-init Creates the Gancio database in the shared PostgreSQL instance vaultwarden-init Configures Vaultwarden admin settings nocodb-init Registers the main database with NocoDB for browsing 
    Seeing these containers in a \"stopped\" or \"exited (0)\" state is completely normal.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#starting-everything","title":"Starting Everything","text":"
    To start all services at once (excluding monitoring):
     
    docker compose up -d\n
     
    To start everything including monitoring:
     
    docker compose up -d && docker compose --profile monitoring up -d\n
     
    To see what's running:
     
    docker compose ps\n
     
    Warning
     
    Starting all services at once requires at least 4 GB RAM. For resource-constrained environments, start only the services you need.
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/services/#next-steps","title":"Next Steps","text":"
       
    • Installation \u2014 setup walkthrough and configuration wizard details
      •  
    • Environment Variables \u2014 complete .env reference
      •  
    • First Steps \u2014 create your first campaign and volunteer shift
      •  
    ","tags":["reference","getting-started","operator","docker"]},{"location":"docs/getting-started/upgrades/","title":"Updates & Upgrades","text":"
    Changemaker Lite includes a built-in upgrade system that pulls code updates, rebuilds containers, runs database migrations, and restarts services \u2014 all while preserving your customizations.
     
    There are two ways to upgrade:
     
       
    1. Admin GUI \u2014 Check for updates and run upgrades from Settings > System
      2.  
    2. CLI \u2014 Run ./scripts/upgrade.sh directly from the command line
      3.  
     
    Both methods execute the same 6-phase upgrade process.
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#prerequisites","title":"Prerequisites","text":"","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#upgrade-watcher-required-for-gui-method","title":"Upgrade Watcher (Required for GUI Method)","text":"
    The admin GUI triggers upgrades via a systemd path watcher that monitors for trigger files. This must be installed on the host system.
     
    Install during initial setup:
     
    The config.sh wizard offers to install the watcher automatically (Step 13). If you skipped it, install manually:
     
    # Edit the systemd units to set your project path and user\nsed -e \"s|__PROJECT_DIR__|$(pwd)|g\" scripts/systemd/changemaker-upgrade.path > /tmp/changemaker-upgrade.path\nsed -e \"s|__PROJECT_DIR__|$(pwd)|g\" -e \"s|__USER__|$(whoami)|g\" scripts/systemd/changemaker-upgrade.service > /tmp/changemaker-upgrade.service\n\n# Install and enable\nsudo cp /tmp/changemaker-upgrade.path /tmp/changemaker-upgrade.service /etc/systemd/system/\nsudo systemctl daemon-reload\nsudo systemctl enable --now changemaker-upgrade.path\n
     
    Verify it's running:
     
    sudo systemctl status changemaker-upgrade.path\n
     
    How the watcher works
     
    The API container writes a trigger.json file to a shared data/upgrade/ volume. The systemd path watcher detects the file and runs scripts/upgrade-watcher.sh on the host, which dispatches to the appropriate script (check or upgrade). Progress and results are communicated back via JSON files that the API reads.
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#method-1-admin-gui","title":"Method 1: Admin GUI","text":"","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#checking-for-updates","title":"Checking for Updates","text":"
       
    1. Navigate to Settings (/app/settings)
      2.  
    2. Click the System tab
      3.  
    3. Click Check for Updates
      4.  
     
    The System tab shows your current version, last commit message, and auto-upgrade settings:
     
     
    The system fetches from the git remote and shows:
     
       
    • Current commit hash and message
      •  
    • Remote commit hash (if different)
      •  
    • Number of commits behind
      •  
    • Changelog of incoming changes
      •  
     
    When updates are available, the panel highlights how many commits are behind and lists the incoming changes:
     
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#starting-an-upgrade","title":"Starting an Upgrade","text":"
       
    1. Review the changelog to understand what's changing
      2.  
    2. Click Start Upgrade
      3.  
    3. Optionally configure:
         
      • Skip backup \u2014 skip the database backup phase (not recommended)
        •  
      • Pull images \u2014 also update third-party Docker images (PostgreSQL, Redis, etc.)
        •  
      • Use registry images \u2014 pull pre-built images from Gitea instead of compiling from source (faster \u2014 requires scripts/build-and-push.sh to have been run first)
        •  
      • Dry run \u2014 preview what would happen without making changes
        •  
       
      4.  
    4. Monitor the 6-phase progress indicator
      5.  
     
    The GUI polls for progress updates and displays the current phase, percentage, and status message in real time.
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#upgrade-results","title":"Upgrade Results","text":"
    After the upgrade completes, the System tab shows the result \u2014 including the new version, health check status, and any warnings:
     
     
    Tip
     
    If health checks show warnings immediately after an upgrade, wait 1-2 minutes for services to fully start before investigating.
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#the-6-upgrade-phases","title":"The 6 Upgrade Phases","text":"
    Both the GUI and CLI methods execute the same 6-phase process:
     Phase % Name What Happens 1 5% Pre-flight Checks Verifies Docker, git, disk space (2 GB minimum), remote reachability, and clean working directory 2 15% Backup Runs scripts/backup.sh (pg_dump + archive), backs up user-modifiable content, saves pre-upgrade commit hash 3 30% Code Update Saves user paths, stashes local changes, git pull, pops stash with auto-conflict resolution, detects new .env variables 4 50% Container Rebuild Rebuilds api, admin, media-api from source (default) or pulls pre-built images from the Gitea registry (--use-registry); conditionally rebuilds nginx and code-server if their configs changed; optionally pulls third-party images 5 70% Service Restart Stops app containers, force-recreates LSIO containers, verifies Gancio config, starts infrastructure, waits for PostgreSQL, starts API (runs migrations), starts everything else, restarts Newt tunnel and monitoring if they were running 6 90% Verification Health checks for API, Admin, Media API, Gancio, MkDocs; detects containers in restart loops","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#what-gets-preserved","title":"What Gets Preserved","text":"
    The upgrade script automatically preserves user-modifiable paths that you may have customized:
     Path What It Contains mkdocs/docs/ Your documentation content mkdocs/mkdocs.yml MkDocs configuration mkdocs/site/ Built documentation site configs/ Prometheus, Grafana, Alertmanager, Homepage configs nginx/conf.d/services.conf Custom nginx service proxies 
    These files are saved before git pull and unconditionally restored afterward, even if the pull introduces changes to them. Your versions always win.
     
    Tip
     
    The .env file is never touched by git pull (it's in .gitignore). However, if new environment variables are added in .env.example, the upgrade script automatically appends them to your .env with their default values and warns you to review them.
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#method-2-cli","title":"Method 2: CLI","text":"
    Run the upgrade script directly:
     
    ./scripts/upgrade.sh\n
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#options","title":"Options","text":"Flag Description --skip-backup Skip the backup phase (requires --force) --pull-services Also pull new third-party Docker images --use-registry Pull pre-built images from Gitea instead of compiling from source --dry-run Show what would happen without executing --force Continue past non-critical warnings --branch BRANCH Git branch to pull (default: current branch) --rollback Rollback to pre-upgrade commit --api-mode Write progress/result JSON for admin GUI (used internally)","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#examples","title":"Examples","text":"
    # Standard upgrade\n./scripts/upgrade.sh\n\n# Preview changes without executing\n./scripts/upgrade.sh --dry-run\n\n# Full upgrade including third-party image updates\n./scripts/upgrade.sh --pull-services\n\n# Upgrade using pre-built images from Gitea registry (faster, no TypeScript compile)\n./scripts/upgrade.sh --use-registry --force --skip-backup\n\n# Rollback to the last pre-upgrade state\n./scripts/upgrade.sh --rollback\n
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#registry-mode-fast-upgrades","title":"Registry Mode (Fast Upgrades)","text":"
    By default, the upgrade script compiles TypeScript from source (npm run build) and rebuilds Docker images on the deployment server. Registry mode skips this by pulling pre-built production images from the Gitea container registry \u2014 faster and requires no build tooling on the server.
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#how-it-works","title":"How It Works","text":"
       
    1. Run scripts/build-and-push.sh on a machine with Docker (usually your dev machine) to build and push production images tagged with the current commit SHA
      2.  
    2. During the next upgrade, pass --use-registry (CLI) or enable the checkbox (GUI)
      3.  
    3. The upgrade script pulls gitea.bnkops.com/admin/changemaker-{service}:{sha} instead of rebuilding from source
      4.  
    4. If a registry image is unavailable (e.g., the SHA wasn't pushed), it automatically falls back to a source build
      5.  
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#building-and-pushing-images","title":"Building and Pushing Images","text":"
    # Build and push all core services (api, admin, media-api, nginx)\n./scripts/build-and-push.sh\n\n# Skip code-server (9 GB \u2014 push only when Dockerfile changes)\n./scripts/build-and-push.sh --services api,admin,media-api,nginx\n\n# Build only, no push (verify locally first)\n./scripts/build-and-push.sh --no-push\n\n# Also mirror third-party images (postgres, redis, etc.) to Gitea\n./scripts/mirror-images.sh\n
     
    Registry prerequisites
     
       
    • Run docker login gitea.bnkops.com once per machine before pushing
      •  
    • Set GITEA_REGISTRY_USER and GITEA_REGISTRY_PASS in .env for the admin GUI's Registry status endpoint
      •  
    • gitea.bnkops.com must be reachable without proxies that limit upload size (Cloudflare free plan blocks blobs >100 MB)
      •  
     
    Release installs upgrade automatically via registry
     
    If you installed from a release tarball (not git clone), the upgrade script automatically uses registry mode. It downloads the latest release package from Gitea instead of running git pull. No additional configuration needed.
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#rollback","title":"Rollback","text":"","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#automatic-rollback","title":"Automatic Rollback","text":"
    If the upgrade fails at any phase, the script prints detailed rollback instructions including the pre-upgrade commit hash. Use the --rollback flag:
     
    ./scripts/upgrade.sh --rollback\n
     
    This:
     
       
    1. Finds the latest backup archive
      2.  
    2. Extracts the pre-upgrade commit hash from git-commit.txt inside the archive
      3.  
    3. Checks out that commit
      4.  
    4. Rebuilds and restarts all containers
      5.  
     
    Warning
     
    --rollback restores the code to the pre-upgrade state but does not automatically restore the database. If database migrations were applied during the failed upgrade, you may need to manually restore from the backup archive.
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#manual-rollback","title":"Manual Rollback","text":"
    # 1. Restore code\ncd /path/to/changemaker.lite\ngit checkout <pre-upgrade-commit-hash>\n\n# 2. Rebuild and restart\ndocker compose build api admin media-api\ndocker compose up -d\n\n# 3. Database restore (if needed \u2014 destructive!)\nls -lt backups/changemaker-v2-backup-*.tar.gz | head -5\ntar xzf backups/<backup>.tar.gz -C /tmp\ngunzip -c /tmp/<backup>/v2-postgres.sql.gz | \\\n  docker exec -i changemaker-v2-postgres psql -U changemaker -d changemaker_v2\n
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#new-environment-variables","title":"New Environment Variables","text":"
    When upstream code adds new environment variables to .env.example, the upgrade script automatically:
     
       
    1. Compares .env.example against your .env
      2.  
    2. Appends any missing variables with their default values
      3.  
    3. Warns you to review the new additions
      4.  
     
    [WARN] New env vars added to .env (review defaults):\n    NEW_FEATURE_FLAG\n    NEW_API_KEY\n
     
    Always review new variables after an upgrade \u2014 some may need manual configuration.
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#update-checker","title":"Update Checker","text":"
    A separate lightweight script checks for available updates without performing any changes:
     
    ./scripts/upgrade-check.sh\n
     
    This writes data/upgrade/status.json with:
     
       
    • Current and remote commit hashes
      •  
    • Number of commits behind
      •  
    • Changelog (last 30 commits)
      •  
    • Timestamp of last check
      •  
     
    The admin GUI reads this file to display update availability.
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#troubleshooting","title":"Troubleshooting","text":"","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#stale-progress-indicator","title":"Stale Progress Indicator","text":"
    If the GUI shows an upgrade \"in progress\" but nothing is happening, the upgrade script may have crashed. The system automatically detects stale progress (no update for 10+ minutes) and treats it as not running.
     
    To manually clear:
     
    rm -f data/upgrade/progress.json\n
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#merge-conflicts","title":"Merge Conflicts","text":"
    If git pull encounters merge conflicts in user-modifiable paths (docs, configs), the upgrade script auto-resolves by keeping your version. If conflicts occur in project-owned files (api/, admin/), the upgrade fails and asks you to resolve manually.
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#lock-file","title":"Lock File","text":"
    The upgrade script uses .upgrade.lock to prevent concurrent upgrades. If a previous upgrade crashed without cleaning up:
     
    # Verify no upgrade is actually running\nps aux | grep upgrade.sh\n\n# Remove stale lock\nrm -f .upgrade.lock\n
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#health-check-failures","title":"Health Check Failures","text":"
    If Phase 6 health checks fail, services may still be starting. Wait 1-2 minutes and check manually:
     
    # API health\ncurl -s http://localhost:4000/api/health\n\n# Container status\ndocker compose ps\n\n# Recent logs\ndocker compose logs api --tail 50\ndocker compose logs admin --tail 50\n
    ","tags":["guide","operator","upgrades"]},{"location":"docs/getting-started/upgrades/#systemd-watcher-not-triggering","title":"Systemd Watcher Not Triggering","text":"
    # Check watcher status\nsudo systemctl status changemaker-upgrade.path\n\n# Check service logs\nsudo journalctl -u changemaker-upgrade.service --tail 20\n\n# Re-enable if stopped\nsudo systemctl enable --now changemaker-upgrade.path\n
    ","tags":["guide","operator","upgrades"]},{"location":"docs/services/","title":"Services","text":"
    Changemaker Lite orchestrates 20+ services via Docker Compose. This page is your map to every service: what it does, how to reach it, and where to find its upstream documentation.
    ","tags":["reference","operator","services","docker"]},{"location":"docs/services/#core-platform","title":"Core Platform","text":"
    The essential services that power the application.
     
       
    •  
       Express API
       
      Main V2 API server. Handles authentication, campaigns, map, shifts, pages, email, and all business logic. Prisma ORM with PostgreSQL.
       
      Port: 4000 \u00b7 Container: changemaker-v2-api
       
       API Reference
       
      •  
    •  
       Fastify Media API
       
      Video library server. Upload, metadata extraction (FFprobe), analytics, scheduled publishing, and public gallery. Shares the same PostgreSQL database.
       
      Port: 4100 \u00b7 Container: changemaker-media-api
       
       Media Guide
       
      •  
    •  
       Admin GUI
       
      React single-page application (Vite + Ant Design + Zustand). Serves the admin dashboard, public campaign pages, volunteer portal, and media gallery \u2014 all from one build.
       
      Port: 3000 \u00b7 Container: changemaker-v2-admin
       
       Feature Guides
       
      •  
    •  
       PostgreSQL 16
       
      Primary database shared by both APIs. Managed by Prisma migrations. Contains 30+ tables covering users, campaigns, locations, shifts, media, and more.
       
      Port: 5433 (host) / 5432 (container) \u00b7 Container: changemaker-v2-postgres
       
       PostgreSQL Docs
       
      •  
    •  
       Redis
       
      In-memory store for rate limiting, BullMQ job queues (email, video scheduling), geocoding cache, and session data. Requires authentication.
       
      Port: 6379 \u00b7 Container: redis-changemaker
       
       Redis Docs
       
      •  
    •  
       Nginx
       
      Reverse proxy handling all subdomain routing (app., api., media., docs., etc.). Includes security headers (HSTS, CSP, Permissions-Policy) and WebSocket support.
       
      Port: 80 / 443 \u00b7 Container: changemaker-v2-nginx
       
       Nginx Docs
       
      •  
    ","tags":["reference","operator","services","docker"]},{"location":"docs/services/#communication-email","title":"Communication & Email","text":"
       
    •  
       Listmonk
       
      Self-hosted newsletter and mailing list manager. Drop-in replacement for Mailchimp. Opt-in sync with the main platform imports participants, locations, and users as subscriber lists.
       
      Port: 9001 \u00b7 Container: listmonk-app \u00b7 Subdomain: listmonk.DOMAIN
       
       Listmonk Docs
       
      •  
    •  
       MailHog
       
      Email capture for development. All outgoing email is intercepted and displayed in a web UI when EMAIL_TEST_MODE=true. No real emails are sent.
       
      Port: 8025 (web) / 1025 (SMTP) \u00b7 Container: mailhog-changemaker \u00b7 Subdomain: mail.DOMAIN
       
       MailHog GitHub
       
      •  
    ","tags":["reference","operator","services","docker"]},{"location":"docs/services/#content-editing","title":"Content & Editing","text":"
       
    •  
       MkDocs
       
      Material-themed documentation site with full-text search, blog, social cards, and Jinja2 template overrides. Two containers: live preview (dev) and static site (production).
       
      Port: 4003 (dev) / 4004 (static) \u00b7 Container: mkdocs-changemaker \u00b7 Subdomain: docs.DOMAIN
       
       MkDocs Material
       
      •  
    •  
       Code Server
       
      Full VS Code in the browser. Edit configuration files, templates, and documentation from anywhere without SSH. Supports extensions.
       
      Port: 8888 \u00b7 Container: code-server-changemaker \u00b7 Subdomain: code.DOMAIN
       
       Code Server Docs
       
      •  
    ","tags":["reference","operator","services","docker"]},{"location":"docs/services/#data-automation","title":"Data & Automation","text":"
       
    •  
       NocoDB
       
      Airtable-alternative database browser. Provides a spreadsheet-like interface to browse, filter, sort, and export campaign data. Read-only access to the main database.
       
      Port: 8091 \u00b7 Container: changemaker-v2-nocodb \u00b7 Subdomain: db.DOMAIN
       
       NocoDB Docs
       
      •  
    •  
       n8n
       
      Visual workflow automation platform. Connect APIs, trigger actions on events, schedule tasks, and build custom integrations \u2014 all without code. 400+ built-in integrations.
       
      Port: 5678 \u00b7 Container: n8n-changemaker \u00b7 Subdomain: n8n.DOMAIN
       
       n8n Docs
       
      •  
    •  
       Gitea
       
      Self-hosted Git repository hosting. Version control for campaign code, configuration, templates, and documentation. Includes issues, pull requests, and CI/CD.
       
      Port: 3030 (web) / 2222 (SSH) \u00b7 Container: gitea-changemaker \u00b7 Subdomain: git.DOMAIN
       
       Gitea Docs
       
      •  
    ","tags":["reference","operator","services","docker"]},{"location":"docs/services/#utilities","title":"Utilities","text":"
       
    •  
       Mini QR
       
      Lightweight QR code generator. Produces PNG images for walk sheets, campaign materials, and event signage. Embedded in the admin dashboard via iframe.
       
      Port: 8089 \u00b7 Container: mini-qr \u00b7 Subdomain: qr.DOMAIN
       
      •  
    •  
       Homepage
       
      Service dashboard showing the status of all containers at a glance. Auto-generated services.yaml from config.sh provides both production and local links.
       
      Port: 3010 \u00b7 Container: homepage-changemaker \u00b7 Subdomain: home.DOMAIN
       
       Homepage Docs
       
      •  
    •  
       Excalidraw
       
      Collaborative whiteboard for brainstorming, diagramming, and visual planning. Real-time collaboration via WebSocket.
       
      Port: 8090 \u00b7 Container: excalidraw-changemaker \u00b7 Subdomain: draw.DOMAIN
       
       Excalidraw
       
      •  
    •  
       Vaultwarden
       
      Self-hosted Bitwarden-compatible password manager. Secure credential sharing for campaign teams. Requires HTTPS for account creation; local browsing works on HTTP.
       
      Port: 8445 \u00b7 Container: vaultwarden-changemaker \u00b7 Subdomain: vault.DOMAIN
       
       Vaultwarden Wiki
       
      •  
    ","tags":["reference","operator","services","docker"]},{"location":"docs/services/#team-communication","title":"Team Communication","text":"
       
    •  
       Rocket.Chat
       
      Self-hosted team chat for volunteer coordination. Supports channels, direct messaging, threads, and file sharing. Embeddable in the admin dashboard via iframe. Enable with ENABLE_CHAT=true.
       
      Port: 3000 (internal) \u00b7 Container: rocketchat-changemaker \u00b7 Subdomain: chat.DOMAIN
       
       Rocket.Chat Docs
       
      •  
    •  
       Jitsi Meet
       
      Self-hosted video conferencing with JWT authentication. Four containers (web, Prosody, Jicofo, JVB) provide the full video call stack. Integrated with Rocket.Chat for one-click calls from channels and DMs. Enable with ENABLE_MEET=true.
       
      Containers: jitsi-web, jitsi-prosody, jitsi-jicofo, jitsi-jvb \u00b7 Subdomain: meet.DOMAIN
       
       Setup Guide \u00b7  Jitsi Docs
       
      •  
    •  
       Gancio
       
      Self-hosted event management platform. Automatic shift-to-event sync (when GANCIO_SYNC_ENABLED=true) publishes shifts as public events. Uses the shared PostgreSQL database. Embeddable calendar widget available for MkDocs pages.
       
      Port: 8092 \u00b7 Container: gancio-changemaker \u00b7 Subdomain: events.DOMAIN
       
       Gancio Docs
       
      •  
    ","tags":["reference","operator","services","docker"]},{"location":"docs/services/#networking-tunneling","title":"Networking & Tunneling","text":"
       
    •  
       Pangolin + Newt
       
      Self-hosted tunnel server with the Newt client container. Exposes your services to the internet without port forwarding. Handles SSL/TLS, works behind CGNAT and double NAT.
       
      Container: newt-changemaker \u00b7 Managed from Admin \u2192 Settings \u2192 Tunnel
       
       Deployment Guide \u00b7  Pangolin GitHub
       
      •  
    ","tags":["reference","operator","services","docker"]},{"location":"docs/services/#monitoring-stack","title":"Monitoring Stack","text":"
    These services run behind the monitoring Docker Compose profile. Start them with:
     
    docker compose --profile monitoring up -d\n
     
       
    •  
       Prometheus
       
      Metrics collection and time-series database. Scrapes 12 custom cm_* application metrics plus container, host, and Redis metrics. Pre-configured alert rules.
       
      Port: 9090 \u00b7 Container: prometheus-changemaker
       
       Prometheus Docs
       
      •  
    •  
       Grafana
       
      Metrics visualization with 3 auto-provisioned dashboards: API Overview, Infrastructure, and Campaign Activity. Supports custom dashboards and alerting.
       
      Port: 3005 \u00b7 Container: grafana-changemaker \u00b7 Subdomain: grafana.DOMAIN
       
       Grafana Docs
       
      •  
    •  
       Alertmanager
       
      Alert routing and notification delivery. Receives alerts from Prometheus and dispatches to Gotify, email, or webhooks based on configurable rules.
       
      Port: 9093 \u00b7 Container: alertmanager-changemaker
       
       Alertmanager Docs
       
      •  
    •  
       cAdvisor
       
      Container resource metrics. Exposes CPU, memory, network, and filesystem usage per container for Prometheus to scrape.
       
      Port: 8086 \u00b7 Container: cadvisor-changemaker
       
       cAdvisor GitHub
       
      •  
    •  
       Node Exporter
       
      Host system metrics. Reports CPU, memory, disk, and network stats for the underlying server.
       
      Port: 9100 \u00b7 Container: node-exporter-changemaker
       
       Node Exporter
       
      •  
    •  
       Redis Exporter
       
      Redis metrics for Prometheus. Exposes connection counts, memory usage, command stats, and keyspace info.
       
      Port: 9121 \u00b7 Container: redis-exporter-changemaker
       
       Redis Exporter GitHub
       
      •  
    •  
       Gotify
       
      Self-hosted push notification server. Receives alerts from Alertmanager and delivers them to mobile/desktop clients.
       
      Port: 8889 \u00b7 Container: gotify-changemaker
       
       Gotify Docs
       
      •  
    ","tags":["reference","operator","services","docker"]},{"location":"docs/services/#quick-reference","title":"Quick Reference","text":"
    All services at a glance with their default ports and subdomains.
     Service Port Subdomain Docker Profile Express API 4000 api. default Media API 4100 media. default Admin GUI 3000 app. default PostgreSQL 5433 \u2014 default Redis 6379 \u2014 default Nginx 80/443 (all) default Listmonk 9001 listmonk. default MailHog 8025 mail. default MkDocs (dev) 4003 docs. default MkDocs (static) 4004 (root) default Code Server 8888 code. default NocoDB 8091 db. default n8n 5678 n8n. default Gitea 3030 git. default Mini QR 8089 qr. default Homepage 3010 home. default Excalidraw 8090 draw. default Vaultwarden 8445 vault. default Rocket.Chat \u2014 chat. default Jitsi Meet \u2014 meet. default Gancio 8092 events. default Newt (tunnel) \u2014 \u2014 default Prometheus 9090 \u2014 monitoring Grafana 3005 grafana. monitoring Alertmanager 9093 \u2014 monitoring cAdvisor 8086 \u2014 monitoring Node Exporter 9100 \u2014 monitoring Redis Exporter 9121 \u2014 monitoring Gotify 8889 \u2014 monitoring 
    Starting services selectively
     
    You don't need to run everything. Start only what you need:
     
    # Core only\ndocker compose up -d v2-postgres redis api admin\n\n# Add nginx for subdomain routing\ndocker compose up -d nginx\n\n# Add monitoring\ndocker compose --profile monitoring up -d\n
     
    See Getting Started for the recommended startup order.
    ","tags":["reference","operator","services","docker"]},{"location":"docs/troubleshooting/","title":"Troubleshooting","text":"
    Common issues and their solutions when running Changemaker Lite.
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#cors-errors-in-production","title":"CORS Errors in Production","text":"
    Symptom: Browser console shows CORS errors when accessing production domain.
     
    Fix: Add your production domain to CORS_ORIGINS in .env:
     
    CORS_ORIGINS=https://app.yourdomain.org,http://localhost:3000\n
     
    Then restart the API: docker compose restart api
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#pangolin-tunnel-403302-errors","title":"Pangolin Tunnel \u2014 403/302 Errors","text":"
    Symptom: All API endpoints return 302 redirects to Pangolin auth page, or 403 Forbidden.
     
    Fix: In the Pangolin dashboard, set each resource to Not Protected (public access). Critical resources to fix first:
     
       
    1. api.yourdomain.org \u2014 Main API
      2.  
    2. app.yourdomain.org \u2014 Admin GUI + public pages
      3.  
    3. media.yourdomain.org \u2014 Media API
      4.  
     
    Verify:
     
    # Should return JSON, NOT a 302 redirect\ncurl -I https://api.yourdomain.org/api/health\n
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#database-connection-failures","title":"Database Connection Failures","text":"
    Symptom: API logs show database connection errors.
     
    Checklist:
     
       
    1. Check PostgreSQL: docker compose ps v2-postgres
      2.  
    2. Verify DATABASE_URL in .env matches container name and port
      3.  
    3. View logs: docker compose logs v2-postgres --tail 50
      4.  
    4. Test connection: docker compose exec api npx prisma db execute --stdin <<< \"SELECT 1\"
      5.  
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#redis-connection-failures","title":"Redis Connection Failures","text":"
    Symptom: API logs show Redis connection errors, rate limiting doesn't work.
     
    Checklist:
     
       
    1. Check Redis: docker compose ps redis-changemaker
      2.  
    2. Verify REDIS_PASSWORD and REDIS_URL format (redis://:password@host:port)
      3.  
    3. View logs: docker compose logs redis-changemaker --tail 50
      4.  
    4. Test: docker compose exec redis-changemaker redis-cli -a $REDIS_PASSWORD ping
      5.  
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#api-not-starting","title":"API Not Starting","text":"
    Symptom: API container keeps restarting or won't start.
     
    Checklist:
     
       
    1. Check logs: docker compose logs api --tail 100
      2.  
    2. Verify all required env vars are set (compare with .env.example)
      3.  
    3. Check database is ready: docker compose ps v2-postgres (should show \"healthy\")
      4.  
    4. Run migrations manually: docker compose exec api npx prisma migrate deploy
      5.  
    5. Check for port conflicts: ss -tlnp | grep 4000
      6.  
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#containers-in-restart-loops","title":"Containers in Restart Loops","text":"
    Symptom: docker compose ps shows containers with \"restarting\" status.
     
    Diagnosis:
     
    # Find restarting containers\ndocker compose ps | grep -i restarting\n\n# Check recent logs for the problem container\ndocker compose logs <service-name> --tail 50\n\n# Check container exit code\ndocker inspect <container-name> --format='{{.State.ExitCode}}'\n
     
    Common causes:
     
       
    • Missing environment variables (check .env)
      •  
    • Database not ready (healthcheck dependencies)
      •  
    • Port already in use by another process
      •  
    • Insufficient memory (check with free -h)
      •  
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#newt-tunnel-wont-connect","title":"Newt Tunnel Won't Connect","text":"
    Checklist (in order):
     
       
    1. Credentials: Verify PANGOLIN_NEWT_ID and PANGOLIN_NEWT_SECRET in .env
      2.  
    2. Endpoint: Confirm PANGOLIN_ENDPOINT matches your Pangolin server URL
      3.  
    3. Logs: docker compose logs newt --tail 50
      4.  
    4. Nginx running: Newt depends on nginx \u2014 docker compose ps nginx
      5.  
    5. Network: Ensure outbound HTTPS is not blocked by your firewall
      6.  
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#migration-errors","title":"Migration Errors","text":"
    Symptom: prisma migrate deploy fails.
     
    Common fixes:
     
    # Check migration status\ndocker compose exec api npx prisma migrate status\n\n# If migrations are out of sync, reset (DESTRUCTIVE \u2014 dev only)\ndocker compose exec api npx prisma migrate reset\n\n# If shadow database errors, create one\ndocker compose exec -T v2-postgres createdb -U changemaker prisma_shadow_diff\n
     
    Never use prisma db push in production
     
    Always use prisma migrate dev (development) or prisma migrate deploy (production) to keep migration history in sync.
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#media-api-upload-failures","title":"Media API Upload Failures","text":"
    Symptom: Video uploads fail with permission errors or 500 status.
     
    Checklist:
     
       
    1. Verify inbox volume is writable: check media/local/inbox has :rw mount
      2.  
    2. Check disk space: df -h
      3.  
    3. Verify FFmpeg is installed in container: docker compose exec media-api ffprobe -version
      4.  
    4. Check upload size limit: default is 10 GB in Fastify multipart config
      5.  
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#email-not-sending","title":"Email Not Sending","text":"
    Symptom: Advocacy emails or notifications aren't delivered.
     
    Checklist:
     
       
    1. Check EMAIL_TEST_MODE \u2014 if true, all emails go to MailHog (http://localhost:8025)
      2.  
    2. Verify SMTP credentials in .env (SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS)
      3.  
    3. Check BullMQ queue: visit Admin > Email Queue or check logs
      4.  
    4. Test SMTP from Settings: Admin > Settings > Email > Test Connection
      5.  
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#services-unreachable-via-tunnel","title":"Services Unreachable via Tunnel","text":"
    Checklist:
     
       
    1. Verify nginx is running: docker compose ps nginx
      2.  
    2. Test locally first: curl http://localhost:4000/api/health
      3.  
    3. Check nginx logs: docker compose logs nginx --tail 50
      4.  
    4. Verify DNS: dig app.yourdomain.org should point to your Pangolin server
      5.  
    5. Check Pangolin resources are all set to \"Not Protected\"
      6.  
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#slow-map-performance","title":"Slow Map Performance","text":"
    Symptom: Map page is slow or returns 500 errors with many locations.
     
    Causes and fixes:
     
       
    • Too many locations loaded at once \u2014 the API limits by address count with debounced bounds queries
      •  
    • Missing indexes \u2014 verify database has the 5 performance indexes on Location/Address tables
      •  
    • Browser memory \u2014 marker clustering activates above zoom level 18; below that, addresses are grouped
      •  
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#docker-disk-space","title":"Docker Disk Space","text":"
    Symptom: Builds fail, containers can't start, or images won't pull.
     
    # Check disk usage\ndf -h\n\n# Clean unused Docker resources\ndocker system prune -f\n\n# Clean old images (keep only last 2 days)\ndocker image prune -a --filter \"until=48h\"\n\n# Check what's using space\ndocker system df\n
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/troubleshooting/#getting-help","title":"Getting Help","text":"
    If your issue isn't listed here:
     
       
    1. Check the API logs: docker compose logs api --tail 200
      2.  
    2. Search the Gitea issues
      3.  
    3. Review the Deployment guide for production-specific issues
      4.  
    4. File a new issue with your logs and .env (redact passwords)
      5.  
    ","tags":["troubleshooting","operator"],"boost":2},{"location":"docs/user-guide/","title":"User Guide","text":"
    This guide covers everything you can do as a visitor or registered supporter \u2014 from contacting representatives to signing up for volunteer shifts.
    ","tags":["guide","user"]},{"location":"docs/user-guide/#what-you-can-do","title":"What You Can Do","text":"
       
    •  
       Campaigns
       
      Find active advocacy campaigns, look up your representatives, and send emails.
       
      •  
    •  
       Map
       
      Explore the interactive map showing locations across your community.
       
      •  
    •  
       Shifts
       
      Sign up for volunteer shifts and join canvassing teams.
       
      •  
    •  
       Events
       
      Browse upcoming events and RSVP through the event calendar.
       
      •  
    •  
       Gallery
       
      Watch campaign videos, browse photos, and explore playlists.
       
      •  
    •  
       Shop & Pricing
       
      Purchase campaign merchandise or subscribe to a membership plan.
       
      •  
    •  
       Donations
       
      Support the cause with one-time donations on branded pages.
       
      •  
    •  
       Your Profile
       
      View and manage your contact profile, preferences, and activity history.
       
      •  
    ","tags":["guide","user"]},{"location":"docs/user-guide/campaigns/","title":"Campaigns","text":"
    Browse active advocacy campaigns and contact your elected representatives.
    ","tags":["guide","user","influence","campaigns"]},{"location":"docs/user-guide/campaigns/#how-it-works","title":"How It Works","text":"
       
    1. Browse campaigns at /campaigns \u2014 see active campaigns with descriptions and email counts
      2.  
    2. Pick a campaign \u2014 read about the issue and who it targets
      3.  
    3. Enter your postal code \u2014 the system looks up your federal, provincial, municipal, and school board representatives
      4.  
    4. Send the email \u2014 use \"Send Now\" to send through the platform, or open it in your own email app (Gmail, Outlook, etc.)
      5.  
    5. Share the response \u2014 if a representative replies, submit it to the public Response Wall
      6.  
    ","tags":["guide","user","influence","campaigns"]},{"location":"docs/user-guide/campaigns/#response-wall","title":"Response Wall","text":"
    Each campaign has a public response wall where supporters share how their representatives responded. Responses can be upvoted and are moderated by admins. Verified responses display a trust badge.
    ","tags":["guide","user","influence","campaigns"]},{"location":"docs/user-guide/campaigns/#submit-your-own-campaign","title":"Submit Your Own Campaign","text":"
    Registered users can draft and submit their own advocacy campaigns at /campaigns/create. Submissions go through admin review before being published.
    ","tags":["guide","user","influence","campaigns"]},{"location":"docs/user-guide/campaigns/#public-routes","title":"Public Routes","text":"
       
    • /campaigns \u2014 browse active campaigns
      •  
    • /campaign/:slug \u2014 take action on a specific campaign
      •  
    • /campaign/:slug/responses \u2014 view the response wall
      •  
    • /campaigns/create \u2014 submit a user-generated campaign (requires login)
      •  
    • /campaigns/mine \u2014 manage your submitted campaigns (requires login)
      •  
    ","tags":["guide","user","influence","campaigns"]},{"location":"docs/user-guide/donations/","title":"Donations","text":"
    Make one-time contributions on branded donation pages.
    ","tags":["guide","user","payments"]},{"location":"docs/user-guide/donations/#how-it-works","title":"How It Works","text":"
       
    1. Browse donation pages at /donate
      2.  
    2. Choose a campaign to support
      3.  
    3. Select a suggested amount or enter a custom amount
      4.  
    4. Complete payment securely through Stripe
      5.  
    5. Receive a confirmation with a thank-you message
      6.  
    ","tags":["guide","user","payments"]},{"location":"docs/user-guide/donations/#donation-pages","title":"Donation Pages","text":"
    Each donation page has:
     
       
    • Custom branding \u2014 unique title, description, and cover image
      •  
    • Suggested amounts \u2014 pre-set donation tiers for quick selection
      •  
    • Goal tracking \u2014 progress bar showing how close the campaign is to its fundraising goal
      •  
    • Anonymous giving \u2014 option to donate without displaying your name
      •  
    ","tags":["guide","user","payments"]},{"location":"docs/user-guide/donations/#public-routes","title":"Public Routes","text":"
       
    • /donate \u2014 browse donation pages
      •  
    • /donate/:slug \u2014 donate on a specific campaign page
      •  
    ","tags":["guide","user","payments"]},{"location":"docs/user-guide/events/","title":"Events (Gancio)","text":"
    Integrated with Gancio for self-hosted event management. When enabled, volunteer shifts are automatically published as public events.
    ","tags":["guide","user","events"]},{"location":"docs/user-guide/events/#shift-to-event-sync","title":"Shift-to-Event Sync","text":"
    When GANCIO_SYNC_ENABLED=true, the platform:
     
       
    1. Creates a Gancio event whenever a new shift is published
      2.  
    2. Updates the event if the shift time, location, or details change
      3.  
    3. Deletes the event if the shift is cancelled
      4.  
     
    Sync uses OAuth authentication with the Gancio admin account.
    ","tags":["guide","user","events"]},{"location":"docs/user-guide/events/#key-features","title":"Key Features","text":"
       
    • Automatic sync \u2014 shifts appear as public events without manual entry
      •  
    • Embeddable calendar \u2014 GrapesJS block and MkDocs widget for embedding the event calendar on pages
      •  
    • Public events page \u2014 linked from the public navigation when enableEvents is enabled in settings
      •  
    ","tags":["guide","user","events"]},{"location":"docs/user-guide/events/#admin-routes","title":"Admin Routes","text":"
       
    • /app/gancio \u2014 Gancio service status and iframe embed
      •  
    ","tags":["guide","user","events"]},{"location":"docs/user-guide/events/#public-routes","title":"Public Routes","text":"
       
    • /events \u2014 public events navigation link (when enabled)
      •  
    • events.DOMAIN \u2014 Gancio web interface for browsing and RSVPs
      •  
    ","tags":["guide","user","events"]},{"location":"docs/user-guide/gallery/","title":"Gallery","text":"
    The public gallery at /gallery showcases campaign videos, photos, and curated playlists.
    ","tags":["guide","user","media","gallery"]},{"location":"docs/user-guide/gallery/#videos","title":"Videos","text":"
       
    • Browse by category \u2014 videos organized into categories with thumbnails and durations
      •  
    • Video player \u2014 full playback with engagement features (reactions, comments)
      •  
    • Shorts feed \u2014 TikTok-style vertical video feed for clips under 60 seconds at /gallery/shorts
      •  
    ","tags":["guide","user","media","gallery"]},{"location":"docs/user-guide/gallery/#photos","title":"Photos","text":"
       
    • Photo albums \u2014 browse photos organized into named collections
      •  
    • Reactions and comments \u2014 engage with individual photos
      •  
    ","tags":["guide","user","media","gallery"]},{"location":"docs/user-guide/gallery/#playlists","title":"Playlists","text":"
       
    • Curated playlists \u2014 admin and community-created video collections
      •  
    • Featured carousel \u2014 highlighted playlists on the gallery homepage
      •  
    • Playlist viewer \u2014 continuous playback with up-next queue at /gallery/playlist/:id
      •  
    ","tags":["guide","user","media","gallery"]},{"location":"docs/user-guide/gallery/#public-routes","title":"Public Routes","text":"
       
    • /gallery \u2014 public video and photo gallery
      •  
    • /gallery/watch/:id \u2014 watch a specific video
      •  
    • /gallery/playlist/:id \u2014 view a playlist
      •  
    • /gallery/shorts \u2014 browse the shorts feed
      •  
    ","tags":["guide","user","media","gallery"]},{"location":"docs/user-guide/map/","title":"Map","text":"
    The public map at /map shows locations across your community on an interactive Leaflet map.
    ","tags":["guide","user","map"]},{"location":"docs/user-guide/map/#features","title":"Features","text":"
       
    • Interactive map \u2014 zoom, pan, and click markers to see address details
      •  
    • Color-coded markers \u2014 locations are color-coded based on their status
      •  
    • Cluster groups \u2014 markers group together when zoomed out for better performance
      •  
    • Fullscreen mode \u2014 expand the map to fill your screen
      •  
    ","tags":["guide","user","map"]},{"location":"docs/user-guide/map/#public-routes","title":"Public Routes","text":"
       
    • /map \u2014 public interactive map
      •  
    ","tags":["guide","user","map"]},{"location":"docs/user-guide/profile/","title":"Self-Service Contact Profile","text":"
    Give supporters a private, token-based link to view and manage their own contact profile -- no login required.
    ","tags":["guide","user","CRM"]},{"location":"docs/user-guide/profile/#how-it-works","title":"How It Works","text":"
       
    1. An admin generates a profile link from the People CRM -- each link contains a unique 64-character hex token with a configurable expiration (24 hours to 1 year).
      2.  
    2. The supporter opens the link -- if the link is password-protected, they enter the password first. If expired, they see a branded expiration notice.
      3.  
    3. The supporter views and edits their profile -- they can update their name, email, phone, address, and cover photo.
      4.  
    4. Communication preferences -- supporters can opt out of email and/or SMS communications with simple toggle switches.
      5.  
    ","tags":["guide","user","CRM"]},{"location":"docs/user-guide/profile/#profile-tabs","title":"Profile Tabs","text":"
       
    • Profile -- edit display name, first/last name, email, phone, and address
      •  
    • Preferences -- toggle email and SMS opt-out switches
      •  
    • Activity -- paginated timeline of all engagement: emails sent, responses submitted, shift signups, canvass visits, donations, video views, and profile edits
      •  
    • Social tabs -- if the viewer is a logged-in user viewing their own profile and the social feature is enabled, additional tabs appear: Friends, Feed, Achievements, Notifications, and Discover
      •  
    ","tags":["guide","user","CRM"]},{"location":"docs/user-guide/profile/#security","title":"Security","text":"
       
    • Token-based access -- no account or login needed; the URL token grants access
      •  
    • Password protection -- admins can optionally set a password on the profile link
      •  
    • Expiration -- links expire after a configurable duration, showing a branded message with the expiration date
      •  
    • Rate limiting -- separate rate limits on profile views, edits, photo uploads, and password attempts
      •  
    • Cover photo -- supporters can upload a JPEG, PNG, or WebP cover photo (max 5 MB), automatically resized to 800x400
      •  
    ","tags":["guide","user","CRM"]},{"location":"docs/user-guide/profile/#engagement-score","title":"Engagement Score","text":"
    Each profile shows a circular engagement score (0-100) calculated from the contact's activity across the platform -- emails, shifts, canvass visits, donations, and video views.
    ","tags":["guide","user","CRM"]},{"location":"docs/user-guide/profile/#public-routes","title":"Public Routes","text":"
       
    • /profile/:token -- self-service contact profile page
      •  
    ","tags":["guide","user","CRM"]},{"location":"docs/user-guide/shifts/","title":"Shifts","text":"
    Browse available volunteer shifts and sign up to participate in canvassing and other campaign activities.
    ","tags":["guide","user","shifts"]},{"location":"docs/user-guide/shifts/#signing-up","title":"Signing Up","text":"
       
    1. Visit /shifts to see available time slots
      2.  
    2. Pick a shift that works for your schedule
      3.  
    3. Fill in your name and email
      4.  
    4. You'll receive a confirmation email with login credentials
      5.  
    ","tags":["guide","user","shifts"]},{"location":"docs/user-guide/shifts/#quick-join","title":"Quick Join","text":"
    Organizers may share a QR code at events for instant onboarding:
     
       
    1. Scan the QR code \u2014 it opens a Quick Join page
      2.  
    2. Enter your email (and optionally your name and phone)
      3.  
    3. Start immediately \u2014 you're logged in and redirected to the volunteer portal with your area pre-loaded
      4.  
     
    Quick Join creates a temporary 24-hour account. Your organizer can upgrade it to a permanent account afterward.
    ","tags":["guide","user","shifts"]},{"location":"docs/user-guide/shifts/#after-signing-up","title":"After Signing Up","text":"
    Once you have an account, log in to access the Volunteer Portal where you can:
     
       
    • View your assigned shifts and canvassing areas
      •  
    • Open the canvass map for GPS-guided door-to-door outreach
      •  
    • Track your activity and visit history
      •  
     
    See the Volunteer Guide for the full volunteer experience.
    ","tags":["guide","user","shifts"]},{"location":"docs/user-guide/shifts/#public-routes","title":"Public Routes","text":"
       
    • /shifts \u2014 browse and sign up for volunteer shifts
      •  
    • /join?token=... \u2014 quick join via invite link or QR code
      •  
    ","tags":["guide","user","shifts"]},{"location":"docs/user-guide/shop/","title":"Shop & Pricing","text":"
    Support the campaign by purchasing merchandise or subscribing to a membership plan.
    ","tags":["guide","user","payments"]},{"location":"docs/user-guide/shop/#shop","title":"Shop","text":"
    Browse available products at /shop:
     
       
    • Campaign merchandise and branded items
      •  
    • One-time purchases with Stripe checkout
      •  
    • Product details with images and descriptions
      •  
    ","tags":["guide","user","payments"]},{"location":"docs/user-guide/shop/#membership-plans","title":"Membership Plans","text":"
    View subscription options at /pricing:
     
       
    • Tiered membership plans with different benefits
      •  
    • Monthly and yearly billing options
      •  
    • Secure recurring payments through Stripe
      •  
    ","tags":["guide","user","payments"]},{"location":"docs/user-guide/shop/#public-routes","title":"Public Routes","text":"
       
    • /shop \u2014 browse products
      •  
    • /pricing \u2014 view subscription plans
      •  
    ","tags":["guide","user","payments"]},{"location":"docs/volunteer/","title":"Volunteer Guide","text":"
    Welcome! This guide walks you through everything you need as a campaign volunteer.
    ","tags":["guide","volunteer"]},{"location":"docs/volunteer/#getting-started","title":"Getting Started","text":"","tags":["guide","volunteer"]},{"location":"docs/volunteer/#1-sign-up-for-a-shift","title":"1. Sign Up for a Shift","text":"
    Visit the Shifts page (your organizer will share the link, or find it at /shifts). Browse available time slots, pick one that works, and fill in your name and email. You'll receive a confirmation email with login credentials.
    ","tags":["guide","volunteer"]},{"location":"docs/volunteer/#2-log-in","title":"2. Log In","text":"
    Sign in with the email and password from your confirmation at the login page.
    ","tags":["guide","volunteer"]},{"location":"docs/volunteer/#3-explore-the-volunteer-portal","title":"3. Explore the Volunteer Portal","text":"
    After logging in, you'll land on the volunteer portal. Use the bottom navigation to access:
     
       
    • Map \u2014 your canvassing area with GPS tracking
      •  
    • Shifts \u2014 your upcoming and past shifts
      •  
    • Friends \u2014 social connections with other volunteers
      •  
    • Achievements \u2014 badges and leaderboards
      •  
    ","tags":["guide","volunteer"]},{"location":"docs/volunteer/#in-this-section","title":"In This Section","text":"
       
    • Canvassing \u2014 the GPS-guided canvass map, recording visits, and walking routes
      •  
    • Shifts \u2014 viewing your assigned shifts, activity log, and route history
      •  
    • Social \u2014 friend connections, activity feed, groups, profiles, and privacy settings
      •  
    • Achievements \u2014 unlockable badges, progress tracking, and competitive leaderboards
      •  
    ","tags":["guide","volunteer"]},{"location":"docs/volunteer/#browsing-public-pages","title":"Browsing Public Pages","text":"
    Tap your name/avatar in the header and select Browse Site to visit the public pages \u2014 campaigns, the public map, and shift signups.
    ","tags":["guide","volunteer"]},{"location":"docs/volunteer/#faq","title":"FAQ","text":"
    Q: I can't find my assigned area on the map. A: Make sure your shift has an area assigned. Check with your organizer.
     
    Q: My GPS isn't working. A: Allow location access in your browser. Try moving near a window for better signal.
     
    Q: I recorded the wrong outcome. A: Visit the same address again and record the correct outcome. The most recent visit counts.
     
    Q: How do I sign up for more shifts? A: Visit the public shifts page at /shifts.
    ","tags":["guide","volunteer"]},{"location":"docs/volunteer/achievements/","title":"Achievements & Leaderboard","text":"
    Recognize volunteer contributions with unlockable achievement badges and competitive leaderboards.
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/achievements/#how-it-works","title":"How It Works","text":"
    Achievements are checked automatically when relevant actions occur (e.g., signing up for a shift, completing a canvass session, accepting a friend request). When a user's progress meets the threshold, the badge is unlocked and an in-app notification is sent.
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/achievements/#badge-categories","title":"Badge Categories","text":"","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/achievements/#shifts","title":"Shifts","text":"Badge Name Threshold Description FIRST_SHIFT First Steps 1 confirmed signup Sign up for your first volunteer shift SHIFT_STREAK_3 Reliable Volunteer 3 confirmed signups Sign up for 3 volunteer shifts SHIFT_STREAK_10 Shift Champion 10 confirmed signups Sign up for 10 volunteer shifts","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/achievements/#canvassing","title":"Canvassing","text":"Badge Name Threshold Description FIRST_CANVASS Door Knocker 1 completed session Complete your first canvass session CANVASS_50_DOORS Neighbourhood Explorer 50 visits Record 50 canvass visits CANVASS_100_DOORS Community Connector 100 visits Record 100 canvass visits CANVASS_500_DOORS Door-to-Door Legend 500 visits Record 500 canvass visits","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/achievements/#campaigns","title":"Campaigns","text":"Badge Name Threshold Description FIRST_CAMPAIGN_EMAIL Voice Heard 1 email sent Send your first advocacy email CAMPAIGN_CHAMPION Campaign Champion 5 distinct campaigns Participate in 5 different campaigns","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/achievements/#social","title":"Social","text":"Badge Name Threshold Description SOCIAL_BUTTERFLY Social Butterfly 10 accepted friends Make 10 friends on the platform TEAM_PLAYER Team Player 3 group memberships Be a member of 3 groups","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/achievements/#progress-tracking","title":"Progress Tracking","text":"
    Each badge displays a progress bar showing current progress toward the threshold. Already-unlocked badges show the unlock date and the progress value at unlock time or the current count (whichever is higher).
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/achievements/#leaderboards","title":"Leaderboards","text":"
    The Achievements page includes a leaderboard tab with three ranking types:
     
       
    • Canvass \u2014 ranked by total canvass visits recorded
      •  
    • Shifts \u2014 ranked by total confirmed shift signups
      •  
    • Campaigns \u2014 ranked by number of distinct campaigns participated in
      •  
     
    Leaderboard entries show rank, user name, and score. Users who have disabled \"Show in Friend Activity\" in their privacy settings are excluded from leaderboard rankings to respect their privacy choices.
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/achievements/#volunteer-stats","title":"Volunteer Stats","text":"
    The Achievements page also displays aggregate stats for the current user:
     
       
    • Confirmed shift signups
      •  
    • Completed canvass sessions
      •  
    • Total canvass visits
      •  
    • Advocacy emails sent
      •  
    • Campaigns participated in
      •  
    • Friend count
      •  
    • Group memberships
      •  
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/achievements/#volunteer-routes","title":"Volunteer Routes","text":"
       
    • /volunteer/achievements \u2014 badge gallery, progress bars, leaderboard tabs, and personal stats
      •  
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/canvassing/","title":"Canvassing","text":"
    The volunteer canvass map is your main tool for door-to-door outreach \u2014 a full-screen GPS-tracked experience.
    ","tags":["guide","volunteer","map","canvassing"]},{"location":"docs/volunteer/canvassing/#the-volunteer-map","title":"The Volunteer Map","text":"","tags":["guide","volunteer","map","canvassing"]},{"location":"docs/volunteer/canvassing/#what-you-see","title":"What You See","text":"
       
    • Colored markers \u2014 each marker is an address. Colors indicate the outcome of the last visit (green = supportive, red = opposed, grey = not yet visited)
      •  
    • Clusters \u2014 when zoomed out, markers group together showing the address count. Tap a cluster to zoom in.
      •  
    • Blue dot \u2014 your current GPS position
      •  
    • Walking route \u2014 a suggested path through the addresses (dotted line)
      •  
    ","tags":["guide","volunteer","map","canvassing"]},{"location":"docs/volunteer/canvassing/#recording-a-visit","title":"Recording a Visit","text":"
       
    1. Tap a marker to select an address
      2.  
    2. A bottom panel slides up showing address details
      3.  
    3. Tap Record Visit to log what happened:
         
      • Not Home \u2014 nobody answered
        •  
      • Supportive \u2014 positive interaction
        •  
      • Opposed \u2014 not supportive
        •  
      • Undecided \u2014 hasn't made up their mind
        •  
      • Moved \u2014 no longer lives there
        •  
      • Refused \u2014 declined to talk
        •  
       
      4.  
    4. Optionally add a note about the visit
      5.  
    5. Tap Save \u2014 the marker color updates immediately
      6.  
    ","tags":["guide","volunteer","map","canvassing"]},{"location":"docs/volunteer/canvassing/#sessions","title":"Sessions","text":"
       
    • Start a session before you begin knocking on doors \u2014 this tracks your route and time
      •  
    • End your session when you're done for the day
      •  
    • The map works offline for basic viewing, but you need a connection to save visits
      •  
    • If GPS is inaccurate, manually tap the correct marker on the map
      •  
    ","tags":["guide","volunteer","map","canvassing"]},{"location":"docs/volunteer/canvassing/#routes","title":"Routes","text":"
    The Routes tab shows your past canvassing routes on a map, helping you see which areas you've covered and plan your next outing.
    ","tags":["guide","volunteer","map","canvassing"]},{"location":"docs/volunteer/canvassing/#volunteer-routes","title":"Volunteer Routes","text":"
       
    • /volunteer \u2014 full-screen canvass map with GPS and visit recording
      •  
    • /volunteer/activity \u2014 visit history and outcome breakdown
      •  
    • /volunteer/routes \u2014 past canvassing routes
      •  
    ","tags":["guide","volunteer","map","canvassing"]},{"location":"docs/volunteer/shifts/","title":"Your Shifts","text":"
    View your upcoming and past volunteer shifts from the Shifts tab in the bottom navigation.
    ","tags":["guide","volunteer","shifts"]},{"location":"docs/volunteer/shifts/#shift-details","title":"Shift Details","text":"
    Each shift shows:
     
       
    • Date and time
      •  
    • Assigned area (if linked to a canvassing territory)
      •  
    • A button to open the canvass map for that area
      •  
    ","tags":["guide","volunteer","shifts"]},{"location":"docs/volunteer/shifts/#activity-log","title":"Activity Log","text":"
    The Activity tab shows your complete visit history:
     
       
    • Outcome breakdown \u2014 pie chart of your visit outcomes
      •  
    • Visit list \u2014 each visit with address, outcome, time, and notes
      •  
    • Stats \u2014 total visits, addresses covered, and sessions completed
      •  
    ","tags":["guide","volunteer","shifts"]},{"location":"docs/volunteer/shifts/#volunteer-routes","title":"Volunteer Routes","text":"
       
    • /volunteer/shifts \u2014 view assigned shifts
      •  
    • /volunteer/activity \u2014 visit history and outcome breakdown
      •  
    ","tags":["guide","volunteer","shifts"]},{"location":"docs/volunteer/social/","title":"Social Connections","text":"
    Connect with fellow volunteers through friend requests, activity feeds, team groups, and real-time notifications. Enable via Settings > Feature Toggles > Social Connections.
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/social/#friends","title":"Friends","text":"
       
    • Send requests \u2014 search for other volunteers and send friend requests
      •  
    • Accept / decline / cancel \u2014 manage requests from the Friends page
      •  
    • Mutual friends \u2014 view shared connections between users
      •  
    • Block / unblock \u2014 blocked users cannot send requests or appear in suggestions
      •  
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/social/#discover","title":"Discover","text":"
    The Discover page suggests potential friends using a ranked scoring algorithm based on:
     
       
    • Household/family connections (highest priority)
      •  
    • Mutual friends
      •  
    • Shared shifts (co-volunteers from the last 90 days)
      •  
    • Shared campaigns (co-participants from the last 90 days)
      •  
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/social/#activity-feed","title":"Activity Feed","text":"
    The Social Feed at /volunteer/feed shows recent activity from your friends:
     
       
    • Shift signups, campaign emails, canvass sessions, and response submissions
      •  
    • Limited to the last 30 days (max 50 items)
      •  
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/social/#groups","title":"Groups","text":"
    Groups are automatically created based on platform activity:
     
       
    • Shift teams \u2014 created when 2+ volunteers share a shift
      •  
    • Campaign teams \u2014 created when 2+ users participate in the same campaign
      •  
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/social/#profiles","title":"Profiles","text":"
    Each volunteer has a social profile showing volunteer stats, achievement badges, friendship status, and recent activity.
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/social/#pokes","title":"Pokes","text":"
    Send a friendly nudge to any accepted friend (24-hour cooldown per pair).
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/social/#privacy-settings","title":"Privacy Settings","text":"Setting Default Description Show online status On Whether friends see you as online Show in friend activity On Whether your actions appear in feeds Allow friend requests On Whether others can send you requests","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/social/#digest-emails","title":"Digest Emails","text":"
    Opt into periodic social digest emails with friend activity, unread notifications, and pending requests. Choose daily or weekly frequency.
    ","tags":["guide","volunteer","social"]},{"location":"docs/volunteer/social/#volunteer-routes","title":"Volunteer Routes","text":"
       
    • /volunteer/feed \u2014 social activity feed
      •  
    • /volunteer/friends \u2014 friends, requests, blocked, and groups
      •  
    • /volunteer/discover \u2014 ranked friend suggestions
      •  
    • /volunteer/profile \u2014 your social profile
      •  
    • /volunteer/profile/:userId \u2014 another volunteer's profile
      •  
    • /volunteer/notifications \u2014 notification center and preferences
      •  
    • /volunteer/groups/:id \u2014 group detail with member list
      •  
    ","tags":["guide","volunteer","social"]},{"location":"blog/archive/2026/","title":"2026","text":""},{"location":"blog/category/testing/","title":"Testing","text":""},{"location":"blog/category/announcements/","title":"Announcements","text":""},{"location":"blog/category/platform/","title":"Platform","text":""}]}
\ No newline at end of file
diff --git a/mkdocs/site/sitemap.xml b/mkdocs/site/sitemap.xml
index ee5bc226..7fee9687 100644
--- a/mkdocs/site/sitemap.xml
+++ b/mkdocs/site/sitemap.xml
@@ -2,338 +2,350 @@
 
     
          https://cmlite.org/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/404/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/lander/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/main/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/test-page/
-         2026-03-23
+         2026-03-31
+    
+    
+         https://cmlite.org/test/
+         2026-03-31
     
     
          https://cmlite.org/blog/
-         2026-03-23
+         2026-03-31
+    
+    
+         https://cmlite.org/blog/2026/03/27/test-blog-post---version-7/
+         2026-03-31
     
     
          https://cmlite.org/blog/2026/03/22/introducing-changemaker-lite-v2/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/comments/callback/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/phil/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/dashboard/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/people-access/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/settings/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/advocacy/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/advocacy/campaigns/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/advocacy/email-queue/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/advocacy/representatives/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/advocacy/responses/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/broadcast/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/broadcast/email-templates/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/broadcast/newsletter/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/broadcast/sms/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/map/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/map/areas/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/map/canvassing/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/map/data-quality/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/map/locations/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/map/settings/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/map/shifts/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/media/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/media/ads/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/media/analytics/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/media/curated/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/media/library/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/media/moderation/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/payments/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/payments/donations/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/payments/plans/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/payments/products/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/payments/settings/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/services/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/services/crowdsec/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/services/integrations/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/services/monitoring/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/services/tunnel/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/services/user-provisioning/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/web/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/web/documentation/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/web/homepage/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/web/landing-pages/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/admin/web/navigation/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/api/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/architecture/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/deployment/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/getting-started/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/getting-started/control-panel/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/getting-started/environment-variables/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/getting-started/features/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/getting-started/first-steps/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/getting-started/installation/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/getting-started/services/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/getting-started/upgrades/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/services/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/troubleshooting/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/user-guide/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/user-guide/campaigns/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/user-guide/donations/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/user-guide/events/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/user-guide/gallery/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/user-guide/map/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/user-guide/profile/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/user-guide/shifts/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/user-guide/shop/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/volunteer/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/volunteer/achievements/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/volunteer/canvassing/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/volunteer/shifts/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/docs/volunteer/social/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/includes/abbreviations/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/partials/integrations/analytics/custom/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/blog/archive/2026/
-         2026-03-23
+         2026-03-31
+    
+    
+         https://cmlite.org/blog/category/testing/
+         2026-03-31
     
     
          https://cmlite.org/blog/category/announcements/
-         2026-03-23
+         2026-03-31
     
     
          https://cmlite.org/blog/category/platform/
-         2026-03-23
+         2026-03-31
     
 
\ No newline at end of file
diff --git a/mkdocs/site/sitemap.xml.gz b/mkdocs/site/sitemap.xml.gz
index 49ba88e9..52d48cfd 100644
Binary files a/mkdocs/site/sitemap.xml.gz and b/mkdocs/site/sitemap.xml.gz differ
diff --git a/mkdocs/site/test-page/index.html b/mkdocs/site/test-page/index.html
index bfe8fb55..173dcc80 100644
--- a/mkdocs/site/test-page/index.html
+++ b/mkdocs/site/test-page/index.html
@@ -1546,6 +1546,8 @@ body.cm-search-active .md-header--cm-hidden .md-search__output {
       
         
       
+        
+      
         
       
         
diff --git a/mkdocs/site/test/index.html b/mkdocs/site/test/index.html
new file mode 100644
index 00000000..d458733c
--- /dev/null
+++ b/mkdocs/site/test/index.html
@@ -0,0 +1,1590 @@
+
+
+
+
+  
+    
+      
+      
+      
+        
+      
+      
+        
+      
+      
+        
+      
+      
+      
+      
+        
+      
+      
+      
+      
+    
+    
+      
+        test - Changemaker Lite
+      
+    
+    
+      
+      
+        
+        
+      
+      
+
+
+    
+    
+      
+    
+    
+      
+        
+        
+        
+        
+        
+      
+    
+    
+      
+    
+      
+    
+      
+    
+      
+    
+      
+    
+      
+    
+    
+    
+      
+  
+
+
+  
+  
+    
+  
+
+    
+    
+  
+
+
+
+
+
+
+
+
+
+
+
+
+
+  
+  
+    
+    
+      
+    
+    
+    
+    
+    
+  
+    
+    
+    
+    
+    
+    
    
+      
+        
+      
+    
    
+    
+    
+
    
+  
    
+    
+      
+        
    
+  
+    
+    
+    
+    
+    
+      
+    
+  
+    
+    
+    
+    
+    
+      
+    
+  
+
    
+      
+    
+  
    
+  
+    
+  
+
    
+
+    
    
+      
+      
+
+  
+
+
+
+      
    
+        
    
+          
+            
+              
+              
    
+                
    
+                  
    
+                    
+
+
+  
+
+
+
+                  
    
+                
    
+              
    
+            
+            
+              
+              
    
+                
    
+                  
    
+                    
+
+  
+
+
+                  
    
+                
    
+              
    
+            
+          
+          
+            
    
+              
+                
+
+
+
+  
+
+
+              
+              
    
+                
+                  
+
+
+  
+    
+      
+      
+    
+  
+  
+    
+      
+    
+    
+      
+      
+    
+  
+
+
+
    test
    
+
    Hello! 
    
+
+
+
+
+
+
+
+
+
+  
+
+
+
+
+                
+              
    
+            
    
+          
+          
+  
+
+
+        
    
+        
+          
+        
+      
    
+      
+        
+      
+    
    
+    
    
+      
    
+    
    
+    
+      
    
+    
+    
+      
+      
+    
+    
+      
+      
+      
+    
+    
+      
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+        
+      
+    
+  
+
\ No newline at end of file
diff --git a/nginx/conf.d/services.conf.template b/nginx/conf.d/services.conf.template
index a37351d8..d192a2c7 100644
--- a/nginx/conf.d/services.conf.template
+++ b/nginx/conf.d/services.conf.template
@@ -1,4 +1,5 @@
 # Gitea — allows iframe embedding from admin (app.${DOMAIN})
+# SSO: nginx validates cml_session cookie via API auth_request, injects X-WEBAUTH-USER
 server {
     listen 80;
     server_name git.${DOMAIN};
@@ -7,7 +8,20 @@ server {
     # Increase max body size for large git pushes (2GB)
     client_max_body_size 2048M;
 
+    # Internal: validate SSO session cookie via API
+    location = /_auth {
+        internal;
+        set $upstream_api http://changemaker-v2-api:4000;
+        proxy_pass $upstream_api/api/auth/gitea-sso-validate;
+        proxy_pass_request_body off;
+        proxy_set_header Content-Length "";
+        proxy_set_header Cookie $http_cookie;
+    }
+
     location / {
+        auth_request /_auth;
+        auth_request_set $gitea_user $upstream_http_x_gitea_user;
+
         set $upstream_gitea http://gitea-changemaker:3000;
         proxy_pass $upstream_gitea;
         proxy_hide_header X-Frame-Options;
@@ -15,6 +29,8 @@ server {
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_set_header X-Forwarded-Proto $scheme;
+        # SSO header — empty string if not authenticated (Gitea ignores it)
+        proxy_set_header X-WEBAUTH-USER $gitea_user;
     }
 }
 
@@ -300,11 +316,26 @@ server {
     }
 }
 
+# Gitea embed proxy — SSO via auth_request (same as subdomain block)
 server {
     listen ${GITEA_EMBED_PORT};
     # Increase max body size for large git pushes (2GB)
     client_max_body_size 2048M;
+
+    # Internal: validate SSO session cookie via API
+    location = /_auth {
+        internal;
+        set $upstream_api http://changemaker-v2-api:4000;
+        proxy_pass $upstream_api/api/auth/gitea-sso-validate;
+        proxy_pass_request_body off;
+        proxy_set_header Content-Length "";
+        proxy_set_header Cookie $http_cookie;
+    }
+
     location / {
+        auth_request /_auth;
+        auth_request_set $gitea_user $upstream_http_x_gitea_user;
+
         set $upstream_gitea http://gitea-changemaker:3000;
         proxy_pass $upstream_gitea;
         proxy_hide_header X-Frame-Options;
@@ -314,6 +345,8 @@ server {
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_set_header X-Forwarded-Proto $scheme;
+        # SSO header — empty string if not authenticated (Gitea ignores it)
+        proxy_set_header X-WEBAUTH-USER $gitea_user;
     }
 }
 
diff --git a/scripts/install.sh b/scripts/install.sh
index 120236c6..dc63d2f2 100755
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -5,7 +5,7 @@
 # Downloads the latest release tarball and runs the configuration wizard.
 #
 # Usage:
-#   curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/v2/scripts/install.sh | bash
+#   curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/main/scripts/install.sh | bash
 #   bash install.sh [OPTIONS]
 #
 # Options: