Update self-host docs for cleaner onboarding

README.md

@@ -62,12 +62,6 @@ Head over to [app.compasscalendar.com](https://app.compasscalendar.com?utm_sourc
 
 Run Compass on your own machine with the local Docker installer. Password-only self-hosting is supported; Google Calendar is optional.
 
-With Docker Desktop installed and running, install the local self-hosted stack:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/SwitchbackTech/compass/main/self-host/install.sh | sh
-```
-
 See [docs/self-hosting.md](./docs/self-hosting.md) to choose the right self-hosting guide and read the local install, backup, Google Calendar, and server-hosting notes.
 
 ### Run Locally

docs/self-hosting.md

@@ -55,13 +55,16 @@ Most people want the first one. Pick based on where you want Compass to live and
 | [Server hosting guide](./self-hosting/server-guide.md) | You want to serve Compass from a public domain with Docker Compose and Caddy. |
 | [Advanced manual setup](./self-hosting/advanced-manual.md) | You want to run the pieces yourself instead of using the installer. |
 
-## The one warning that matters
+## Keep `.env` with your data
 
-> **Warning: keep `~/compass/.env`.**
->
-> That file holds the generated passwords and tokens that match your Docker volumes. If the volumes stay but `.env` is gone, a new install creates different credentials and locks you out of the old data.
->
-> Before `./compass update` or anything that touches the install, back up `~/compass/.env`, the Mongo volume, and the SuperTokens Postgres volume together. They're a set. See [Backups and restore](./self-hosting/backups-and-restore.md). Browser IndexedDB data (tasks, pre-signup events) is not included.
+`~/compass/.env` holds the generated passwords and tokens that match your
+Docker volumes. If the volumes stay but `.env` is gone, a new install creates
+different credentials and can lock you out of the old data.
+
+Before `./compass update` or anything that touches the install, back up
+`~/compass/.env`, the Mongo volume, and the SuperTokens Postgres volume together.
+They're a set. See [Backups and restore](./self-hosting/backups-and-restore.md).
+Browser IndexedDB data (tasks, pre-signup events) is not included.
 
 ## What this guide does not set up yet
 
@@ -74,12 +77,9 @@ These docs keep the default path focused on local Docker self-hosting. They do n
 - Docker backups for browser IndexedDB data
 - continuous Google Calendar sync on the local-only install (see [Google Calendar](./self-hosting/google-calendar.md) for why)
 
-## Quick install
-
-If you're ready to use the local Docker path, install Docker Desktop, make sure it's running, then run:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/SwitchbackTech/compass/main/self-host/install.sh | sh
-```
+## Start here
 
-For the full local guide, including what to expect, how to manage the install, and troubleshooting, read [Local quickstart](./self-hosting/local-quickstart.md).
+For the full local guide, including what to expect, how to manage the install,
+and troubleshooting, read [Local quickstart](./self-hosting/local-quickstart.md).
+If you want Compass on a VPS with your own domain, read
+[Server hosting guide](./self-hosting/server-guide.md).

docs/self-hosting/server-guide.md

@@ -24,6 +24,16 @@ You'll need:
 
 The examples use `compass.example.com`. Replace it with your real domain everywhere.
 
+If you're starting from a fresh VPS, install Docker Engine, Docker Compose, and
+Caddy before continuing. Prefer the official apt packages over Snap packages:
+
+- [Docker Engine on Ubuntu](https://docs.docker.com/engine/install/ubuntu/)
+- [Caddy on Debian, Ubuntu, Raspbian](https://caddyserver.com/docs/install#debian-ubuntu-raspbian)
+
+If the server has been used for other projects, do the checks in the next
+section before you install Compass. Existing web servers, private-network tools,
+or firewall rules can block Caddy even when the Compass containers are healthy.
+
 ## The shape
 
 One public domain, two paths:
@@ -35,16 +45,62 @@ Compass binds to `127.0.0.1:9080` and `127.0.0.1:3000` on the server. Caddy prox
 
 A separate API domain like `https://api.compass.example.com` may be possible, but it adds cookie and CORS complexity. This guide uses one domain for the first server install.
 
+## 0. Point DNS and check the server
+
+Create a DNS record for the subdomain you want to use:
+
+```text
+Type: A
+Name: compass
+Value: <your-vps-ipv4-address>
+```
+
+That example makes `compass.example.com` point at the server's public IPv4
+address. DNS is managed wherever your domain's nameservers point. That may be
+your registrar, but it may also be another host such as Cloudflare or Vercel.
+
+You can confirm the record from your own computer:
+
+```bash
+dig +short A compass.example.com
+```
+
+It should print your VPS IPv4 address. Don't add an `AAAA` record unless the
+server's IPv6 is configured and reachable.
+
+On the server, confirm the basic tools and ports:
+
+```bash
+lsb_release -a
+docker --version
+docker compose version
+caddy version
+sudo systemctl status caddy --no-pager
+sudo ss -tulpn | grep -E ':(80|443|3000|9080)\b' || true
+sudo ufw status verbose || true
+```
+
+For the recommended setup:
+
+- Caddy should run as a system service.
+- Public ports `80` and `443` should be available for Caddy.
+- Ports `3000` and `9080` should be unused before the Compass installer runs.
+- If UFW or another firewall is enabled, allow inbound TCP `80` and `443`.
+
+Caddy needs port `80` for the first certificate setup and HTTP-to-HTTPS
+redirects. It needs port `443` for the final HTTPS site.
+
 ## Steps in order
 
 Order matters. The helper script's health check uses `BASEURL`, so set up Caddy **before** changing `BASEURL` to your public URL. Otherwise the rebuild fails its health check against an HTTPS URL that isn't routed yet.
 
-1. SSH into the server and install Compass with the local installer.
-2. Configure Caddy to proxy `compass.example.com` to `127.0.0.1:9080` and `/api/*` to `127.0.0.1:3000`.
-3. Verify Caddy can reach the local backend over HTTPS.
-4. Edit `~/compass/.env` to use your public URLs, then `./compass rebuild`.
-5. Sign in over HTTPS and run the basic tests below.
-6. (Optional) Add Google Calendar.
+1. Point DNS at the server and confirm the server has Docker, Compose, Caddy, and open `80`/`443`.
+2. SSH into the server and install Compass with the local installer.
+3. Configure Caddy to proxy `compass.example.com` to `127.0.0.1:9080` and `/api/*` to `127.0.0.1:3000`.
+4. Verify Caddy can reach the local backend over HTTPS.
+5. Edit `~/compass/.env` to use your public URLs, then `./compass rebuild`.
+6. Sign in over HTTPS and run the basic tests below.
+7. (Optional) Add Google Calendar.
 
 ## 1. Install Compass on the server
 
@@ -70,7 +126,15 @@ compass.example.com {
 }
 ```
 
-Reload Caddy after saving.
+Validate and reload Caddy after saving:
+
+```bash
+sudo caddy validate --config /etc/caddy/Caddyfile
+sudo systemctl reload caddy
+```
+
+If this is the first real HTTPS site on the server, Caddy will fetch a
+certificate after the reload. That can take a few seconds.
 
 ## 3. Verify Caddy can reach the backend
 
@@ -80,6 +144,24 @@ curl -f https://compass.example.com/api/health
 
 A healthy backend returns JSON with `"status":"ok"`. If this fails, Caddy isn't routing to the backend yet. Fix that before moving on.
 
+If `curl` cannot connect to port `443`, check that Caddy is listening there:
+
+```bash
+sudo ss -tulpn | grep -E ':(80|443)\b' || true
+sudo systemctl status caddy --no-pager -l
+sudo journalctl -u caddy --since '10 minutes ago' --no-pager -l
+```
+
+If another process already owns `443`, Caddy cannot serve HTTPS. Common examples
+are another web server, an old Caddy process, or a private-network HTTPS feature
+such as Tailscale Serve. Stop or move the conflicting service, then restart
+Caddy:
+
+```bash
+sudo systemctl reset-failed caddy
+sudo systemctl restart caddy
+```
+
 ## 4. Switch Compass to your public URLs
 
 > **Warning.** Don't change `BASEURL` until step 3 succeeds. The helper script uses `BASEURL` for its own health check during rebuild. If `BASEURL` points at an HTTPS URL Caddy can't serve yet, the rebuild fails.
@@ -108,6 +190,12 @@ cd ~/compass
 ./compass rebuild
 ```
 
+Confirm the public health check still works after the rebuild:
+
+```bash
+curl -f https://compass.example.com/api/health
+```
+
 > **Tip.** If you ever need the helper to check the local backend directly while `BASEURL` stays public, add `COMPASS_HEALTH_URL=http://127.0.0.1:3000/api/health` to `~/compass/.env`. Most one-domain installs don't need this once Caddy is working.
 
 ## 5. Sign in and test the basics
@@ -125,6 +213,18 @@ Open `https://compass.example.com` in a browser. Run the password-only path firs
 
 Doing this before Google keeps the first server test focused on Compass, auth, and storage.
 
+For a final server-side check, run:
+
+```bash
+cd ~/compass
+./compass status
+sudo ss -tulpn | grep -E ':(80|443|3000|9080)\b' || true
+curl -f https://compass.example.com/api/health
+```
+
+You want the Compass containers healthy, Caddy listening on public `80` and
+`443`, and the Compass backend/web containers still bound only to `127.0.0.1`.
+
 ## 6. Add Google Calendar (optional)
 
 If you want Google sign-in or Google Calendar watch notifications, see [Google Calendar — Public watch notifications](./google-calendar.md#public-watch-notifications). The short version:
@@ -155,4 +255,8 @@ This guide gives one coherent server shape. It doesn't automate everything a pro
 - Google Calendar continuous sync needs server-specific setup and testing.
 - A separate API domain is not the recommended first path.
 
-> **Warning.** Don't expose MongoDB, SuperTokens, or Postgres to the public internet. A safe server keeps those private and exposes only the web app and API through HTTPS.
+The default compose file keeps MongoDB, SuperTokens, and Postgres off the public
+internet. Keep it that way. Don't add public port mappings for those services,
+don't open their ports in your firewall, and don't move them to public database
+hosts unless you know how you want to secure them. For this guide, only Caddy
+should be public, and Caddy should proxy only the web app and `/api`.

self-host/README.md

@@ -8,13 +8,10 @@ This README is a quick reference for what each file in this folder does. For ins
 
 ## Install Compass
 
-With Docker Desktop running:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/SwitchbackTech/compass/main/self-host/install.sh | sh
-```
-
-Compass will be available at `http://localhost:9080` (web) and `http://localhost:3000/api` (backend). The compose stack binds those ports to `127.0.0.1` and is not a public-server installer.
+For install steps, start with [Local quickstart](../docs/self-hosting/local-quickstart.md).
+Compass will be available at `http://localhost:9080` (web) and
+`http://localhost:3000/api` (backend). The compose stack binds those ports to
+`127.0.0.1` and is not a public-server installer.
 
 ## Files in this folder