clawdie/colibri
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 31
colibri/docs/guide/operate/git-storage.md
Sam & Claude 95c487546d
Some checks are pending
CI / rust (pull_request) Waiting to run
Details
CI / markdown (pull_request) Waiting to run
Details
CI / port (pull_request) Waiting to run
Details
CI / agent-jail-pkgs (pull_request) Waiting to run
Details
docs(guide): port 39 procedural docs from clawdie-ai to colibri 
New docs/guide/ tree — canonical home for operator-facing procedural docs.
Starlight frontmatter added to all files. 0.12 alignment fixes applied:

- v0.11.0 → v0.12.0 throughout
- PI_TUI_PROVIDER/MODEL → DEEPSEEK_API_KEY
- Headless Codex login → Agent runtime setup (zot + RPC mode)
- /login and auth.json references removed
- pi → zot in provider-fallback spawn reference
- colibri-provider-verify (was pi-provider-smoke)
- Language cleanup: smoke test → verification, fake → test,
  can't self-fix → requires operator intervention,
  broken → unresponsive, Fix anything broken → Verify all checks pass

Two-tree model: docs/wiki/ (decisions) + docs/guide/ (procedural).
Single source of truth in colibri. clawdie-ai docs/public/ to be retired.
2026-06-26 09:16:43 +02:00

4.1 KiB
Raw Blame History

title
Git Storage

This document defines the local code-hosting target for Clawdie.

Decision

Use a dedicated shared FreeBSD jail named git by default for local code storage. Operators may override the jail name with GIT_JAIL_NAME, but it is no longer derived from ASSISTANT_NAME.

Initial scope:

  • bare repositories by default
  • optional later Forgejo Web UI on the same jail role
  • no CI
  • no public exposure by default

This keeps code storage simple and reduces dependence on external remotes during bootstrap, maintenance, and recovery.

Why

  • lower operational complexity than introducing a forge immediately
  • easy to mirror from Codeberg without changing public workflow
  • fits the current service-jail design
  • clean separation from:
    • the host orchestrator
    • PostgreSQL (DB_RUNTIME=host or optional db jail)
    • cms content stack

Jail Shape

  • jail name: git by default; override with GIT_JAIL_NAME
  • hostname: git.<agent>.home.arpa
  • role: persistent internal Git Service
  • preferred storage path: /srv/git
  • registry/default slot: <subnet>.2

infra/jails.yaml defines the default git slot as .2. A live install may override the actual address through .env with WARDEN_GIT_IP; live state and .env win when answering what is running now.

The installer stores this as:

  • CODE_HOSTING_MODE=external|git|gitea
  • REMOTE_GIT_URL=...
  • FEATURE_GIT=true|false
  • FEATURE_GITEA=true|false
  • WARDEN_GIT_IP
  • GIT_JAIL_NAME

Mode meanings:

  • external = bootstrap from a remote git URL only
  • git = plain local git storage in the git jail
  • gitea = local git plus the optional Forgejo application layer

Recommended default:

  • current installs default to git

First Bootstrap Goal

The first supported target is:

  1. create the git jail
  2. install git
  3. create /srv/git
  4. create one or more bare repositories
  5. allow local clone/push from host and future worker/cms tooling

This stage does not require nginx, a public UI, or a separate database.

Recommended Workflow

Keep public and local remotes separate.

  • origin = Codeberg
  • git = local bare repository in the git jail

If CODE_HOSTING_MODE=external, keep the bootstrap path simple:

  • origin = REMOTE_GIT_URL

If CODE_HOSTING_MODE=git, use:

  • origin = Codeberg
  • git = local git jail

If CODE_HOSTING_MODE=gitea, use:

  • origin = Codeberg
  • git or forgejo = local Forgejo-backed remote

That allows:

  • local-first clone/push inside the host
  • later push or mirror upstream when wanted
  • reduced dependence on external network availability

When CODE_HOSTING_MODE=external, the installer also captures REMOTE_GIT_URL for bootstrap and clone operations.

Non-Goals

Not part of the first bootstrap implementation:

  • Forgejo provisioning by default
  • full Codeberg-like forge
  • public HTTP UI
  • SSH key management for the git jail
  • automatic mirroring

Those can be layered on later if the plain git jail proves useful. The first bootstrap target remains plain git storage.

First Repository Layout

The first useful filesystem shape inside the git jail is:

/srv/git/
  Clawdie-AI.git

The repository should be:

  • bare
  • internal-first
  • mirrored from the current repo or the configured upstream remote
  • clonable from host-side tooling and future jailed workflows

Recommended first command shape after bootstrap:

git clone --mirror https://codeberg.org/Clawdie/Clawdie-AI.git /srv/git/Clawdie-AI.git

Related Files