ihp-railiance-probe/DeploymentBlueprint.md

# Deployment Blueprint — ihp-railiance-probe

Textual equivalent of a C4 Deployment Diagram covering the full
build-to-production cycle. Read top-to-bottom as the artifact flows through
each node.

---

## Deployment Nodes

### Node: Developer Workstation
- **Host**: `localhost` (WSL2 on Windows, `linux/x86_64`)
- **Role**: source editing, flake authoring, orchestration
- **Key tools**: git, sshpass, skopeo (client), nix (local, for dry-runs only)
- **Constraints**: not used for Haskell compilation — insufficient RAM for GHC
  on large module graphs

### Node: haskelseed (Build Server)
- **Host**: `192.168.178.135` (Alpine Linux VM, LAN-local to workstation)
- **SSH access**: `root` / `hcs26!x` (password) or via `ssh haskelseed` alias
- **Role**: sole Haskell compilation and `nix build` host
- **Resources**: 2 CPU, ~3.8 GiB RAM, 100 GB NVMe at `/nix` (`/dev/sdb1`)
- **Nix store**: `/nix/store` on dedicated volume; store paths survive reboots
- **Key constraint**: `libHSghc-9.10.3-5702.a` in the Nix store may be truncated
  (287 MB vs full 289 MB); must be patched before production builds if affected
  (see `inter-hub/HaskellVibePrimer.md` §Bug 2)
- **GHC version**: 9.10.3 (from IHP v1.5 flake)
- **GHCRTS**: `-A32m -M2g` (heap ceiling to prevent OOM)

### Node: CoulombCore VPS (Registry + Gitea)
- **Host**: `92.205.130.254`
- **SSH access**: `tegwick` via `id_ops` key (alias `coulombcore`)
- **Role**: Gitea source hosting + built-in OCI container registry
- **Gitea SSH**: port `30022`, alias `gitea-remote` in `~/.ssh/config`
- **Registry endpoint**: `92.205.130.254:32166` (HTTP, no TLS — internal use)
- **Image namespace**: `coulomb/ihp-railiance-probe`
- **Registry auth**: Gitea credentials (same user as Gitea login)

### Node: Railiance01 (Production Cluster)
- **Host**: `92.205.62.239`
- **SSH access**: `tegwick` via `id_custodian_agent` key (alias `railiance01`)
- **Role**: k3s Kubernetes cluster, deployment target
- **Namespace**: `coulomb` (shared with inter-hub)
- **Image pull**: cluster pulls from `92.205.130.254:32166` (LAN-adjacent VPS,
  no auth needed if registry is public or cluster has credentials configured)
- **Ingress**: Traefik (k3s default); routes via IngressRoute or Ingress manifest

---

## Deployment Pipeline — Step by Step

```
[Workstation]
    │
    │  git push (SSH via gitea-remote)
    ▼
[CoulombCore — Gitea]
    │
    │  (no CI yet; developer triggers manually)
    │
    ▼
[Workstation]
    │
    │  scp flake.nix + source → haskelseed
    │  (or: git push + git pull on haskelseed)
    ▼
[haskelseed — Build]
    │  nix build .#docker
    │    → evaluates flake.nix
    │    → builds inter-hub-models (GHC, 477 modules)  ← cached after first build
    │    → builds inter-hub-lib   (GHC, 199 modules)
    │    → builds inter-hub-binaries
    │    → assembles OCI tarball  (result → /root/ihp-railiance-probe/result)
    │
    │  # Gitea's registry token realm points to port 80; skopeo must use a
    │  # pre-fetched token to avoid following that misconfigured URL.
    │  TOKEN=$(curl -s \
    │    "http://92.205.130.254:32166/v2/token?service=container_registry\
    │&scope=repository:coulomb/<APP>:push,pull" \
    │    -u 'tegwick:<GITEA_API_KEY>' | awk -F'"' '/token/{print $4}')
    │  skopeo copy --insecure-policy --dest-tls-verify=false \
    │    --dest-registry-token "$TOKEN" \
    │    docker-archive:result \
    │    docker://92.205.130.254:32166/coulomb/<APP>:<SHA>
    ▼
[CoulombCore — Registry]
    │  image stored as coulomb/ihp-railiance-probe:<SHA>
    │
    ▼
[Railiance01 — Kubernetes / k3s]
    │  helm upgrade --install ihp-railiance-probe ./chart
    │    --set image.tag=<SHA>
    │    --namespace coulomb
    │
    │  k3s pulls image from 92.205.130.254:32166
    │  Deployment → ReplicaSet → Pod (RunProdServer binary)
    │  Service (ClusterIP) → IngressRoute (Traefik)
    ▼
[External / Browser]
    GET https://probe.railiance.example/
```

