stepss-apt

The Debian and Ubuntu package archive for STEPSS, served at apt.sps-lab.org.

For installing STEPSS, follow the landing page. This README is about how the archive is built.

What is in here

There are no packages in this repository, and there never will be. It holds the configuration that builds one:

Path	What it is
conf/distributions	The suite reprepro publishes: one codename, amd64, non-free
conf/options	reprepro's own settings
index.html	The landing page, and the only place users copy their .sources file from
sps-l-archive-keyring.asc	The public half of the signing key, installed into /etc/apt/keyrings
.github/workflows/publish.yml	Rebuilds the archive and deploys it to Pages

dists/, pool/, db/ and incoming/ are build output and are all in .gitignore.

How a release reaches a user

The deb leg of stepss-java-ui's release workflow fires a stepss-release repository_dispatch at this repository, in the leg itself and immediately after the .deb is attached to the release. That job then downloads the .deb assets of the three most recent releases, hands them to reprepro in an empty tree, signs the result, installs it in a clean container to prove it works, and deploys the whole thing to Pages as an Actions artifact.

The archive serves one version of STEPSS, the newest. That is not a policy choice: the Limit: header that would keep several is rejected by reprepro 5.3.1, which is what Ubuntu 24.04 and Debian 12 ship, and including an older .deb afterwards is a no-op. Three releases are downloaded anyway, because the newest release does not always carry a .deb (v3.74.8's Windows leg failed, and releases before v3.74.8 have no installer at all), and reaching back means the archive keeps serving the last good package rather than emptying itself. Users who need a specific build take it from the releases page.

Two more consequences worth knowing:

• Nothing is incremental. The site is rebuilt from the releases every time, so there is no drift between this repository and what is served, and re-running the workflow is always safe. It also means no .deb ever enters git history, where GitHub's 100 MiB per-blob limit would apply to a file already at 73 MB.
• A dropped dispatch is not fatal. Dispatches do not retry, and a lost one would otherwise mean the archive silently stops tracking releases. The weekly schedule: is there to pick that up; it costs nothing, because the run is idempotent.
• The container step upgrades from a release that may not configure, on purpose. It installs the previous release by hand to have something to upgrade from, and releases up to v3.74.11 leave install ok half-configured on a machine with no desktop: their postinst ran xdg-desktop-menu under set -e. Released history cannot be changed, and that is the state real users on servers are in, so the failure is tolerated and the assertion is on the end state instead. install ok installed, not a version number: a package whose postinst failed still reports its version. Do not tighten the first half back up; the upgrade repairing a broken predecessor is the thing being tested.

What the archive supports: Ubuntu 24.04 and newer, or a Debian of the same vintage, x86-64 only. The .deb takes its dependency names from the release it is built on, and no Linux arm64 build of the engines exists. getting-started/installation in stepss-docs and the landing page both say so; keep the three in step.

The signing key

Fingerprint	125ABE6917ED2F2965D6545B3600A756077AD061
User ID	SPS-L Packaging <[email protected]>
Type	RSA-4096, sign and certify
Expires	2031-08-15

One key, held in two places that have to stay in step: the private half in this repository's APT_GPG_PRIVATE_KEY secret, base64-encoded and without a passphrase so an unattended job can sign; the public half committed as sps-l-archive-keyring.asc, because that is the file users install and never touch again. The publish workflow refuses to run when the two fingerprints disagree, and warns a year before the key expires.

The private half is not in this repository and must never be. It belongs offline, and losing it means re-keying: every user then has to redo the setup by hand, because a key already installed in /etc/apt/keyrings cannot be replaced by anything the archive serves. The eventual answer is a small sps-l-archive-keyring package in this same archive that stepss depends on, so a future key arrives through apt upgrade before the current one expires. That is worth doing well before 2031.

Rotating the key means changing the secret and committing the new .asc in the same pass. A push touching sps-l-archive-keyring.asc triggers a rebuild on its own. To generate a replacement, on a machine you trust and never in CI:

# A dedicated key. Do not reuse a personal or commit-signing one. Created
# without a passphrase in one step, because an unattended job has to sign with
# it: the key's protection is that it lives only in a repository secret.
gpg --batch --pinentry-mode loopback --passphrase '' \
    --quick-generate-key "SPS-L Packaging <[email protected]>" rsa4096 sign 5y

KEYID=$(gpg --list-secret-keys --with-colons "[email protected]" \
          | awk -F: '/^fpr:/ {print $10; exit}')
echo "$KEYID"   # check this is the new key and not the one already in use

gpg --armor --export "$KEYID" > sps-l-archive-keyring.asc            # commit this
gpg --armor --export-secret-keys "$KEYID" | base64 -w0 > secret.b64  # the secret
gh secret set APT_GPG_PRIVATE_KEY --repo SPS-L/stepss-apt < secret.b64

Back secret.b64 up offline, then delete it. It is the signing key in plain text: do not leave it in a git working tree, where one git add -A publishes it.

Licensing

An APT repository reads as "free software, install it", and STEPSS is not that. RAMSES is proprietary, free for non-commercial use only and capped at 1000 buses and 2 cores; Helios and CODEGEN are under Academic Public Licences; only the two user interfaces are Apache 2.0. Components: non-free says so in the one file every user copies onto their machine, and the landing page says it beside the install snippet, because a user who installs through apt has agreed to nothing yet: the licence dialog appears on first launch, which is after installation.

The licence the University of Liège granted is non-transferable, so publishing from the lab's own infrastructure is covered and mirroring is not. The landing page asks people not to.

getting-started/license.md in stepss-docs owns these facts; everything here is a summary that points at it.