path: root/README

git-forge-cloudflare
====================
Runs git-forge on Cloudflare Containers with R2 for durable storage. A Worker
routes every request to a single container through one Durable Object. Inside
the container, syncd mirrors the data directory to an R2 bucket and restores
it at boot.

git-forge is neither modified nor vendored here. The image builds it from its
own repository, at the commit named in `forge.rev`.

Container disk is erased whenever the instance sleeps or its host is
recycled, and git-forge needs a real filesystem and one running process.
Cloudflare supplies the second: a Durable Object name resolves to one instance
globally. syncd supplies the first: the container keeps its filesystem on
ephemeral disk, R2 holds the durable copy, and git-forge is unaware of either.


Architecture
------------
    Worker  ->  Durable Object "forge"  ->  Container
                                              :8080  git-forge, unmodified
                                              :8081  syncd, in this repo
                                                |
                                              Outbound  ->  R2, logs, mail

    worker.js       routes requests and answers the intercepted hosts
    syncd           mirrors and restores the datadir, makes writes durable
    Containerfile   git-forge, syncd, git, cgit, highlight, tini
    wrangler.jsonc  the bindings

The Worker intercepts three hostnames, none of which resolve in DNS:

    r2.forge.internal      objects, served from the R2 binding
    logs.forge.internal    stdout, logged where `wrangler tail` can see it
    mail.forge.internal    Mailgun's api shape, answered by whatever sends

syncd carries no R2 credential: it sends plain HTTP to a hostname the Worker
intercepts on the same machine. Anything in the container that can make a
request has the whole bucket, cgit included; a binding has no narrower form.
Logs travel the same path because Cloudflare does not forward container
stdout to Workers observability.


Storage
-------
    manifest.json                    which repositories exist. Authoritative
    stale.json                       directories the manifest stopped listing,
                                     and when
    config/...                       the config directory, file by file
    config/git/objects/...           its audit log
    config/REFS                      its refs
    repos/{path}.git/objects/...     immutable, uploaded once, never rewritten
    repos/{path}.git/REFS            `git show-ref` output, one PUT

Git objects are content addressed and append only, so only refs change, and
syncd stores them as state rather than files: `gc --auto` moves loose refs
into `packed-refs`, and a restored loose ref would override it and resurrect
an old head. Objects go up first and refs last, the order git pushes in, so a
crash within a flush leaves the state from before the write.

The manifest is what makes deletion work: restore creates only the
directories it names, so rewriting it deletes. The objects of a repository the
manifest no longer lists stay in the bucket for seven days, reported at every
boot and once a day while the container runs, and are removed by the first
check after that. The delay is the window to put back a manifest restored
from a backup or written short: a boot that believed one would otherwise
remove every repository it omits.

A bucket holding objects under `repos/` and no manifest is fatal rather than
empty. A forge that never made a repository writes no manifest and starts
normally.

Boot restores `config/` in full, then creates one empty directory per
repository in the manifest, which is all git-forge's startup scan looks at.
syncd hydrates a repository on its first request: `git init --bare`, copy the
objects, replay the refs. The issue and wiki siblings hydrate with it. A
repository that should have hydrated and did not fails loudly: git refuses an
empty directory, and git-forge does not treat that as an empty repository.


Durability
----------
syncd puts a write in R2 before reporting success. It forwards the request to
git-forge and, for anything other than a known read, buffers the response,
flushes, and returns once the flush completes. A mutex serialises flushes and
each one rescans the whole datadir, so every request covers its own writes
whatever URL it had:

    held      everything that is not a GET or HEAD, except git-upload-pack
    streamed  every GET and HEAD, except /confirm-email and /oidc/...

A held response is capped at 8 MiB and answered 503 past it; the cap is for
cgit, which answers a snapshot to POST as well.

One write is asynchronous: the date a push token was last used, which
git-forge treats as telemetry. A sweep every 15 seconds carries it up, and
backstops any misclassification above.

tini is PID 1 and syncd its child, with git-forge as syncd's child, so the
container dies if syncd dies. On SIGTERM syncd signals git-forge, waits for
it to drain, flushes, and exits.


