nordisk/holger

Holger for absolute beginners

Class: idiot. No jargon, nothing assumed. What holger is, why it exists, and how to get it running — spelled out step by step. If you already know the domain, read guide.md instead.

What is holger?

Holger is a warehouse for software packages. Programmers constantly download ready-made building blocks — a Rust "crate", a Python "wheel", a Java "jar", a Docker image. Normally their tools fetch these from the public internet (crates.io, PyPI, Docker Hub, …).

Some places can't touch the internet — banks, defence, hospitals, anything that has to stay "airgapped" (physically cut off). Holger is the warehouse you put inside that walled-off network so programmers there can still get their packages. It does the job that Nexus or Artifactory does, but built for the airgap and for auditing who got what.

How do packages get in?

Someone on the outside (internet side) runs the holger agent. It downloads the packages you need and bundles them into one sealed file — a .znippy archive. Think of it as a shrink-wrapped, tamper-evident shipping crate: each file inside has a fingerprint (a "blake3 checksum"), so you can prove nothing was swapped.

You carry that crate across the airgap — literally on a USB stick or a disc — and hand it to the holger server on the inside. Done. No cable ever crosses the boundary.

How do programmers get packages out?

The clever bit: the holger server pretends to be the registry each tool already expects. Point pip at holger and pip thinks it's talking to PyPI. Point docker pull at holger and it answers like Docker Hub. No special tools, no retraining — the normal commands just work, but the packages come out of your sealed crate instead of the internet.

What does "pluggable" mean?

Each kind of package — Rust, Python, Java, npm, Docker, Helm, and ten more — has its own quirky way of being asked for and delivered. Holger handles each with a small, swappable module called a backend (a plug-in adapter). Every backend agrees to the same simple checklist (in code, a "trait"):

• "Give me a package by name and version" → hand back the bytes.
• "A real pip/docker/cargo is talking to you — answer in its language."

Because every backend follows the same checklist, the core of holger doesn't care which kind of package it's dealing with. It looks up the right plug-in by the repository's name and lets it do its thing. Adding a brand-new kind of package is therefore easy — about a hundred lines plus one line in a registry (the registry-guide shows exactly how).

The whole thing in one breath

Outside the wall, the agent packs the packages you need into one sealed, fingerprinted crate. You carry the crate across the airgap. Inside the wall, the server unpacks on demand and impersonates every public registry, so ordinary pip / cargo / docker / helm commands keep working — fully offline, fully audited. Each package type is handled by a small swappable backend, all speaking one common contract, so new ecosystems plug in without changing the core.

Try it — the smallest possible run

You need a terminal (the black window where you type commands) and the holger repo on disk. Type each line and press Enter.

1. Go into the repo:

cd /run/media/rickard/T9/git/holger

1. Build the server binary (this takes a few minutes the first time):

cargo build -p holger

When it finishes without red text, the program is at target/debug/holger-server.

1. Ask it for help — this proves it runs:

./target/debug/holger-server --help

You should see a list of commands. That is holger.

To serve real packages you point it at a config file (holger.ron) that lists your repositories and the .znippy archives behind them — the serve-guide walks through a first config. To make a .znippy to serve, use the agent (agent-guide).

Is it safe?

Holger had a security clean-up pass, so the dangerous corners are tidied: you can't trick it into reading files outside its warehouse with a sneaky package name; two people writing at once can't corrupt a sealed crate; the internet-side agent won't hand its passwords to a stranger's web address; and it keeps a tamper-evident logbook (on by default) of who put what in and when.

But remember the one thing: holger does not lock its front door unless you tell it to. Fresh out of the box, with no security settings, anybody can upload to it. That's fine for a toy on your laptop, dangerous on a network. To lock it, turn on a login and hand out roles — the auth-for-idiots guide does this click by click.

What if I want to remove holger again?

There are two different things you might mean, and holger keeps them apart on purpose.

1. "Take the warehouse away." This throws out the stuff holger stored: the packages, the logbook, the settings file it generated for itself.

holger-server install remove --purge

Your keys are safe. Holger's machine has a small secret file — an "ssh key" — that proves to your private code servers that this machine is allowed to talk to them. Somebody registered that key once, by hand, on every server. Deleting it would mean doing all of that again. So --purge deliberately steps around it: it wipes the packages and leaves the key (and any saved access token) untouched, byte for byte. When you install holger again, it just carries on with the same key. Nothing to re-register.

That is a rule for all the software in this suite, not a holger quirk: uninstalling nukes the data and keeps the keys.

2. "Take everything away, keys included." Only if you really mean it, and you have to say so out loud:

holger-server install remove --purge --wipe-identity

This destroys the key. It cannot be undone. A fresh install will make a brand new key, and someone will have to register that new key on every code server before holger can fetch anything again. holger refuses to accept --wipe-identity unless --purge is there too, so you can't reach it by accident.

Either way holger tells you plainly what it did — whether the key was kept or destroyed — and if there was nothing to delete in the first place, it says that instead of pretending it cleaned something up.

Can another program run holger inside itself?

Yes — holger doesn't have to be a separate server. Another Rust program can link holger as a library and run a little registry right inside its own process, calling holger's functions directly with no network. The reference user is nornir; the friendly walk-through is embed-for-idiots.