feat(self-host): improve on-premises deployment for homelabbers (#1737)

* feat(self-host): improve on-premises deployment for homelabbers

- Publish images to Docker Hub (switchbacktech/compass-{backend,web,mongo})
  with semver tags (X.Y.Z, X.Y, latest) via new publish-images.yml workflow
- Switch docker-compose.yml from local builds to Hub image references;
  keep commented-out build blocks for users who need custom builds
- Add compass_backend_logs and compass_mongo_configdb named volumes so all
  writable paths are on volumes; add read_only: true + tmpfs on backend and web
- Run backend and web containers as non-root compass user (uid 1001);
  no extra Linux capabilities required
- Simplify install.sh from 947 to ~270 lines: replace git/archive download
  with curl for docker-compose.yml and compass helper; no --build on startup
- Update compass helper: COMPOSE_FILE now at $INSTALL_DIR/docker-compose.yml,
  update command uses docker compose pull instead of git fetch + build
- Rename COMPASS_REF to COMPASS_VERSION throughout; add secret generation
  hints to .env.example
- Add docs/Self-Hosting/environment-variables.md: full env var reference
  derived from backend and web Zod schemas
- Document health endpoint in Self-Hosting README

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: removed advanced-manual doc

* docs(self-host): restructure env vars and monitoring docs

- Convert environment-variables.md to markdown tables
- Remove intro copy/secret-generation lines from environment-variables.md
- Extract health endpoint into standalone monitoring.md
- Remove env vars and health endpoint links from README, add monitoring link

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* refactor(self-host): derive project name from install directory

Remove COMPOSE_PROJECT_NAME env var. Docker Compose project name is now
derived from basename of the install directory in both install.sh and the
compass helper, so --project-name stays consistent without requiring an
explicit env var. Users who need a second install use a different directory.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* chore(self-host): remove .env.example, point to backend example file

The installer auto-generates .env so a separate template adds no value.
Update self-host/README.md and environment-variables.md to reference
packages/backend/.env.local.example instead.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(self-host): clean up compose comment style and env vars doc reference

* docs: remove outdated deploy.md

* docs: add CI-CD section, move cli commands doc into it

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(ci-cd): simplify publish-images docs and remove outdated build-args section

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: tyler-dane

.github/workflows/publish-images.yml

@@ -0,0 +1,76 @@
+name: Publish Docker images
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Derive semver tags from git tag
+        id: version
+        run: |
+          TAG="${GITHUB_REF_NAME}"        # e.g. v1.2.3
+          VERSION="${TAG#v}"              # 1.2.3
+          MINOR="${VERSION%.*}"           # 1.2
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "minor=${MINOR}"    >> "$GITHUB_OUTPUT"
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build and push compass-backend
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: self-host/Dockerfile.backend
+          push: true
+          tags: |
+            switchbacktech/compass-backend:${{ steps.version.outputs.version }}
+            switchbacktech/compass-backend:${{ steps.version.outputs.minor }}
+            switchbacktech/compass-backend:latest
+
+      - name: Build and push compass-mongo
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: self-host/Dockerfile.mongo
+          push: true
+          tags: |
+            switchbacktech/compass-mongo:${{ steps.version.outputs.version }}
+            switchbacktech/compass-mongo:${{ steps.version.outputs.minor }}
+            switchbacktech/compass-mongo:latest
+
+      - name: Build and push compass-web
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: self-host/Dockerfile.web
+          push: true
+          # BASEURL and GOOGLE_CLIENT_ID are baked into the web bundle at build time.
+          # The published image ships with localhost defaults, which work for local installs.
+          # Users who need a custom API domain or real Google credentials must rebuild
+          # the web image locally using the build: blocks in docker-compose.yml.
+          build-args: |
+            BASEURL=http://localhost:3000/api
+            GOOGLE_CLIENT_ID=compass-self-host-placeholder.apps.googleusercontent.com
+            COMPASS_BUILD_REF=${{ steps.version.outputs.version }}
+          tags: |
+            switchbacktech/compass-web:${{ steps.version.outputs.version }}
+            switchbacktech/compass-web:${{ steps.version.outputs.minor }}
+            switchbacktech/compass-web:latest

docs/CI-CD/README.md

@@ -0,0 +1,57 @@
+# CI/CD
+
+Compass uses GitHub Actions for continuous integration and Docker Hub for distributing self-host images.
+
+## Workflows
+
+| Workflow | Trigger | Purpose |
+|---|---|---|
+| Test | Push / PR to `main` | Runs lint, type-check, and unit tests |
+| CodeQL | Push / PR to `main` | Static security analysis |
+| Publish Docker images | Push a `v*.*.*` tag | Builds and publishes self-host images to Docker Hub |
+| Sync docs to compass-docs | Push to `main` touching `docs/**` | Mirrors this `docs/` directory to docs.compasscalendar.com |
+
+---
+
+## Publish Docker Images
+
+Source: [`.github/workflows/publish-images.yml`](../../.github/workflows/publish-images.yml)
+
+### How it works
+
+1. A maintainer pushes a git tag matching `v[0-9]+.[0-9]+.[0-9]+` (e.g. `v1.2.3`).
+2. The workflow strips the `v` prefix and derives two tag aliases:
+   - `1.2.3` — exact patch version
+   - `1.2` — floating minor alias
+3. It builds and pushes three images to Docker Hub:
+   - `switchbacktech/compass-backend`
+   - `switchbacktech/compass-mongo`
+   - `switchbacktech/compass-web`
+4. Each image gets all three tags: `1.2.3`, `1.2`, and `latest`.
+
+### Manually publishing a release
+
+Although tags are created automatically as part of the release flow, you can also create them manually to publish images from a local branch.
+
+```sh
+git tag v1.2.3
+git push origin v1.2.3
+```
+
+Watch progress in the [Actions tab](https://github.com/SwitchbackTech/compass/actions). After the workflow completes, all three images appear on Docker Hub under the `switchbacktech` org.
+
+### Removing a test tag
+
+```sh
+git push origin --delete v1.2.3
+git tag -d v1.2.3
+```
+
+### Required secrets
+
+Two secrets must be set in **GitHub → Settings → Secrets and variables → Actions**:
+
+| Secret | Value |
+|---|---|
+| `DOCKERHUB_USERNAME` | Docker Hub username for the `switchbacktech` org |
+| `DOCKERHUB_TOKEN` | Docker Hub personal access token (Read & Write) |

…elopment/cli-and-maintenance-commands.md …cs/CI-CD/cli-and-maintenance-commands.mddocs/development/cli-and-maintenance-commands.md renamed to docs/CI-CD/cli-and-maintenance-commands.md docs/development/cli-and-maintenance-commands.md renamed to docs/CI-CD/cli-and-maintenance-commands.md

@@ -40,8 +40,8 @@ Markdown files in this `docs/` directory are automatically mirrored to [docs.com
 - [Self-Hosting](./self-hosting/README.md)
 - [Testing Playbook](./development/testing-playbook.md)
 - [Types And Validation](./development/types-and-validation.md)
-- [CLI And Maintenance Commands](./development/cli-and-maintenance-commands.md)
-- [Deploy](./development/deploy.md)
+- [CI/CD](./ci-cd/README.md)
+- [CLI And Maintenance Commands](./ci-cd/cli-and-maintenance-commands.md)
 
 ## Feature Deep Dives
 

docs/README.md

@@ -73,7 +73,7 @@ bun run cli delete -u <email>
 
 The delete flow removes both Compass data and SuperTokens auth state. The browser cleanup screen only clears local browser storage after the server-side purge is complete.
 
-See [CLI And Maintenance Commands](./cli-and-maintenance-commands.md) for the current delete flow.
+See [CLI And Maintenance Commands](../ci-cd/cli-and-maintenance-commands.md) for the current delete flow.
 
 ### Invalid domain name
 

docs/development/deploy.md

@@ -36,6 +36,7 @@ flowchart TD
 - Backups and restore: [Back up and restore your data](./backups-and-restore.md)
 - Google Calendar: [Add Google Calendar](./google-calendar.md)
 - Manual Bun setup: [Run Compass without the installer](./advanced-manual.md)
+- Monitoring: [Monitoring](./monitoring.md)
 
 ## What you still need to handle yourself