Limits
------
Cloudflare caps a push at 100 MB of new objects at the edge, more on Business
and Enterprise, and nothing here can raise it. Clones are unbounded. git-forge
separately caps a wiki push at 16 MiB. Import an existing repository in
ranges, so that no single pack exceeds the cap:

    git push origin <sha>:refs/heads/master

Local disk bounds the datadir. Instance type `basic` has 4 GB, and `git gc`
needs room to repack on top of it; `wrangler.jsonc` picks the type, and 20 GB
is the largest.

Boot costs one round trip per object under `config/`. The sweep packs the
audit log at five hundred loose objects. A flush walks the whole datadir and
forks `git show-ref` per directory, so its cost, and every held write's
latency, grows with the number of repositories.


Test
----
    ./test

Builds the image and exercises it end to end: create the first admin, create
a repository, push, destroy the container, then start a new one with only the
bucket to work from, and again after the audit log is packed. It needs docker,
go, git, curl and openssl on the host, and the git-forge checkout
`fetch-forge` reads. `fake-r2.go` stands in for the object handler in
`worker.js`, so no Cloudflare account is needed.

`go test` covers syncd against a bucket: a flush racing a hydration, a gc, a
push, and a deletion, and the prune waiting out its grace.

The rest of `worker.js` has no coverage: it runs only in a deployment.


Deploy
------
Needs a Cloudflare account on Workers Paid with R2 enabled, wrangler, and
docker.

    ./fetch-forge
    wrangler r2 bucket create git-forge
    wrangler secret put GIT_FORGE_COOKIE_KEY     at least 32 characters
    wrangler deploy

`fetch-forge` copies git-forge's source into `forge/` for the image build,
from `../git-forge` at the commit in `forge.rev`, or from `GIT_FORGE_SRC` and
`GIT_FORGE_REV`. `forge/` is derived and uncommitted. Upgrading means editing
`forge.rev`; the pin exists because this repository asserts which of
git-forge's routes write, which one removes a repository, and what a
repository holds besides objects and refs. syncd logs the revision at startup.

`GIT_FORGE_COOKIE_KEY` must be a secret: the datadir is ephemeral, so a
generated key would sign everybody out on every restart. syncd refuses to
start without one.

A custom domain is one route, with workers.dev switched off:

    "routes": [{ "pattern": "git.example.com", "custom_domain": true }],
    "workers_dev": false,

Switching workers.dev off matters: base_url is decided by the request that
starts the container, so two hostnames on one worker means whichever wakes it
wins and every form posted to the other returns 403 until it restarts.

Leave `base_url` unset. worker.js supplies it from the origin of the request
that started the container, always as https. Set it in `wrangler.jsonc` only
when a custom domain fronts a hostname requests do not arrive on, and then
exactly. Put nothing else in `vars`: an environment value pins what the admin
page could otherwise change. worker.js sets `GIT_FORGE_CLIENT_IP_HEADER` to
`CF-Connecting-IP`, which the edge overwrites, so rate limits count real
addresses rather than syncd's.

Against an empty bucket git-forge prints a one time setup token and serves
`/setup`. The container starts on the first request and prints the token
then, so start `wrangler tail` beforehand. A restart before setup issues a new
token; `wrangler deploy` forces a restart.

The container stops after ten idle minutes and starts again on the next
request. A Durable Object alarm stops it with SIGTERM once nothing is in
flight; a request arriving mid-drain receives an error. Retry.


Mail
----
git-forge's Mailgun driver issues one form-encoded POST, and `worker.js`
answers that shape, so any sender serves git-forge without changing it and
every key stays outside the container. The binding is declared and sends
nothing until git-forge's config points at the intercepted host; until then
git-forge's default driver drops each message with a log line naming the
recipient and subject.

Edit the copy of `forge.json` in the bucket, since the web interface does not
expose mail settings, then redeploy:

    wrangler r2 object get git-forge/config/forge.json --remote --pipe >f
    "$EDITOR" f
    wrangler r2 object put git-forge/config/forge.json --remote --file=f
    wrangler deploy

