# 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.