coulomb/ihp-railiance-probe
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document probe scope
Some checks failed
Build and Deploy / build-push-deploy (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Bernd Worsch
2026-06-05 00:56:34 +02:00
parent 537a1d6673
commit b74a501e7c
1 changed files with 124 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

185
SCOPE.md
View File

@@ -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
<!-- Describe the purpose of this repository in one precise sentence. -->
<!-- Example: "Provides a lightweight event router for Kubernetes-native systems." -->
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
<!-- What is the main capability or idea behind this repository? -->
<!-- What problem does it try to solve? -->
`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
<!-- What this repository is responsible for. -->
<!-- Be explicit and concrete. -->
-
-
-
- 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
<!-- What this repository deliberately does NOT do. -->
<!-- This is often more important than "In 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
<!-- When should someone consider using or exploring this repository? -->
-
-
-
- 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
<!-- When should someone ignore this repository? -->
-
-
-
- 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
<!-- Rough indication of maturity. No strict format required. -->
- 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: <!-- e.g. concept / experimental / active / stable / deprecated -->
- Implementation: <!-- e.g. idea / partial / substantial / complete -->
- Stability: <!-- e.g. unstable / evolving / stable -->
- Usage: <!-- e.g. none / personal / internal / production -->
<!-- Add any notes that help set expectations. -->
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
<!-- Where does this repository sit in the bigger picture? -->
- 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
<!-- Terms that are important to understand this repo. -->
<!-- Especially useful if naming differs from other repos. -->
- 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
<!-- List repositories that have similar or adjacent responsibilities. -->
<!-- Helps detect duplication and navigate the ecosystem. -->
- <repo-name> — <!-- how it relates -->
- `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
<!-- If someone decides to look deeper, where should they start? -->
- 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
<!-- What can this repo's domain provide to other domains on request? -->
<!-- Each capability block is parsed by the state-hub capability catalog ingest. -->
<!-- Remove the examples and add your own, or leave empty if none. -->
<!--
```capability
type: infrastructure
title: Example capability title
description: What this capability provides, in one or two sentences.
keywords: [keyword1, keyword2, keyword3]
type: validation
title: IHP-on-Railiance pipeline canary
description: Minimal IHP application used to validate Nix production builds, Gitea OCI registry push, Helm deployment on Railiance01, and live HTTP smoke checks before larger IHP workloads are promoted.
keywords: [ihp, railiance, probe, canary, nix, ghc, gitea, helm, kubernetes, smoke-test]
```
```capability
type: documentation
title: IHP deployment blueprint and evidence log
description: Documents the full IHP build-to-deploy path, known infrastructure constraints, and recorded end-to-end pipeline smoke evidence.
keywords: [deployment-blueprint, pipeline-log, haskelseed, railiance01, registry, evidence]
```
-->
---
## Notes
<!-- Anything else worth knowing. Keep it short. -->
The README still looks like the original seed template. Use `INTENT.md`,
`DeploymentBlueprint.md`, and this file as the current orientation documents.