docs(self-host): improve self hosting docs (#1800)

* docs(self-host): add manual install guide

* docs: update self-hosting docs

Author: tyler-dane

README.md

@@ -37,7 +37,9 @@ It'll be around for the long-term:
 - User sessions
 
 ### The Limitations
+
 Current things we don't support (yet):
+
 - Subcalendar sync (only primary calendar)
 - Sharing, reminders, locations
 - Mobile app
@@ -86,6 +88,7 @@ We love contributions! Whether it's bug fixes, new features, or documentation im
 **Feedback**: Share your ideas on [GitHub Discussions](https://github.com/SwitchbackTech/compass/discussions).
 
 ## Resources
+
 - **Docsite**: [docs.compasscalendar.com](https://docs.compasscalendar.com/docs)
 - **Changelog**: [compasscalendar.com](https://changelog.compasscalendar.com)
 - **Handbook**: [notion.site](https://alpaca-ty.notion.site/Compass-Handbook-26b237bde8f4805c9a56de6db3a7993d?utm_source=github&utm_medium=referral&utm_campaign=readme)

docs/development/quickstart.md

@@ -0,0 +1,43 @@
+# Development Quickstart
+
+## Get code and dependencies
+
+```bash
+git clone git@github.com:SwitchbackTech/compass.git
+
+cd compass
+
+bun install
+
+## Setup config values
+
+```bash
+cp compass.example.yaml compass.yaml
+```
+
+Replace the placeholder values in `compass.yaml`
+
+## Run
+
+Run the web app in one terminal:
+
+```bash
+bun run dev:web
+# Frontend on <http://localhost:9080>
+```
+
+Run the backend in another terminal:
+
+```bash
+bun run dev:backend  
+# Backend on <http://localhost:3000>
+```
+
+## Testing
+
+After making your changes, you can run our test suite locally before opening a PR.
+
+```bash
+bun run test:core && bun run test:web && bun run test:backend
+bun run test:e2e
+```

docs/self-hosting/README.md

@@ -6,7 +6,7 @@ Start with [Run Compass on a server](./server-guide.md). It walks through a smal
 
 If you only want to run Compass on your own computer, use the normal local development flow with Bun instead of the self-host installer.
 
-## What Compass is made of
+## Compass architecture
 
 When you self-host Compass on a server, you get a stack of small services. Only the public website and API are reachable from your browser. The databases stay private inside Docker.
 
@@ -32,19 +32,8 @@ flowchart TD
 
 ## Start here
 
-- New self-host install: [Run Compass on a server](./server-guide.md)
-- Backups and restore: [Back up and restore your data](./backup-and-restore.md)
-- Google Calendar: [Add Google Calendar](./google-calendar.md)
-- Monitoring: [Monitoring](./monitoring.md)
+Ready to get this setup on your infrastructure? See [Run Compass on a server](./server-guide.md)
 
-## What you still need to handle yourself
-
-These docs keep the default self-host path focused on a small server. They do not set up:
-
-- a built-in backup scheduler
-- an automatic restore flow
-- a rollback command for `./compass update`
-- Docker backups for browser IndexedDB data
-- automatic Google Calendar watch maintenance (see [Google Calendar](./google-calendar.md))
+----
 
 Have an idea on how we can make self-hosting easier? Let us know in [this GitHub Discussion](https://github.com/SwitchbackTech/compass/discussions/1694).

docs/self-hosting/backup-and-restore.md

@@ -334,4 +334,6 @@ rerun the installer.
 After you have a backup you trust, return to [Server hosting guide](./server-guide.md)
 for server checks and update notes.
 
+----
+
 Have an idea on how we can make self-hosting easier? Let us know in [this GitHub Discussion](https://github.com/SwitchbackTech/compass/discussions/1694).

docs/self-hosting/customizing.md

@@ -0,0 +1,32 @@
+# Custom code guide
+
+We deploy our code to DockerHub so it's easy to pull them down during updates without manually rebuilding. This guide is for those who want to run their own Compass code in their selfhosted environment.
+
+> **Warning: back up before every update.** `./compass update` rebuilds with newer code. There is no rollback. Back up `~/compass/compass.yaml`, the Mongo volumes, and the SuperTokens Postgres volume **together**. See [Backups and restore](./backup-and-restore.md).
+
+Then:
+
+```bash
+cd ~/compass
+./compass update
+```
+
+## Customizing web code
+
+There are a few scenarios when you'll need to customize things:
+
+- When you want to change the API URL used by the browser
+- When you want to enable Google OAuth
+
+These values are baked into the web bundle, so they require a rebuild.
+
+If you need one of those values to differ from the published image, build and push a custom `compass-web` image, then set `web.image` in `compass.yaml` to the
+tag you pushed:
+
+```yaml
+web:
+  image: your-registry/compass-web:your-tag
+  url: https://compass.example.com
+```
+
+The `compass` script exports `web.image` as `COMPASS_WEB_IMAGE` and Docker Compose uses it automatically. Run `./compass restart` after updating the field.

docs/self-hosting/google-calendar.md

@@ -166,4 +166,6 @@ The repo has the code paths for Google watches and repair. The self-host Docker
 
 If you need public Google watch notifications, continue with [Server hosting guide](./server-guide.md).
 
+----
+
 Have an idea on how we can make self-hosting easier? Let us know in [this GitHub Discussion](https://github.com/SwitchbackTech/compass/discussions/1694).

docs/self-hosting/monitoring.md

@@ -11,15 +11,19 @@ GET /api/health
 No authentication required.
 
 **Response (healthy):** `200 OK`
+
 ```json
 {"status": "ok", "timestamp": "2025-01-01T00:00:00.000Z"}
 ```
 
 **Response (unhealthy):** `500 Internal Server Error`
+
 ```json
 {"status": "error", "timestamp": "2025-01-01T00:00:00.000Z"}
 ```
 
 The check calls `db.admin().ping()` against MongoDB. Call it on whatever schedule makes sense for your setup — Compass does not impose a polling interval.
 
+----
+
 Have an idea on how we can make self-hosting easier? Let us know in [this GitHub Discussion](https://github.com/SwitchbackTech/compass/discussions/1694).