CodeForPhilly / CodeForPhilly/codeforphilly-ng

docs: document push-daemon-as-durability + fix stale PVC/working-tree language in runbook

Open
#87 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
1
Forks
1
Avg merge
5d 3h
Merged PRs (30d)
9

Description

## Background

PR #86 switched the data-repo volume from PVC to `emptyDir` and made the clone bare. Two doc gaps remain:

### 1. Durability tradeoff is undocumented

With `emptyDir`, the bare clone is wiped on every pod boot. If the pod crashes (OOM, node failure, hard kill) before the push daemon has shipped locally-committed gitsheets writes to origin, **those commits are lost** — the volume goes away before any container code (reconcile, escape-hatch) can run.

Today's reconcile escape-hatches local-ahead commits to `conflicts/` only when the container restarts cleanly enough to invoke `reconcileDataRepo`. On a hard crash, that path never runs.

Mitigating factor: the push daemon runs continuously with retry/backoff, so the window of unpushed local state is small. But this is now a meaningful change in the durability story vs. the previous PVC-backed setup, and it should be documented as an explicit operating constraint.

**Where to add:**
- `specs/behaviors/storage.md` — under "The data clone is bare", a short subsection: "Durability: writes are durable once `origin/` has them. The push daemon is the only line of defense for in-flight commits; on hard pod crash before the next push, local commits are lost."
- `docs/operations/runbook.md` — in the "API won't boot" or a new "Durability" section, the same note plus a pointer to the push daemon's lag/log for verification.

### 2. Stale wording in runbook's "Fetch from the pod's data clone" section

[`docs/operations/runbook.md`](https://github.com/CodeForPhilly/codeforphilly-ng/blob/main/docs/operations/runbook.md) — the section that documents the `git-pod-uploadpack.sh` operator helper still says:

> The pod's **working tree** lives on a **PVC** at `/app/data` inside the container...

After PR #86 that's incorrect on both counts — it's now a bare gitdir on an `emptyDir`. Update to reflect bare-clone reality. Reference [`specs/behaviors/storage.md`](https://github.com/CodeForPhilly/codeforphilly-ng/blob/main/specs/behaviors/storage.md) → "The data clone is bare".

## Scope

Single PR. Maybe ~30 lines of diff total.

_Filed as follow-up from PR #86._

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.