orca/.ciagent/RESEARCH_v0.5.md

Research: Orca v0.5 — Distribution

Research findings for the v0.5 Distribution milestone (install, namespace, docker, public releases). Conducted during P0 RESEARCH under full autonomy.

R-001: Gitea Container Registry

Source: https://docs.gitea.com/usage/packages/container (Gitea 1.27.1 docs)

Findings:

• Gitea ships a built-in OCI-compliant container registry.
• Image naming convention: {registry}/{owner}/{image}:{tag}. For orca: git.cloudinit.dev/coreci/orca:{tag}.
• Auth: docker login git.cloudinit.dev with username + personal access token (or password if no 2FA). The GITEA_TOKEN env var already used for release publishing works as the password.
• Push: docker push git.cloudinit.dev/coreci/orca:v0.4.4.
• Pull: anonymous pull works if the repo is public (REQ-045 flips this). For private repos, pull requires auth.
• Tags are case-insensitive — use lowercase image names.
• The registry supports multi-arch manifests via docker buildx.

Implication for P03: scripts/release.sh must add a docker build

• docker login + docker push step. The .coreci.yml release pipeline needs a container-publish step. Credential is GITEA_TOKEN (reused from the existing release flow — no new secret needed).

R-002: tea repos edit — Repo Visibility

Source: tea repos edit --help (tea 0.14.1 installed locally)

Findings:

• Command: tea repos edit --private false --repo coreci/orca
• The --private flag accepts true/false (string, not bool).
• Default login bot (cloudinit-bot) is already configured and is the default login. No extra auth needed.
• The change is immediate and reversible (re-run with --private true).

Implication for P0 ship: Run this as an operational step during the P0 ship. Verify with unauth curl against the releases API afterward.

R-003: Gitea Releases API — Asset Download URLs

Source: /api/v1/repos/coreci/orca/releases/latest (authed probe)

Findings:

• Auth header format: Authorization: token <GITEA_TOKEN> (NOT basic auth — basic auth returns "invalid username, password or token").
• Latest release endpoint: GET /api/v1/repos/coreci/orca/releases/latest → JSON with tag_name, name, body, assets[].
• Each asset has browser_download_url — the direct download URL.
• Public access: once the repo is public (R-002), the releases API and asset downloads work without authentication. This is what install.sh relies on (REQ-043).
• Asset naming convention from existing releases: orca-{version}-linux-amd64.tar.gz (per scripts/release.sh).

Implication for P02 install.sh:

1. Query GET /api/v1/repos/coreci/orca/releases/latest (unauth, post-R-002).
2. Parse tag_name for the version.
3. Find the asset with name matching orca-{tag}-linux-{arch}.tar.gz.
4. Download browser_download_url with curl -fsSL.
5. Extract and install.

R-004: ORCA_HOME Propagation Points (Codebase Audit)

Source: grep for UserHomeDir|os.Getenv("ORCA|\.orca across *.go

Findings — exactly 3 production code sites determine the namespace root today:

File	Current behavior	Needs change?
internal/certpaths/certpaths.go:21-26	Dir() honors ORCA_HOME → ~/.orca	No — this is the single source of truth. Already correct.
internal/store/store.go:13-19	Open("") hardcodes ~/.orca/orca.db (ignores ORCA_HOME)	Yes — route through certpaths.DBPath() instead.
internal/cli/init.go:16-22	Hardcodes ~/.orca via os.UserHomeDir()	Yes — route through certpaths.Dir().

All other call sites (node.go:openDB, daemon.go, job.go, doctor.go, cert.go) already go through certpaths.DBPath() or certpaths.Dir() indirectly. No other files need changes for REQ-041.

For REQ-042 (--system): Add a --system persistent flag on rootCmd. When set, rootCmd.PersistentPreRunE sets os.Setenv("ORCA_HOME", "/root/.orca") before any subcommand runs. This is the minimal-touch approach — all downstream code already honors ORCA_HOME. The flag is a CLI convenience that maps to the env var, not a parallel mechanism.

Backward compatibility: empty ORCA_HOME + no --system → ~/.orca (unchanged). Existing tests that t.Setenv("ORCA_HOME", ...) continue to work.

R-005: Distroless Base Image for CGO-free Go Binaries

Source: Go module audit — modernc.org/sqlite (pure Go, CGO-free), go.mod has no CGO dependencies.

Findings:

• gcr.io/distroless/static-debian12 is the correct base for static Go binaries with no CGO and no libc dependency. ~2MB image.
• orca uses modernc.org/sqlite (pure Go) — no CGO, no libc. ✓
• Multi-stage Dockerfile:
  • Stage 1 (golang:1.25): build with -trimpath -ldflags (same as Makefile), output bin/orca.
  • Stage 2 (gcr.io/distroless/static-debian12): COPY bin/orca /orca, ENTRYPOINT ["/orca"].
• CGO_ENABLED=0 must be set in the build stage to guarantee a static binary (Go defaults to CGO_ENABLED=1 on platforms with a C compiler).
• The image runs as nonroot user by default in distroless — but orca writes to ~/.orca (or /root/.orca for --system). For the container image, default ORCA_HOME=/var/lib/orca and document volume mount at that path.

Implication for P03: Dockerfile is ~15 lines. The .coreci.yml release pipeline adds a docker build --build-arg VERSION=$VERSION -t git.cloudinit.dev/coreci/orca:$VERSION . step + login + push.

R-006: install.sh Conventions (curl|sh pattern)

Source: Common patterns from deno, rustup, homebrew installers.

Findings:

• 1-liner: curl -fsSL <url> | bash (or | bash -s -- --system).
• The script must be downloadable from a stable URL. orca's script lives at scripts/install.sh in the repo, accessible via https://git.cloudinit.dev/coreci/orca/raw/branch/main/scripts/install.sh (once repo is public per R-002).
• Args passed via bash -s -- --system --version v0.4.4.
• In-place update: detect existing binary at install path, read its version via orca version --json (parse version field), print "updated from X to Y", overwrite binary. Never touch the namespace dir (~/.orca or /root/.orca) — that's user state.
• User-level default: ~/.local/bin/orca (XDG-ish, on PATH on most modern distros). System-level: /usr/local/bin/orca (requires root).

Implication for P02: install.sh is ~80-100 lines of bash. Idempotent. Tested via a scripts/install_test.sh that mocks the download and verifies path selection + update-in-place.

Pitfalls (P-001..P-003)

• P-001: docker may not be available in the CoreCI release pipeline container. The .coreci.yml release step uses image: golang:1.25 which does NOT include docker. Mitigation: the release pipeline must use a docker:dind sidecar or a step image that has the docker CLI. Alternatively, scripts/release.sh handles docker publish only when run locally or in a CI step that has docker. The .coreci.yml container step must use an image with docker CLI (e.g., catthehacker/docker:docker-latest or a custom image).

• P-002: Making the repo public exposes git history including the pre-existing .env SHA-1 leak (commit 00127ce documented the rotate-forward decision; .gitleaks-baseline.json suppresses it for scanning). The leak is a non-secret (the token was rotated). This is an accepted risk per the existing decision — no new action needed, but document it in the P0 ship commit.

• P-003: CGO_ENABLED=0 must be explicit in the Dockerfile build stage. Without it, go build in golang:1.25 may produce a dynamically-linked binary that won't run in distroless. Verified: orca has no CGO deps, but CGO_ENABLED=0 is belt-and-suspenders.