---

## Container: ihp-railiance-probe Application

- **Base**: IHP unoptimized Docker image (`config.packages.unoptimized-docker-image`)
- **Entry point**: `/bin/RunProdServer`
- **Exposed port**: `8000` (IHP default)
- **Environment variables** (injected via Kubernetes Secret / ConfigMap):

| Variable | Purpose |
|----------|---------|
| `IHP_SESSION_SECRET` | Session encryption key (32+ random bytes, base64) |
| `DATABASE_URL` | PostgreSQL connection string |
| `IHP_BASEURL` | External URL shown in links (e.g. `https://probe.coulomb.example`) |

- **PostgreSQL**: deployed as a separate pod (`bitnami/postgresql`) or uses the
  shared CoulombCore postgres — TBD per cluster capacity

---

## Artifact Versioning

| Artifact | Identifier | Retention |
|----------|------------|-----------|
| Git commit | `<SHA>` (short, from `git rev-parse --short HEAD`) | permanent in Gitea |
| OCI image | `coulomb/ihp-railiance-probe:<SHA>` | keep last 5 tags |
| Helm release | `ihp-railiance-probe` in namespace `coulomb` | single release, upgraded in-place |
| Nix build result | `/root/ihp-railiance-probe/result` symlink on haskelseed | GC'd by `nix store gc` |

---

## Known Infrastructure Constraints

| Constraint | Impact | Mitigation |
|------------|--------|------------|
| haskelseed 2 CPU / 3.8 GB RAM | Full GHC build saturates RAM | `GHCRTS=-A32m -M2g`; `-j1` in flake |
| GHC 9.10.3 `.hi` overflow (>274 MB) | Crash after all modules compile | ActualTypes postUnpack overlay in flake.nix |
| GHC 9.10.3 `libHSghc.a` truncated | Crash at position 287,686,318 | Direct archive patch on haskelseed (one-time; check after flake lock update) |
| Registry on HTTP (no TLS) | k3s defaults to HTTPS for pulls | Configure k3s `registries.yaml` with mirror entry for `92.205.130.254:32166` |
| Gitea registry token realm misconfigured | `Bearer realm` points to `gitea.coulomb.social:80` but Gitea is on port 32166; skopeo follows the realm URL and gets 404 | Pre-fetch token via `curl` against port 32166 and pass with `--dest-registry-token`; do NOT rely on skopeo's automatic token fetch |
| No CI runner yet | Manual build + push | Phase 6 of workplan adds Gitea Actions runner on haskelseed |

---

## Key File Locations

| File | Node | Path |
|------|------|------|
| Nix flake | Workstation + haskelseed | `flake.nix` |
| Helm chart | Workstation | `chart/` |
| GHC archive (may be truncated) | haskelseed | `/nix/store/ffg3yf2ypnbz3hc31y7nglrkihz0if01-ghc-9.10.3/lib/ghc-9.10.3/lib/x86_64-linux-ghc-9.10.3/ghc-9.10.3-5702/libHSghc-9.10.3-5702.a` |
| Build log | haskelseed | `/tmp/build<N>.log` |
| k3s registries config | Railiance01 | `/etc/rancher/k3s/registries.yaml` |