95 lines
4.4 KiB
Markdown
95 lines
4.4 KiB
Markdown
# 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`](overview.md)) |
|
|
| HTTP + WebSocket on one port | Lobby over HTTP, game stream over WebSocket ([`protocol.md`](protocol.md)) |
|
|
| A writable data directory | The append-only event log ([`lobby-and-sessions.md`](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`](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:
|
|
|
|
1. **Single process, single port**, serving both the client and the API.
|
|
2. **Relative URLs everywhere** in the client. No baked-in origin, no hard-coded hostname.
|
|
3. **All state under one configurable data directory**, path supplied by environment variable.
|
|
4. **No assumption of public reachability** anywhere in the code.
|
|
5. **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.md` in the guide) — irrelevant until the game
|
|
runs.
|
|
- Domain names, TLS specifics, or backup schedules for the plain-host path.
|