`forge.json` reaches the bucket after the container has run once. git-forge
requires `domain` to be non-empty though nothing uses it:

    "mail": {
      "driver": "mailgun",
      "from": "git-forge <forge@example.com>",
      "mailgun": {
        "domain": "forge",
        "base_url": "https://mail.forge.internal/v3"
      }
    }

Without a sending domain onboarded to Email Service, a binding reaches only
addresses verified in the account. With no binding declared, `worker.js` logs
each message and reports success. The spool lives on container disk and is
not mirrored.


Sign in with a provider
-----------------------
git-forge implements generic OpenID Connect: discovery, authorization code
with PKCE, and a signed id_token carrying a verified address. Google works,
as does anything that publishes a discovery document; GitHub does not, since
its only OIDC issuer mints workload tokens.

Declare the provider in the bucket's copy of `forge.json`, as with mail:

    "oidc": [{
      "key": "google",
      "label": "Google",
      "issuer": "https://accounts.google.com",
      "client_id": "<id>.apps.googleusercontent.com",
      "allow": ["someone@gmail.com", "@example.com"]
    }]

Supply the secret through the environment, never the file:

    wrangler secret put GIT_FORGE_OIDC_GOOGLE_CLIENT_SECRET

git-forge derives the variable name from the key, upper-cased. Register the
redirect uri `{base_url}/oidc/{key}/callback` with the provider exactly. A
secret added while a container runs takes effect after a restart; both sides
report what they hold, without its value, in `wrangler tail`.

An account minted this way is named `{key}:{name}` and holds no grants; the
admins receive mail when one first appears. Set `allow`, or every account the
provider vouches for can mint one.

The container contacts the provider directly. This is the only feature that
depends on `enableInternet` in `worker.js` and on the ca bundle `main.go`
assembles; a forge with no provider can set it false.


Operations
----------
R2 holds everything that has to survive. Two backups:

    every repository, cloned                    readable without any of this
    the bucket, mirrored to another bucket      exact, and restores as is

Cloning omits the account table, so keep `users.json` beside it, and treat it
as credential material in full:

    wrangler r2 object get git-forge/config/users.json --remote --pipe

R2 speaks the S3 api at `https://<account>.r2.cloudflarestorage.com`, so any
S3 tool mirrors the bucket.

A repository deleted through the web is reported at every boot, and daily
while the container runs, for seven days:

    stale: notes.git, 412 objects no manifest lists, removed after 2026-09-18

To bring it back within that window, put `manifest.json` and `repos.json`
back as they were and redeploy; after it, a clone is the only recovery.

Reverting any other mistake means editing the bucket and restarting, as with
mail. A restore reads the working tree, not the audit log, so putting the old
content back is the revert:

    wrangler r2 object get git-forge/config/repos.json --remote --pipe >f
    "$EDITOR" f
    wrangler r2 object put git-forge/config/repos.json --remote --file=f
    wrangler deploy

Do this while the forge is idle: syncd leaves a change made behind its back
alone, but a simultaneous change through the web wins.

What the log means when something is wrong:

    restore: ...                    fatal, deliberately: an empty datadir
                                    would be flushed over the real one
    the change could not be made    a flush failed, so the write is on a disk
    durable                         that does not survive: a 503 on purpose.
                                    The next flush carries it up
    Not a git repository:           hydration did not fire for a repository
    /var/lib/git-forge/repos/...    the matcher missed. The objects are still
                                    in the bucket
    config: audit log not           the bucket is missing an object the log's
    replayed                        refs name. This costs history and nothing
                                    else
    no sender bound                 mail is configured but the binding is not
    GIT_FORGE_COOKIE_KEY must be    the secret is unset
    set

Memory and disk are billed on the instance type while the container is
awake; a sleeping container costs nothing.


Debugging
---------
    wrangler tail                                  logs, both processes
    wrangler r2 object get git-forge/manifest.json --remote --pipe
    wrangler r2 object get git-forge/repos/foo.git/REFS --remote --pipe

`--remote` is mandatory: without it wrangler reads a local simulated bucket
and finds nothing. `REFS` is `git show-ref` output. syncd logs one line per
flush that uploaded anything and one per hydration.