Skip to content

Commit faa809d

Browse files
authored
docs: update self-host web image guidance (#1797)
1 parent b4bafd6 commit faa809d

1 file changed

Lines changed: 11 additions & 30 deletions

File tree

docs/self-hosting/server-guide.md

Lines changed: 11 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,7 @@ A separate API domain like `https://api.compass.example.com` may be possible, bu
3535
3. SSH into the server and install Compass with the self-host installer.
3636
4. Configure Caddy to proxy `compass.example.com` to `127.0.0.1:9080` and `/api/*` to `127.0.0.1:3000`.
3737
5. Verify Caddy can reach the local backend over HTTPS.
38-
6. Edit `~/compass/compass.yaml` to use your public URLs, then recreate the backend
39-
container and rebuild the web container.
38+
6. Edit `~/compass/compass.yaml` to use your public URLs, then restart Compass.
4039
7. Sign in over HTTPS and run the basic tests below.
4140
8. (Optional) Add Google Calendar.
4241

@@ -250,34 +249,18 @@ cd ~/compass
250249
./compass restart
251250
```
252251

253-
### Rebuild the web image with your public URL
252+
### Use a custom web image only when needed
254253

255-
`backend.apiUrl` and `google.clientId` are baked into the web bundle at build time — a restart alone is not enough. You have two options:
254+
Most self-hosted installs should use the Compass web image from Docker Hub. The
255+
web container does not read `compass.yaml` at runtime, so a custom web image is
256+
only needed when you change frontend values that are baked into the web bundle:
256257

257-
**Option A — build from source (recommended for custom domains)**
258+
- the API URL used by the browser
259+
- the Google OAuth client ID
258260

259-
Uncomment the `build:` block in `~/compass/compose.yaml`, fill in your real values, then rebuild:
260-
261-
```yaml
262-
# In ~/compass/compose.yaml, under the web service:
263-
build:
264-
context: ..
265-
dockerfile: self-host/Dockerfile.web
266-
args:
267-
BASEURL: https://compass.example.com/api
268-
GOOGLE_CLIENT_ID: "" # leave empty unless adding Google Calendar
269-
```
270-
271-
```bash
272-
cd ~/compass
273-
./compass rebuild
274-
```
275-
276-
This builds the web image locally on the VPS. It can be slow on a small instance.
277-
278-
**Option B — provide a pre-built image**
279-
280-
If you build the web image elsewhere (e.g. in CI), set `web.image` in `compass.yaml` to the tag you pushed:
261+
If you need one of those values to differ from the published image, build and
262+
push a custom `compass-web` image, then set `web.image` in `compass.yaml` to the
263+
tag you pushed:
281264

282265
```yaml
283266
web:
@@ -287,9 +270,7 @@ web:
287270

288271
The `compass` script exports `web.image` as `COMPASS_WEB_IMAGE` and Docker Compose uses it automatically. Run `./compass restart` after updating the field.
289272

290-
> **Note for automated deployments.** If you deploy via the Compass CI workflow (`_deploy-environment.yml`), the workflow builds an environment-specific web image with the correct `BACKEND_API_URL` and writes `web.image` into `compass.yaml` for you. No manual rebuild is needed on the server.
291-
292-
Confirm the public health check still works after applying the env changes:
273+
Confirm the public health check still works after applying the config changes:
293274

294275
```bash
295276
curl -f https://compass.example.com/api/health

0 commit comments

Comments
 (0)