Sam & Claude
95c487546d
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.
147 lines
4.1 KiB
Markdown
147 lines
4.1 KiB
Markdown
---
|
|
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:
|
|
|
|
```text
|
|
/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:
|
|
|
|
```bash
|
|
git clone --mirror https://codeberg.org/Clawdie/Clawdie-AI.git /srv/git/Clawdie-AI.git
|
|
```
|
|
|
|
## Related Files
|
|
|
|
- [setup/git.ts](https://codeberg.org/Clawdie/Clawdie-AI/src/branch/main/setup/git.ts) — git jail provisioning
|
|
- [setup/forgejo.ts](https://codeberg.org/Clawdie/Clawdie-AI/src/branch/main/setup/forgejo.ts) — optional Forgejo layer
|
|
- [setup/install.ts](https://codeberg.org/Clawdie/Clawdie-AI/src/branch/main/setup/install.ts) — install orchestrator
|
|
- [git-jail-bootstrap.yaml](https://codeberg.org/Clawdie/Clawdie-AI/src/branch/main/infra/ansible/playbooks/git-jail-bootstrap.yaml)
|
|
- [ansible-freebsd skill](https://codeberg.org/Clawdie/Clawdie-AI/src/branch/main/.agent/skills/ansible-freebsd/SKILL.md)
|