mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-07 19:32:17 +00:00
kevinveenbirkenbachandClaude Opus 4.7
13c93ad6d5
compose.yml no longer hides services behind \`profiles: ["ci"]\`. The profile existed solely as a no-op safety net against a bare \`docker compose up\` in the repo root, but the top-level compose.yml is already explicitly scoped to local dev / CI testing (production goes through the Ansible roles under roles/<role>/templates/), so the safety net is redundant with the documented scope. Every \`--profile ci\` callsite collapses: - compose.yml: \`profiles: ["ci"]\` removed from coredns + infinito - Profile.args() deleted; Profile keeps is_ci() and registry_cache_active() for the cache-override gating - compose.py / down.py: profile.args() splat removed from the docker-compose command builder; down.py drops its now-unused Profile import - 5 shell wrappers (install, lint, tests/code, meta/resolve/apps, meta/resolve/diff/affected_roles): plain \`docker compose\` instead of \`docker compose --profile ci\` - tests/unit/.../test_profile.py: TestProfileArgs class removed - tests/unit/.../test_compose.py: two cmd-shape asserts updated to reflect the missing --profile pair Docs: - docs/contributing/artefact/files/compose.yml.md: the \"every service MUST be behind a profiles: entry\" rule is gone - docs/contributing/actions/debugging/ci.md: the \`docker compose ... --profile ci config\` debug snippet drops the flag; while touching the file the two em-dash clause separators in the reproduction-profiles shell block are rewritten to colons (documentation.md em-dash rule), and one list-item in compose.yml.md is collapsed to one sentence per line for consistency with its siblings Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
69 lines
4.0 KiB
Markdown
69 lines
4.0 KiB
Markdown
# CI Failures and Debugging 🐛
|
||
|
||
If CI fails, follow a clean debugging workflow:
|
||
|
||
1. Export the raw failing logs.
|
||
2. Save them locally as `job-logs.txt`.
|
||
3. Decide whether the failure belongs to your branch or to something unrelated.
|
||
4. Fix related failures in the same branch.
|
||
5. Open an issue for unrelated failures instead of mixing them into your branch.
|
||
|
||
## Important 🚨
|
||
|
||
- You MUST NOT debug from screenshots alone. Use raw logs.
|
||
- You MUST NOT commit log files to the repository.
|
||
- If a [Playwright](https://playwright.dev/) job fails, you MUST also download the Playwright assets, store them in `/tmp/`, and analyze them together with the logs.
|
||
|
||
## Manual CI Jobs 🎯
|
||
|
||
You SHOULD use targeted manual CI jobs instead of rerunning the full pipeline if you only need one focused check.
|
||
|
||
Prefer the manual workflow in [entry-manual.yml](../../../../.github/workflows/entry-manual.yml):
|
||
|
||
- Select your branch.
|
||
- Use `debian` unless you have a clear reason to use a different distro.
|
||
- Limit the run to the affected app when possible.
|
||
|
||
This gives faster feedback and protects shared CI runners.
|
||
|
||
More information [here](https://hub.infinito.nexus/t/infinito-nexus-ci-cd-debugging-guide/462).
|
||
|
||
## Reproducing Runner Resource Limits Locally 💾
|
||
|
||
Some CI failures (most notably OOM-kills such as [#162](https://github.com/infinito-nexus/core/issues/162), PeerTube plugin install with `rc=137`) only surface under the memory and CPU ceiling of the GitHub-hosted runner and cannot be reproduced on a workstation with plenty of RAM. To reproduce these failures locally, you MUST cap the resources of the top-level `infinito` service in [compose.yml](../../../../compose.yml) to values that match (or undercut) the runner specs below.
|
||
|
||
### GitHub-Hosted Runner Specs
|
||
|
||
All [workflows](../../../../.github/workflows/) target `runs-on: ubuntu-latest`, which maps to the GitHub-hosted standard Linux runner. The effective ceiling depends on the repository's visibility and plan:
|
||
|
||
| Repository / plan | vCPU | RAM | SSD |
|
||
|------------------------------------------|------|--------|-------|
|
||
| Public repo (this repo, `ubuntu-latest`) | 4 | 16 GB | 14 GB |
|
||
| Private repo on Free / Pro / Team | 2 | 7 GB | 14 GB |
|
||
| Private repo on Enterprise | 4 | 16 GB | 14 GB |
|
||
|
||
The effective budget for the actual workload is lower than the table suggests because the runner itself plus the nested `infinito` container (systemd, nested Docker, Ansible) reserve a non-trivial baseline. Plan for roughly **1–2 GB of overhead** before any role deploys a service.
|
||
|
||
For the authoritative specs, see the upstream docs for [standard hosted runners](https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories) and [larger runners](https://docs.github.com/en/actions/using-github-hosted-runners/using-larger-runners).
|
||
|
||
### Env-Var Knobs
|
||
|
||
[compose.yml](../../../../compose.yml) exposes three env vars on the `infinito` service that cap its memory, swap, and CPU ceiling. For the authoritative variable reference (names, defaults, purpose) see the SPOT in [compose.yml.md](../../artefact/files/compose.yml.md). This page SHOULD NOT duplicate that table and MUST link back to it when a contributor needs the precise definitions.
|
||
|
||
### Canonical Reproduction Profiles
|
||
|
||
Pick the profile that matches the runner you want to mimic:
|
||
|
||
```sh
|
||
# Public repo runner (ubuntu-latest, 4 vCPU / 16 GB): the default CI target
|
||
INFINITO_MEM_LIMIT=16g INFINITO_MEMSWAP_LIMIT=16g INFINITO_CPUS=4 make <target>
|
||
|
||
# Private repo runner on Free/Pro/Team (2 vCPU / 7 GB)
|
||
INFINITO_MEM_LIMIT=7g INFINITO_MEMSWAP_LIMIT=7g INFINITO_CPUS=2 make <target>
|
||
|
||
# Aggressive OOM reproducer: forces the memory spike that surfaces #162
|
||
INFINITO_MEM_LIMIT=4g INFINITO_MEMSWAP_LIMIT=4g INFINITO_CPUS=2 make <target>
|
||
```
|
||
|
||
Verify the caps applied with `docker compose -f compose.yml config | grep -E 'mem_limit|memswap_limit|cpus'` before starting the deploy.
|