steid

1	# Runbook
2
3	> Attempt #2's only setup instructions lived in a plan file describing an architecture
4	> that had already been deleted, so they were actively wrong. Keep this file honest:
5	> if a command here doesn't work, fix it or delete it.
6
7	## Status
8
9	The app boots and serves. Everything marked (#2) is carried from the previous
10	attempt and has not been re-verified against Topcoat — treat it as a sketch.
11
12	## Requirements
13
14	- rustc ≥ 1.95 — Topcoat 0.5 requires it, and on an older toolchain `cargo add
15	topcoat` silently resolves to an empty `topcoat v0.0.0` placeholder rather than
16	failing. Verified on 1.97.1.
17	- `git` on `PATH` (from Milestone 3 — `git init --bare` creates repos, and from
18	Milestone 4 `git http-backend` serves the protocol)
19
20	## Dev setup
21
22	```bash
23	cargo run # serves on http://127.0.0.1:3000
24	cargo test
25	```
26
27	```bash
28	cargo install topcoat-cli # dev server: watch, rebuild, asset bundling
29	topcoat dev # working
30	```
31
32	`topcoat dev` builds, bundles assets, watches sources, and live-reloads pages that
33	include `topcoat::dev::script()`. Press `r` to force a rebuild.
34
35	## Configuration
36
37	`STEID_`-prefixed env vars via `dotenvy` + `envy`, read into `AppConfig`. Every value
38	has a default, so a bare `cargo run` works with no environment at all.
39
40	Live now:
41
42	```
43	STEID_DATABASE_URL=sqlite:steid.db?mode=rwc # default
44	STEID_DATA_DIR=./data # default; bare repos, used from M3
45	STEID_INSECURE_COOKIES=false # default; see below
46	```
47
48	There is deliberately no owner password in configuration — the owner is created
49	through the claim flow instead. See
50	[0002](decisions/0002-first-run-claim-not-config-bootstrap.md).
51
52	The bind address is not a `STEID_` variable — Topcoat owns it:
53
54	```bash
55	HOST=0.0.0.0 PORT=8080 cargo run
56	```
57
58	That supersedes attempt #2's `STEID_LISTEN_ADDR`.
59
60	### `STEID_INSECURE_COOKIES` — development only
61
62	Topcoat's session cookie is `__Host-` prefixed and `Secure`. `Secure` means the browser
63	only keeps it over a trustworthy origin, and browsers disagree about whether
64	plain-HTTP `localhost` qualifies. Where it doesn't, **the failure is completely
65	silent**: the server issues a session and records the row, the browser discards the
66	cookie, and every page renders signed out with no error anywhere. This cost an
67	afternoon; the symptom looks exactly like broken auth logic.
68
69	Setting `STEID_INSECURE_COOKIES=true` swaps in `InsecureCookieTokenStore` — the same
70	cookie without `Secure` and without the prefix, named `steid-dev-session` so it can
71	never be confused with a hardened one. `HttpOnly` and `SameSite=Lax` are kept. Boot
72	prints a warning while it's on.
73
74	Never set this on a deployed instance. Without `Secure` the session cookie travels
75	unencrypted and anyone on the network path can lift it and become that user. Behind
76	TLS, leave it unset.
77
78	A gitignored `.env` in the repo root sets it for local work. Keep `.env` and
79	`.env.prod` out of git — both are gitignored.
80
81	## First run
82
83	```bash
84	cargo run # or: topcoat dev
85	```
86
87	An unclaimed instance prints a setup token and redirects every route to `/auth/setup`.
88	Paste the token, choose a handle, email, and password, and the owner is created and
89	signed in.
90
91	The token is held in memory only, so every restart mints a new one — including
92	each rebuild under `topcoat dev`. Use the most recent one printed. Once claimed, no
93	token is minted at all and `/auth/setup` redirects away.
94
95	Sign in at `/auth/login` with the email, not the handle.
96
97	## Repo layout on disk (Milestone 3)
98
99	Bare repos at `{STEID_DATA_DIR}/{handle}/{name}.git`. Created empty — no initial
100	commit, like GitHub.
101
102	## Git transport (Milestone 4)
103
104	Smart HTTP, delegated to `git http-backend`, authenticated with personal access tokens
105	over HTTP Basic — see [0001](decisions/0001-git-over-http-not-ssh.md). No SSH, no host
106	keys, no `authorized_keys`.
107
108	```bash
109	git clone http://host/{handle}/repos/{name}.git
110	```
111
112	Fill in the token workflow and the `body_limit` setting once this is built.
113
114	## Manual verification checklist (#2)
115
116	Attempt #2 verified these by hand each milestone but never wrote down the steps. They
117	are the smoke test for Milestones 4–5. The auth rows assumed SSH keys; the shape of
118	the check still holds with tokens substituted:
119
120	- [ ] Create a repo via the web UI → bare repo appears at
121	`{data_dir}/{org}/{repo}.git`
122	- [ ] `git clone` an empty repo → succeeds
123	- [ ] `git clone` a repo with history → succeeds
124	- [ ] `git clone` a non-existent repo → clean error, not a hang or panic
125	- [ ] First push to an empty repo → succeeds
126	- [ ] Push to a repo with history → succeeds
127	- [ ] Push a repo large enough to exercise the `body_limit` cap → succeeds
128	- [ ] Clone with no credentials → rejected, and the prompt is comprehensible
129	- [ ] Clone with a valid token → succeeds
130	- [ ] Revoke the token → subsequent clone rejected at auth
131	- [ ] Clone a private repo as a non-member → rejected
132	- [ ] Push as a non-owner member → rejected
133
134	Worth automating as an integration test rather than re-running by hand a fourth time.
135
136	## `.gitignore`
137
138	Applied: `/target`, `/data`, `.db`, `.env`, `.env.prod`.
139
140	Do not add `/plans`. Attempt #2 did, and that is why these docs had to be
141	hand-carried between repos.