Skip to content
Clawdie Clawdie

Git Storage

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

Decision

Section titled “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

Section titled “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

Section titled “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

Section titled “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.

Section titled “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

Section titled “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

Section titled “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:

Terminal window
git clone --mirror https://codeberg.org/Clawdie/Clawdie-AI.git /srv/git/Clawdie-AI.git
Section titled “Related Files”