nordisk/holger

Repository replication — the beginner's guide

The problem, in one sentence

You have two package servers and you want the second one to hold copies of everything on the first — without copying the same file twice.

The kitchen analogy

Think of two pantries. The source pantry is full; the destination pantry is being stocked. Replication walks the full pantry shelf by shelf and, for each jar, checks: does the other pantry already have this exact jar?

• If the other pantry has the same jar already → leave it, move on (skip).
• If it is missing (or has a different jar with the same label) → carry a copy over (copy).

You never take anything out of the full pantry — you only read its labels and copy jars into the empty one. And if you run the whole walk again, nothing happens: every jar is already there. That "nothing happens the second time" is what we mean by idempotent.

"By content id" — what makes it skip

Every artifact has a fingerprint: a sha256 hash of its bytes (its "content id"). Replication decides "already there?" by that fingerprint, not just the name. So if the destination already has the exact same bytes, it is skipped. If the bytes differ, it is recopied so the destination matches the source.

Try it on your laptop (no network)

You need two config files (two "stores"). Point them at two different folders. Then:

# 1. See what WOULD happen (writes nothing):
holger-server replicate --from source.ron --to dest.ron

# 2. Actually do it:
holger-server replicate --from source.ron --to dest.ron --execute

# 3. Do it AGAIN — notice it copies nothing this time:
holger-server replicate --from source.ron --to dest.ron --execute

The first execute prints copied N. The second prints copied 0, skipped N. That is replication working correctly: it never does the same work twice.

The safety rails

• Preview by default. Without --execute it only tells you what it would do. Nothing is written.
• Source is never touched. Only read.
• A read-only destination fails loudly. If the destination can't accept writes, every artifact is reported as FAIL and the command exits non-zero — it never pretends to have copied something it didn't.

Where to go next

• Copying between two repos on one running server instead of two stores? That is the ReplicationService.Replicate gRPC call — same rules, admin-gated on the destination. See the guide.
• The full picture of why it is a pure function over the backend seam is in the design.