---
milestone: v0.5
milestone_slug: distribution
type: feature
phase_count: 4
---

# Plan: Orca v0.5 — Distribution

Vertical-slice plan for the v0.5 Distribution milestone. Each phase is a
vertical slice that ships independently as a patch on the v0.4.x line.
The final phase (P4) is the milestone release (promoted to v0.5.0).

## Requirement → Phase Mapping

| REQ | Phase | Priority |
|-----|-------|----------|
| REQ-045 (public releases) | P0 ship (operational) | High |
| REQ-041 (ORCA_HOME unified namespace) | P1 | High |
| REQ-042 (--system flag) | P1 | High |
| REQ-043 (install.sh 1-liner) | P2 | High |
| REQ-044 (in-place update) | P2 | High |
| REQ-046 (docker release) | P3 | Medium |
| REQ-016 (README quickstart) | P2 | Medium (completion) |

## Phase 1 — Namespace Unification (REQ-041, REQ-042)

**Goal**: Single `ORCA_HOME` env var as namespace root for all
on-disk state; `--system` flag selects `/root/.orca`.

**Persona**: backend-engineer (store/certpaths routing) + cli-engineer
(`--system` flag).

**Wave 1** (single wave — no inter-task dependencies):

| Task | File(s) | Persona | REQ |
|------|---------|---------|-----|
| T1.1: Route `store.Open("")` through `certpaths.DBPath()` | `internal/store/store.go` | backend-engineer | REQ-041 |
| T1.2: Route `init` command through `certpaths.Dir()` | `internal/cli/init.go` | backend-engineer | REQ-041 |
| T1.3: Add `--system` persistent flag on `rootCmd` + `PersistentPreRunE` that sets `ORCA_HOME=/root/.orca` | `internal/cli/root.go` | cli-engineer | REQ-042 |
| T1.4: Add `namespace_test.go` covering user-level, `ORCA_HOME` override, `--system` | `internal/cli/namespace_test.go` | cli-engineer | REQ-041/042 |
| T1.5: Update `docs/namespace.md` (paths reference) | `docs/namespace.md` | backend-engineer | REQ-041 |

**Must-haves**:
- `go test ./...` passes (including new namespace_test.go).
- `ORCA_HOME=/tmp/x orca init` creates `/tmp/x` (not `~/.orca`).
- `orca --system init` creates `/root/.orca` (when run as root).
- Empty `ORCA_HOME` + no `--system` → `~/.orca` (backward compat).

**Verification**: 4-layer (structural: gofmt/vet; behavioral: namespace_test
+ existing doctor_test; security: no new secret surface; quality: no
regression in existing tests).

**Ship**: tag `v0.4.2`.

## Phase 2 — install.sh + In-Place Update (REQ-043, REQ-044, REQ-016)

**Goal**: 1-liner installer from public Gitea releases; idempotent
update-in-place; README quickstart.

**Persona**: devops-engineer.

**Wave 1**:

| Task | File(s) | Persona | REQ |
|------|---------|---------|-----|
| T2.1: Write `scripts/install.sh` (curl 1-liner, user/system, latest/pinned, in-place update) | `scripts/install.sh` | devops-engineer | REQ-043/044 |
| T2.2: Write `scripts/install_test.sh` (mocked download, path verification, update-in-place) | `scripts/install_test.sh` | devops-engineer | REQ-043/044 |
| T2.3: Update README quickstart with 1-liner install + `--system` variant | `README.md` | devops-engineer | REQ-016 |
| T2.4: Write `docs/install.md` (full install reference, troubleshooting, ORCA_HOME) | `docs/install.md` | devops-engineer | REQ-043 |

**install.sh spec** (per R-006):
- Default: user-level. Binary → `~/.local/bin/orca`. Namespace → `~/.orca`.
- `--system`: binary → `/usr/local/bin/orca`, namespace → `/root/.orca`. Requires root (uid 0).
- `--version vX.Y.Z`: pin version. Default: query `/api/v1/repos/coreci/orca/releases/latest`.
- Download `orca-{tag}-linux-{arch}.tar.gz` from the release asset.
- In-place update: if `orca` exists at install path, run `orca version --json`,
  parse `version`, print "updated from X to Y". Overwrite binary. **Never**
  touch the namespace dir.
- Detect arch: `amd64` (x86_64), `arm64` (aarch64).
- Idempotent: re-running with same version is a no-op (or reinstalls).

**Must-haves**:
- `bash scripts/install_test.sh` passes (mocked).
- `curl -fsSL <url> | bash` works on a fresh system (verified in P4 e2e).
- `curl -fsSL <url> | bash -s -- --system` installs to `/usr/local/bin` (as root).
- Re-running updates the binary; `~/.orca/orca.db` preserved.

**Verification**: 4-layer (structural: shellcheck; behavioral:
install_test.sh; security: no secret in script, no eval of remote
content beyond the script itself; quality: idempotent).

**Ship**: tag `v0.4.3`.

## Phase 3 — Docker Release (REQ-046)

