4.4 KiB
Deployment
A decision record comparing the two hosting paths under consideration: a plain web host, or packaging the server as a StartOS service. No packaging work is done here — this exists so the choice can be made deliberately, and so the architecture does not accidentally foreclose either option.
Target remains small self-hosted scale.
1. What the server needs, either way
The requirements are modest, which is what makes both paths viable:
| Need | Why |
|---|---|
| One long-running process | Active games are held in memory (overview.md) |
| HTTP + WebSocket on one port | Lobby over HTTP, game stream over WebSocket (protocol.md) |
| A writable data directory | The append-only event log (lobby-and-sessions.md) |
| Static asset serving | The browser client |
| No outbound network access | The game talks to nobody |
| No scheduled work | Nothing in the rules is real-time (overview.md) |
No database server, no message broker, no cache, no cron. SQLite or flat files cover persistence. That single-process, single-port, one-volume shape is the least demanding thing either platform has to host.
2. Plain web host
What it takes: a small VM or container host, a reverse proxy terminating TLS, a process manager, and a backup of the data directory.
Advantages. Anyone with a link can join, which matters for a game whose discovery mechanism is "read a code aloud to your friends." Deployment is unremarkable and every stack has good support for it.
Costs. You own TLS certificates, updates, backups, and uptime. And a public URL means the server is exposed to the open internet, which raises questions the game does not otherwise have — abuse of game creation, resource exhaustion from unbounded lobbies, and the need for at least basic rate limiting.
3. StartOS service
What it takes: packaging the server as an .s9pk. The workspace guide is on disk at
start-technologies/projects/start-sdk/docs/src/ — recipe-basic-service.md for the overall shape,
interfaces.md for how the UI is exposed, recipe-health-checks.md for readiness, and
recipe-backups.md for the data directory. Start with recipes.md, which is the intent index.
Advantages. Installation, updates, TLS and backups are the platform's job rather than yours. The service declares what it exposes; the user decides where it is reachable from. For a friends-and- family game that fits well — the person running it already controls who gets the address.
Costs. Players must reach the host, which is a real constraint for a browser game: everyone needs network access to that StartOS box. How they get it is the user's configuration decision, not something the application chooses or should claim.
One thing the architecture must respect. A packaged service should not assume it is reachable at a fixed, publicly-routable URL. Anything that bakes an origin into the client — absolute WebSocket URLs, hard-coded hostnames in links, CORS allow-lists pinned to one domain — will break. Serve the client from the same origin as the API and use relative URLs throughout. This costs nothing on a plain web host and is required on StartOS, so it should simply be the rule.
4. Recommendation
Build for both; decide later. The requirements in §1 are satisfied identically by either path, and the only architectural constraint that differs is the same-origin/relative-URL rule in §3 — which is good practice regardless.
Concretely, do this from the start:
- Single process, single port, serving both the client and the API.
- Relative URLs everywhere in the client. No baked-in origin, no hard-coded hostname.
- All state under one configurable data directory, path supplied by environment variable.
- No assumption of public reachability anywhere in the code.
- Bind address and port configurable by environment variable.
That set keeps both doors open at no cost. The decision only needs making when there is something worth deploying — and by then it will be an easier call, because you will know whether the people playing it are on your network or scattered.
5. Explicitly not decided here
- The stack. Still open; nothing above depends on it.
- Whether to publish to a StartOS registry (
publishing.mdin the guide) — irrelevant until the game runs. - Domain names, TLS specifics, or backup schedules for the plain-host path.