Guidance for picking a listening port that won't collide on a shared-host
fleet: use the registered range (1024-49151), avoid the crowded alt-HTTP
cluster (3000/5000/8000/8080/8081/8443/9000...) and never the ephemeral range
(49152+, kernel source ports), derive from the service name into a sparse band,
and — the actual anti-collision mechanism — record every allocation in a fleet
registry. Seeds the registry with the services documented across this repo
(pg, neuron, bench, gongfoo controller/agent, cortex) plus newsfeed-api.
Motivated by newsfeed-api having been put on 8081 (the alt-HTTP port). Linked
from generic.md §9.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016fKZzDpvjiJ9eYbPGgJvUP
Document the gongfoo-managed runner images (labels, lineage, toolchains,
CPU/MEM), how `runs-on:` label matching selects one, which runner to pick for
each job type, and how to add/extend an image instead of installing packages
at workflow run time.
Captures the traps that cost a run: `fedora-*` has no cargo (use `rust`); the
base fedora images ship rsync but no ssh client (deploy jobs use `infra`);
`corepack` isn't bundled — pnpm is preinstalled via npm, call it directly.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016fKZzDpvjiJ9eYbPGgJvUP
Capture the cert + edge-proxy conventions worked through deploying the
helexa-bench UI:
- external-tls.md — publicly-trusted certs via Let's Encrypt (certbot,
Cloudflare DNS-01, ECDSA, /root/.certbot-internal); the external
counterpart to internal-tls.md. Decision rule: public name → LE,
*.internal → internal CA.
- reverse-proxies.md — names the per-site edge proxies (oolon for
kosherinata, hanzalova.internal for the office) and what sits behind
each, the public-vs-mesh access paths + the "public names don't
hairpin from inside the mesh" gotcha, per-vhost cert choice, nginx
conventions, and the bench (bench.helexa.ai + bench.internal) worked
example.
- readme + generic.md §11 cross-reference both.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add two new guidance documents alongside generic.md:
- deployment-gitea-actions.md: CI-driven deployment via a Gitea Actions
workflow as an alternative to deploy.sh + manifest.yml (§7), with the
workflow as the source of infra truth and a scoped gitea_ci runner user.
- internal-tls.md: provisioning and renewing per-service internal TLS
certs (<service>.internal) for mesh-only nginx vhosts, extending the
PKI conventions in §11.
Cross-reference both from generic.md and list them in readme.md. Also
add a "never suppress errors" rule to the deploy-script conventions.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add guidance in generic.md §12 that readme files (and other conventional
top-level docs: license, changelog, contributing) should be named in
lowercase, not shouty all-caps. Update all README.md references in
generic.md and rename this repo's own README.md to match.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