**Goal**: Multi-stage Dockerfile; publish to Gitea container registry
per release.

**Persona**: devops-engineer.

**Wave 1**:

| Task | File(s) | Persona | REQ |
|------|---------|---------|-----|
| T3.1: Write `Dockerfile` (multi-stage: golang:1.25 → distroless/static-debian12) | `Dockerfile` | devops-engineer | REQ-046 |
| T3.2: Extend `scripts/release.sh` with docker build + login + push | `scripts/release.sh` | devops-engineer | REQ-046 |
| T3.3: Add `container-publish` step to `.coreci.yml` release pipeline | `.coreci.yml` | devops-engineer | REQ-046 |
| T3.4: Write `docs/docker.md` (docker run quickstart, volume mounts, ORCA_HOME) | `docs/docker.md` | devops-engineer | REQ-046 |
| T3.5: Add `.dockerignore` (exclude .git, bin, .env, *.tar.gz) | `.dockerignore` | devops-engineer | REQ-046 |

**Dockerfile spec** (per R-005):
- Stage 1 (`golang:1.25`): `CGO_ENABLED=0 go build -trimpath -ldflags=... -o /orca ./cmd/orca`.
- Stage 2 (`gcr.io/distroless/static-debian12:nonroot`): `COPY --from=builder /orca /orca`, `ENV ORCA_HOME=/var/lib/orca`, `ENTRYPOINT ["/orca"]`.
- `ARG VERSION` + `ARG GIT_COMMIT` + `ARG BUILD_TIME` for ldflags injection.
- Image runs as `nonroot` user (distroless default) — `ORCA_HOME=/var/lib/orca` must be volume-mounted.

**release.sh extension**:
- After Gitea release: `docker build --build-arg VERSION=$VERSION ... -t git.cloudinit.dev/coreci/orca:$VERSION -t git.cloudinit.dev/coreci/orca:latest .`
- `echo "$GITEA_TOKEN" | docker login git.cloudinit.dev -u cloudinit-bot --password-stdin`
- `docker push git.cloudinit.dev/coreci/orca:$VERSION` + `docker push git.cloudinit.dev/coreci/orca:latest`
- Skip gracefully if `docker` not on PATH (local dev without docker).

**.coreci.yml extension**:
- New step `container-publish` in the `release` pipeline, using an image with docker CLI (e.g., `docker:24-cli` with docker-in-docker service, or a custom image). Per P-001 pitfall.

**Must-haves**:
- `docker build -t orca-test .` succeeds locally.
- `docker run --rm orca-test version` prints the version.
- `scripts/release.sh vX.Y.Z` publishes both the Gitea release AND the container image.
- `.coreci.yml` release pipeline includes the container-publish step.

**Verification**: 4-layer (structural: Dockerfile lint; behavioral: docker
build + run; security: no secret in image, .env excluded; quality:
reproducible build via ARGs).

**Ship**: tag `v0.4.4`.

## Phase 4 — Final Review + Ship + Audit (Milestone Release)

**Goal**: Multi-persona review, audit, milestone ship.

**Tasks**:
| Task | Persona | Detail |
|------|---------|--------|
| T4.1: `ciagent-review` | all | Review P1-P3 changes across personas |
| T4.2: `ciagent-audit` | lead-developer | Reconstruction test, file/branch/commit discipline |
| T4.3: End-to-end verification | lead-developer | Unauth curl to releases API (REQ-045 ✓), fresh install.sh (REQ-043 ✓), `--system` (REQ-042 ✓), update-in-place (REQ-044 ✓), docker pull+run (REQ-046 ✓) |
| T4.4: Milestone ship | lead-developer | Merge phase/04 → milestone/v0.5 → main, tag v0.4.5, create milestone release, build + upload all artifacts |
| T4.5: Complete milestone | lead-developer | Update REQUIREMENTS.md (REQ-041..046 complete), ROADMAP.md (v0.5 complete), clear CHECKPOINT.json |

**Ship**: tag `v0.4.5` (the milestone release, promoted to `v0.5.0`).

## Wave Ordering Summary

All 4 phases are single-wave (no inter-phase dependencies within a
phase). Phases execute strictly sequentially: P1 → P2 → P3 → P4.

- **P1** (Wave 1): T1.1..T1.5 — namespace unification.
- **P2** (Wave 1): T2.1..T2.4 — install.sh.
- **P3** (Wave 1): T3.1..T3.5 — docker.
- **P4** (Wave 1): T4.1..T4.5 — review + ship.

## Versioning

- P0 ship: `v0.4.1` (first patch on v0.4.x line after v0.4.0 milestone tag).
- P1 ship: `v0.4.2`.
- P2 ship: `v0.4.3`.
- P3 ship: `v0.4.4`.
- P4 ship: `v0.4.5` (final phase = milestone release, promoted to `v0.5.0`).

Tags run on the v0.4.x line (previous minor). The milestone branch label
is `milestone/v0.5-distribution`. No separate minor tag — the final
phase's patch IS the milestone release per `run.md` versioning logic
for feature milestones.