Point the design-time factory at the stack the repo ships

`dotnet ef database update --project src/DodoSSH.Infrastructure` — the
command the README documents — failed on a clean machine. The design-time
default named `dodossh_design` as user `postgres` with no password, which is
a database this repository never creates, while the development compose
stack creates `dodossh`/`dodossh`. The failure arrives as a SCRAM
authentication error, so it reads like a broken container rather than a
stale default.

The default is now the compose stack, since that is the only local database
the repo defines. DODOSSH_DESIGN_CONNECTION still overrides it, and a real
deployment migrates through that or the migrator job.

Also documents running the thing end to end, which the README never covered:
the four commands in order, that migrations are a separate step because the
API deliberately fails readiness rather than migrating, and the three M1 gaps
visible in the first five minutes — so they are expected rather than
diagnosed.
This commit is contained in:
2026-07-29 12:17:59 +02:00
parent 34304b989b
commit b9e7c258ae
2 changed files with 55 additions and 4 deletions
+38 -1
View File
@@ -78,7 +78,28 @@ The tests need a Docker daemon. Everything that touches the database, the identi
server uses Testcontainers rather than a stub or a shared instance, so there is nothing to start first and
nothing to clean up after — but with no daemon those suites fail rather than skip.
Run the API locally:
## Running it
Four commands, in order. The first two are once per machine.
**1. The development dependencies** — PostgreSQL and Keycloak, with the `dodossh` realm imported:
```bash
docker compose -f deploy/docker-compose.dev.yml up -d
```
**2. The schema.** The API never migrates anything: it fails readiness while a migration is pending, and
says which one. `dotnet-ef` is pinned in `.config/dotnet-tools.json`, so run `dotnet tool restore` first if
you have not:
```bash
dotnet ef database update --project src/DodoSSH.Infrastructure
```
With nothing else configured this targets the compose stack above. Set `DODOSSH_DESIGN_CONNECTION` to point
it at another database.
**3. The server:**
```bash
dotnet run --project src/DodoSSH.Api
@@ -87,6 +108,22 @@ dotnet run --project src/DodoSSH.Api
It listens on `http://localhost:5233`, serving `/healthz/live`, `/healthz/ready` and — in
Development — `/openapi/v1.json`.
**4. The desktop client:**
```bash
dotnet run --project src/DodoSSH.Client.App
```
In the app, enter `http://localhost:5233` as the server. Your browser opens for sign-in — the realm ships
`alice` / `alice` — then choose a vault passphrase and **write down the recovery code**, which cannot be
skipped and cannot be recovered from the server. You can then add a host and open a shell on it. Keycloak's
admin console is at `http://localhost:18080` (`admin` / `admin`).
Three of M1's known gaps are visible immediately, so they are worth expecting rather than diagnosing: a
connection asks for the host's password every time, because credentials are not a synced entity type yet;
host key trust lasts one session, because known hosts do not live in the vault yet; and unlock asks for the
passphrase on every launch, because no device key is registered.
### End-to-end verification
One suite runs against a real server rather than a stub. It needs a Docker daemon and nothing else, so it