| 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 |
| 5 | the private Shale repository `https://shale.paperclover.net/snowcord-server.git`. |
| 6 | Pushing 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) |
| 11 | jj bookmark set main -r @- && jj git push -b main |
| 12 | curl https://phoenix-selfhosted.paperclover.net/_spacebar/api/version # commit that is live |
| 13 | ``` |
| 14 | |
| 15 | A 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 |
| 17 | supervisor 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 |
| 22 | only process, on a stock Node image with its working files in the persistent `/work` volume. |
| 23 | |
| 24 | 1. 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`. |
| 28 | 2. 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). |
| 31 | 3. 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 | |
| 35 | A tsc error, a crash, or a server that never answers `/api/ping` leaves the |
| 36 | previous server running; the reason is in the service log. A newer push cancels a |
| 37 | start 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 | |
| 55 | The production service publishes the voice WebSocket at `voice.phoenix-selfhosted.paperclover.net:443`. |
| 56 | [`voice-network.json`](../service/spacebar/voice-network.json) configures the |
| 57 | loopback WebSocket mapping and the UDP media port. The supervisor builds Pion |
| 58 | from the Snowcord revision's `flake.lock`: git fetches the pinned commit, `go.sum` |
| 59 | pins the modules, and the build and SFU run with a minimal environment. The binary |
| 60 | is kept in `/work` for that pin, so a restart needs no network. |
| 61 | It starts one SFU and one standalone voice process after the API is healthy. |
| 62 | Each app release restarts voice, and an unavailable voice process retries |
| 63 | while the API continues serving. Previews leave voice disabled. |