1# Spacebar
2
3`https://phoenix-selfhosted.paperclover.net` runs Clover's fork of
4[spacebarchat/server](https://github.com/spacebarchat/server) from branch `main` of
5the private Shale repository `https://shale.paperclover.net/snowcord-server.git`.
6Pushing to that branch is the deploy; `tools/deploy.py` is only needed to change the service definition.
7
8```
9~/dev/snowcord-server jj checkout, remotes: origin = Shale, upstream = GitHub
10 (`master` mirrors upstream, `main` is what runs)
11jj bookmark set main -r @- && jj git push -b main
12curl https://phoenix-selfhosted.paperclover.net/_spacebar/api/version # commit that is live
13```
14
15A push is live about 4 seconds later (3.4 to 4.6 s measured from the start of the push). Dependency changes
16(`package.json` or the lockfile) add an `npm ci`, about 5 s. Previews run the same
17supervisor against the same branch with a fresh database.
18
19## How it works
20
21[`supervisor.mjs`](../service/spacebar/build/supervisor.mjs) is the container's
22only process, on a stock Node image with its working files in the persistent `/work` volume.
23
241. Every 250 ms it reads the branch tip from the repository's Shale storage,
25 mounted read-only at `/source.git`. Shale keeps a repository under its UUID,
26 so renaming it or changing its visibility does not affect the mount; a
27 recreated repository needs the new UUID in `service.pkl`.
282. On a new tip it extracts the tree with `git archive`, installs `node_modules`
29 only when the dependency files changed, and builds with the repo's own
30 `node_modules/.bin/tsc` (TypeScript 7, about 1 s).
313. It starts the new server on a free port, waits for `/api/ping`, then points its
32 TCP listener on 3001 at the new one. The old server is stopped 500 ms later, so
33 open gateway sockets drop and clients reconnect.
34
35A tsc error, a crash, or a server that never answers `/api/ping` leaves the
36previous server running; the reason is in the service log. A newer push cancels a
37start that is still waiting. Rolling back is pushing the old commit again.
38
39- The supervisor also writes everything the container prints (npm, tsc, the server, deploy
40 results) to `/logs/server.log`, with one rotated copy at 10 MB. Production mounts that
41 from `/srv/work/snowcord-server/logs`, so `server-logs.sh` beside `push.sh` in the sandbox
42 prints it (`-f` follows); previews keep their own.
43- `assets/schemas.json` and `assets/openapi.json` deploy as committed. After
44 changing request or response schemas, run `npm run generate:schema` and
45 `npm run generate:openapi` and commit the results, as upstream does.
46- The server runs with `/data` as its working directory, so `jwt.key`, uploads and
47 sessions survive deploys.
48- All revisions share one database. A migration in a pushed commit runs on first
49 start and a revert does not undo it. The old and new server briefly overlap.
50- Changing the supervisor, image or environment redeploys the container, which
51 takes about 9 s to rebuild and start from the branch.
52
53## Voice
54
55The production service publishes the voice WebSocket at `voice.phoenix-selfhosted.paperclover.net:443`.
56[`voice-network.json`](../service/spacebar/voice-network.json) configures the
57loopback WebSocket mapping and the UDP media port. The supervisor builds Pion
58from the Snowcord revision's `flake.lock`: git fetches the pinned commit, `go.sum`
59pins the modules, and the build and SFU run with a minimal environment. The binary
60is kept in `/work` for that pin, so a restart needs no network.
61It starts one SFU and one standalone voice process after the API is healthy.
62Each app release restarts voice, and an unavailable voice process retries
63while the API continues serving. Previews leave voice disabled.