diff --git a/SCOPE.md b/SCOPE.md index d48e39a..3fbe07a 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -1,137 +1,200 @@ # SCOPE -> This file helps you quickly understand what this repository is about, -> when it is relevant, and when it is not. -> It is intentionally lightweight and may be incomplete. +This file defines what `ihp-railiance-probe` owns, when to use it, and where +its boundaries stop. + +Last reviewed: 2026-06-04 --- ## One-liner - - +A minimal IHP-on-Railiance canary application that proves the full path from +Nix production build to Gitea OCI image, Helm deployment on Railiance01, and +live HTTP smoke verification. --- ## Core Idea - - +`ihp-railiance-probe` is intentionally small. It exists to make expensive +IHP/GHC/Nix/deployment failures cheap to reproduce before larger applications +such as `inter-hub` rely on the same path. + +The repo owns a tiny IHP app, the production build shape, a Helm deployment +chart, and the evidence trail for end-to-end validation. Its value is not +business functionality; its value is proving that the IHP workload pipeline is +healthy enough for real apps to use. --- ## In Scope - - - -- -- -- +- Minimal IHP application code: + - `Web/Controller/Health.hs` for `GET /healthz -> ok`; + - `Web/Controller/Probes.hs` for basic `probes` CRUD; + - routes, views, schema, and fixtures needed for the small probe surface. +- Minimal database schema in `Application/Schema.sql`: + - `uuid-ossp` extension; + - one `probes` table with `id`, `name`, and `created_at`. +- Test-first validation surface: + - `Test/ProbeControllerSpec.hs`; + - `Test/Main.hs`; + - Hspec checks for `/probes` and `/healthz`. +- IHP/Nix production build configuration: + - `flake.nix`; + - IHP v1.5 inputs; + - `nix build .#docker`; + - low-memory GHC runtime settings and the GHC 9.10.3 mitigation overlay. +- Kubernetes deployment artifact: + - Helm chart under `chart/`; + - deployment, service, ingress, image settings, resource limits, and + `/healthz` liveness probe. +- Pipeline documentation and evidence: + - `INTENT.md`; + - `DeploymentBlueprint.md`; + - `PIPELINE_LOG.md`; + - completed workplan `workplans/IRP-WP-0001-pipeline-validation.md`. --- ## Out of Scope - - - -- -- -- +- Production business functionality. This is a probe, not an application + product. +- `inter-hub` source code, domain model, features, or release ownership. +- Generic IHP framework maintenance. +- Railiance OS provisioning, Kubernetes runtime setup, and shared platform + services. +- Long-term ownership of Gitea, registries, PostgreSQL, ingress controllers, or + k3s cluster configuration. +- Secret custody. The chart references an environment Secret name, but this + repo must not store live secret values. +- A general-purpose application template. Lessons may inform templates + elsewhere, but this repo stays a small validation target. --- ## Relevant When - - -- -- -- +- Validating that an IHP project can build a production OCI image with the + current Nix/IHP/GHC stack. +- Checking whether known GHC 9.10.3 production-build mitigations still work. +- Proving the Gitea container registry push path for an IHP image. +- Testing that Railiance01 can pull and run the image from the Gitea registry. +- Verifying Helm deployment, service routing, ingress, and `/healthz` behavior + for an IHP workload. +- Rehearsing the path before promoting a larger IHP app. --- ## Not Relevant When - - -- -- -- +- You need application features or user-facing product behavior. +- You need to debug the internals of `inter-hub`. +- You are provisioning hosts, installing k3s, or managing cluster-level addons. +- You are designing shared Railiance platform services such as databases, + secret management, object storage, or caches. +- You need a durable production service with real data and recovery guarantees. +- You need canonical CI/CD or developer enablement templates rather than this + specific probe implementation. --- ## Current State - +- Status: validated canary. +- Implementation: minimal IHP app, schema, health endpoint, probe CRUD, tests, + Nix Docker image build config, Helm chart, deployment blueprint, and pipeline + log are present. +- Stability: suitable as a regression probe; intentionally narrow. +- Usage: two end-to-end pipeline runs are recorded in `PIPELINE_LOG.md` + (`e372a0c` on 2026-05-03 and `511a503` on 2026-05-07), both with build, + push, deploy, and smoke marked PASS. -- Status: -- Implementation: -- Stability: -- Usage: - - +The completed workplan records Gitea Actions automation as done, but the +repository surface visible here does not currently include a +`.gitea/workflows/` file. Treat that as a documentation/state gap to verify +before relying on unattended CI. --- ## How It Fits - - - Upstream dependencies: + IHP v1.5, GHC 9.10.3, Nix/devenv, haskelseed build host, Gitea OCI registry, + Railiance01/k3s, Helm, and a PostgreSQL-compatible `DATABASE_URL`. - Downstream consumers: + humans and agents validating the IHP-on-Railiance release path; larger IHP + applications that want confidence before promotion. - Often used with: + `inter-hub`, `railiance-apps`, `railiance-enablement`, Gitea on CoulombCore, + and Railiance01. --- ## Terminology - - - - Preferred terms: + probe, canary, pipeline validation, smoke test, IHP-on-Railiance. - Also known as: + IHP deployment probe, Railiance IHP canary. - Potentially confusing terms: + this repo is "upstream in confidence" from `inter-hub`, not a source-code + dependency of it. --- ## Related / Overlapping Repositories - - - -- — +- `inter-hub` - the larger IHP workload whose expensive build/deployment + failures motivated this small probe. +- `railiance-apps` - owns S5 application release patterns and app workload + operations for Railiance; this repo is a source workload used to validate an + IHP path into that layer. +- `railiance-enablement` - eventual home for reusable CI/CD, templates, and + developer delivery paths that this probe may inform. +- `railiance-cluster` - owns Kubernetes runtime concerns such as k3s and + cluster-level registry configuration. +- `railiance-platform` - owns shared stateful services such as databases and + secrets consumed by workloads. --- ## Getting Oriented - - -- Start with: -- Key files / directories: -- Entry points: +1. Read `INTENT.md` to understand why the repo exists. +2. Read `DeploymentBlueprint.md` for the full workstation -> haskelseed -> + Gitea registry -> Railiance01 flow. +3. Read `PIPELINE_LOG.md` for recorded successful pipeline runs. +4. Inspect `flake.nix` for the production image build and GHC mitigations. +5. Inspect `chart/` for Kubernetes deployment shape. +6. Inspect `Web/Controller/Health.hs`, `Web/Controller/Probes.hs`, and + `Test/ProbeControllerSpec.hs` for the app and smoke-test surface. +7. Inspect `workplans/IRP-WP-0001-pipeline-validation.md` for the completed + validation sequence and operational caveats. --- ## Provided Capabilities - - - - - --- ## Notes - +The README still looks like the original seed template. Use `INTENT.md`, +`DeploymentBlueprint.md`, and this file as the current orientation documents.