Local compose

Run Render, Mail, and Flow together for a golden path: Flow → Render → (file or Mail).

SMTP is bring-your-own (external provider). There is no SMTP container in Compose.

Docker Compose (recommended)

From the suite root (sibling checkouts of Render, Mail, Flow):

cp .env.example .env
# Edit .env: Jwt__Key (32+ chars), SmtpSettings__* (Host/Username/Password required
# for Mail to start — use your real provider for delivery), optional FLOW_MAIL_API_KEY
docker compose up --build

Service	Host port	Notes
Render	:5066	Security__RequireLocalRequests=false so Flow can call it on the compose network
Mail	:5026	SQLite volume; SMTP from .env
Flow	:5077	Points at http://render:5066 and http://mail:5026
mail-web	:5173	Optional: docker compose --profile ui up --build

Files at the suite checkout root (not in this docs repo): docker-compose.yml, docker/, .env.example, scripts/compose-e2e.sh.

Automated smoke (same golden path) lives in OxyKit.Flow CI: workflow Compose E2E materializes sibling Render/Mail checkouts from deploy/compose/. Locally from suite root:

./scripts/compose-e2e.sh          # starts compose if needed; file + mail accept
START_COMPOSE=0 RUN_MAIL=0 ./scripts/compose-e2e.sh   # file-only against an already-up stack

After first up

1. Confirm health: GET http://localhost:5066/health, http://localhost:5026/health, http://localhost:5077/health
   (Mail /health may be Unhealthy/503 if SMTP is wrong or down — API still runs; send can queue as accepted.)
2. File smoke (no Mail key): Flow Hoppscotch folder Jobs — file (needs Render).
3. Bootstrap Mail if needed: GET /api/v1/setup/needs-admin, then create admin; create a Sender (or Admin) API key.
4. Set FLOW_MAIL_API_KEY in .env to that key and restart Flow (docker compose up -d flow).
   Until then, mail output jobs fail at delivery (empty OxyKit.Mail:ApiKey).
5. Mail smoke: Flow Hoppscotch Jobs — mail (set env mailTo; needs Render + Mail + step 4).

Without Docker (three terminals)

# 1. Render
cd OxyKit.Render && dotnet run --project src/OxyKit.Render.Api
# http://localhost:5066 — X-OxyKit-Render-Key: dev-local-key

# 2. Mail (solution-root .env with SMTP + JWT — see Mail README)
cd OxyKit.Mail && dotnet run --project src/OxyKit.Mail/OxyKit.Mail.csproj
# http://localhost:5026

# 3. Flow
cd OxyKit.Flow && dotnet run --project src/OxyKit.Flow/OxyKit.Flow.csproj
# http://localhost:5077 — configure Render:Engines + OxyKit.Mail in appsettings/env

Golden path checklist

1. Render healthy on :5066
2. Flow on :5077 → Hoppscotch Jobs — file (or POST /api/v1/jobs with file output)
3. Mail reachable on :5026 (SMTP may be Unhealthy)
4. FLOW_MAIL_API_KEY set + Flow restarted → Hoppscotch Jobs — mail
5. Poll job until Completed (or inspect deliveries / DeadLettered if key/SMTP wrong)

Smoke without writing a client

Import each product’s hoppscotch/ collection + Local environment, select the Local env, run folders top to bottom. Do not paste collection JSON into issues or chats — keep files in-repo.

Product	Env display name	Port
Render	OxyKit.Render Local	5066
Mail	OxyKit.Mail Local	5026
Flow	OxyKit.Flow Local	5077

OpenAPI / Scalar

With ASPNETCORE_ENVIRONMENT=Development (default for dotnet run in Dev). Compose images run Production (Scalar off unless you override the env).

Service	Scalar (Dev)	OpenAPI JSON
Render	http://localhost:5066/scalar	/openapi/v1.json
Mail	http://localhost:5026/scalar	/openapi/v1.json
Flow	http://localhost:5077/scalar	/openapi/v1.json

Live documents are authoritative — this site does not mirror endpoint catalogs.