Files
aevolution/deploy/README.md
T

111 lines
6.0 KiB
Markdown

# Build and dev delivery
The maintainer has configured Gitea, Harbor and Argo. Gitea run
[1399](https://git.aeternalisgames.com/dingo/AEvolution/actions/runs/1399)
successfully built, tested and published commit `8ab48d3`. This repository adds
broader checks and a bounded **stateless proof Job**. It is not a region server.
Cluster execution must be recorded separately from image publication.
The expanded [run 1402](https://git.aeternalisgames.com/dingo/AEvolution/actions/runs/1402)
passed all checks and published `4c2cc04`. The dev Kustomize manifest already pins
that verified image digest. Argo bootstrap examples still need the actual
application namespace and destination; do not apply examples unchanged.
## Gitea and Harbor
The single workflow is `.gitea/workflows/build.yaml`. The existing runner label
is `ubuntu-22.04`; this does not imply its compiler version. Checks use explicit
Ubuntu 24.04 Docker stages with GCC14 and LLVM19. The runner needs Git, Node20 for
checkout, Bash and a working Docker builder.
| Setting | Kind | Value / purpose |
|---|---|---|
| HARBOR_HOST | Existing variable | registry.aeternalisgames.com; publishing is scoped to this host |
| HARBOR_PROJECT | Existing variable | aeternalis |
| HARBOR_USERNAME / HARBOR_PASSWORD | Existing secrets | Harbor push robot; values never belong in Git |
| HARBOR_REPOSITORY | Optional variable | Defaults to aevolution |
| CI_RUNNER_LABEL | Optional variable | Defaults to the verified ubuntu-22.04 label |
| UBUNTU_IMAGE | Optional variable | Defaults to ubuntu:24.04; prefer a reviewed base digest |
Checks include Debug/Release CTest, format, clang-tidy, ASan/UBSan, a million
synthetic ticks and bounded seeded libFuzzer. TSan runs separately. No failure
is ignored. Windows MSVC checks use `tools/windows-check.ps1`. The image job waits
for checks and executes a restricted runtime smoke test. Only main push/manual
runs publish, using a temporary Docker credential directory.
Published tags use `sha-<commit>-run-<run-number>-<attempt>` to distinguish rebuilds.
This replaces the original commit-only tag convention. The job prints the
registry digest in its logs/summary. GitOps references the digest, never latest.
CI does not receive cluster credentials or automatically commit/sync GitOps.
Use isolated runners for untrusted pull requests; Docker access is privileged.
## Local container checks
```sh
docker build --progress=plain -f deploy/docker/Dockerfile --target ci-checks .
docker build --progress=plain -f deploy/docker/Dockerfile --target ci-tsan .
docker build -f deploy/docker/Dockerfile -t aeternalis-evo:dev .
docker run --rm --network none --read-only --cap-drop ALL \
--security-opt no-new-privileges aeternalis-evo:dev \
--seed 123456 --entities 8 --ticks 1000 --verify-replay
```
Runtime UID/GID is 10001; JSON goes to stdout. Builder package versions are in
`/usr/share/evo/build-packages.txt`; file output needs an explicit writable mount.
Source COPY operations exclude local chat logs, `.git` and credentials. Ubuntu
security packages move: production promotion still needs pinned provenance,
SBOM, scan/signature and retention. TSan on this sequential proof validates
instrumentation, not future concurrency. Record actual results in VALIDATION.md.
## Argo settings and promotion
Reuse the maintainer's application once its GitOps source is confirmed. For an
application watching this repository directly:
| Field | Value |
|---|---|
| Repository | https://git.aeternalisgames.com/dingo/AEvolution.git |
| Revision | main; review the resolved commit before syncing |
| Path | deploy/kubernetes/dev |
| Destination namespace | evolution-dev |
| Project | aevolution-dev, or an equivalently restricted project |
| Sync | Manual full sync; no automated prune/self-heal |
Bootstrap examples in `deploy/argocd/*.yaml.example` are outside the workload
path. Replace the Argo namespace and registered cluster API URL, or use its UI.
Create evolution-dev separately. Configure Argo's private Git read credential
and a **pull-only** harbor-pull Secret in that namespace. Neither is the CI push
credential. The project allows only Job, ServiceAccount and NetworkPolicy there.
Before syncing:
1. Wait for successful checks and publication of the intended commit.
2. Update `deploy/kubernetes/dev/kustomization.yaml` to the published
`sha256:<64 hex>` digest, review and commit it. It currently pins run 1402;
no floating tag or fallback image is used.
3. Run `kubectl kustomize deploy/kubernetes/dev`. Check exactly three resources,
all in evolution-dev, the selected digest and no unresolved marker.
4. Full-sync the dev app. Selective sync skips hooks.
5. Verify Job aevolution-dev-proof completes with exit 0 and JSON
`replay_verified: true`, seed 123456, 8 entities and 100000 ticks. Record the
digest, source commit and result in the validation report.
The Job has a five-minute deadline, no retries, token mount, network access or
writable root, and bounded resources. NetworkPolicy requires CNI enforcement;
node-level image pulling is separate from pod egress. No Service, port, PVC or
persistent world is included. BeforeHookCreation retains the latest Job until
the next full sync replaces it; collect logs first. Kubernetes can execute a Job
more than once: harmless here, not an exactly-once persistence mechanism.
World0 is unchanged. Persistent deployment follows
[infrastructure architecture](../docs/architecture/INFRASTRUCTURE_ARCHITECTURE.md)
and [operations gates](../docs/infrastructure/OPERATIONS.md).
TSan requires execution outside the Docker build sandbox on this runner. The
ci-tsan target now builds its tests; the Gitea workflow runs them in a non-root,
read-only, networkless container with tmpfs test-output directories. Its pinned
Moby seccomp profile adds only personality(0x40000). No host security settings
change. See ADR-0020 for the source, integrity hash and removal policy. Building
the ci-tsan image alone is NOT a TSan test pass; use the workflow's docker run
command with the generated profile to execute it locally.