gerardo/framebridge
1
0 Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Format APT maintenance instructions

Browse Source
This commit is contained in:
Gerardo Betancourt committed 2026-10-28 11:54:59 -04:00
1 parent fb53fe2b70
commit 7c9371b76a
1 file changed
+17 -17
Download Patch File Download Diff File Expand all files Collapse all files
tools/README-APT.md
+17 -17
View File
@@ -1,10 +1,10 @@
# Signed distribution repositories # Signed distribution repositories
The canonical source is the existing GERANAS Gitea repository The canonical source is the existing GERANAS Gitea repository
\`gerardo/framebridge\`. Build all three reviewed DEBs from its release commit; `gerardo/framebridge`. Build all three reviewed DEBs from its release commit;
do not edit installed files to produce an update. do not edit installed files to produce an update.
One HTTPS repository at \`https://framebridge.betancourt.one/debian/\` contains One HTTPS repository at `https://framebridge.betancourt.one/debian/` contains
three independent suites: three independent suites:
| Suite | Tested distribution profile | | Suite | Tested distribution profile |
@@ -14,12 +14,12 @@ three independent suites:
| mint22 | Linux Mint 22.x, amd64, Python 3.12 | | mint22 | Linux Mint 22.x, amd64, Python 3.12 |
Select exactly the suite matching the computer. These are three builds of one Select exactly the suite matching the computer. These are three builds of one
binary package, \`framebridge-original-expanded\`, with unique pool filenames. binary package, `framebridge-original-expanded`, with unique pool filenames.
This table does not certify untested releases or architectures. This table does not certify untested releases or architectures.
## Prepare and review ## Prepare and review
Run \`python3 tools/build_apt_repository.py prepare --help\` in the source Run `python3 tools/build_apt_repository.py prepare --help` in the source
repository. Supply the exact three version-matched DEBs, the existing official repository. Supply the exact three version-matched DEBs, the existing official
public key and a new output directory. The command copies the artifacts, builds public key and a new output directory. The command copies the artifacts, builds
indexes and by-hash paths, and prints the immutable input manifest SHA-256. indexes and by-hash paths, and prints the immutable input manifest SHA-256.
@@ -27,23 +27,23 @@ It does not open a private keyring, sign, publish or install anything.
Review the manifest, package hashes and release identity before signing. Review the manifest, package hashes and release identity before signing.
The public key must contain exactly one primary release key with fingerprint The public key must contain exactly one primary release key with fingerprint
\`2B1F01BC806C0B33CB6CEDDE52859CEBC91B8808\`. Official subkeys are allowed. `2B1F01BC806C0B33CB6CEDDE52859CEBC91B8808`. Official subkeys are allowed.
## Sign in the owner's normal terminal ## Sign in the owner's normal terminal
Run \`python3 tools/build_apt_repository.py sign --help\`. Pass the reviewed Run `python3 tools/build_apt_repository.py sign --help`. Pass the reviewed
output directory and exact manifest SHA-256. The signer requires a non-root output directory and exact manifest SHA-256. The signer requires a non-root
interactive terminal and an owner-private existing signing home. Set interactive terminal and an owner-private existing signing home. Set
\`GPG_TTY=$(tty)\` in that normal terminal if the pinentry implementation needs it. `GPG_TTY=$(tty)` in that normal terminal if the pinentry implementation needs it.
The owner's passphrase is entered only into normal pinentry; it is never an The owner's passphrase is entered only into normal pinentry; it is never an
argument, environment variable or chat message. argument, environment variable or chat message.
The signer writes \`Release.gpg\` and \`InRelease\` for each suite, verifies the The signer writes `Release.gpg` and `InRelease` for each suite, verifies the
signatures against the public key and exact reviewed Release plaintext, then signatures against the public key and exact reviewed Release plaintext, then
clears the dedicated signing agent. Existing signatures or partial results clears the dedicated signing agent. Existing signatures or partial results
cause refusal; inspect a partial transaction instead of blindly rerunning it. cause refusal; inspect a partial transaction instead of blindly rerunning it.
Run \`verify\` with the same pinned manifest hash after signing and again after Run `verify` with the same pinned manifest hash after signing and again after
transport. Metadata expires after 30 days; publish a freshly signed Release transport. Metadata expires after 30 days; publish a freshly signed Release
before expiry, without altering historical signed artifacts. before expiry, without altering historical signed artifacts.
@@ -55,7 +55,7 @@ current public generation before activation. Preserve the existing signed
0.3.1 downloads and old repository metadata in an archive path. 0.3.1 downloads and old repository metadata in an archive path.
Publish only reviewed manifest files, the six verified signature files and the Publish only reviewed manifest files, the six verified signature files and the
signing receipt. Public directories must be \`0755\` and files \`0644\`; a private signing receipt. Public directories must be `0755` and files `0644`; a private
staging umask must not leak into the served generation. Never publish the staging umask must not leak into the served generation. Never publish the
signing home, private receipts, account configuration or operational worktree. signing home, private receipts, account configuration or operational worktree.
Activate a complete verified generation, preserving the web unit's existing Activate a complete verified generation, preserving the web unit's existing
@@ -65,26 +65,26 @@ for all three suites through the final HTTPS authority.
## Configure a client ## Configure a client
Install the verified official public key as Install the verified official public key as
\`/etc/apt/keyrings/framebridge-archive-keyring.asc\` with mode \`0644\`. `/etc/apt/keyrings/framebridge-archive-keyring.asc` with mode `0644`.
Its fingerprint must match the value above. Add a Deb822 source file: Its fingerprint must match the value above. Add a Deb822 source file:
\`\`\`text ```text
Types: deb Types: deb
URIs: https://framebridge.betancourt.one/debian/ URIs: https://framebridge.betancourt.one/debian/
Suites: trixie Suites: trixie
Components: main Components: main
Architectures: amd64 Architectures: amd64
Signed-By: /etc/apt/keyrings/framebridge-archive-keyring.asc Signed-By: /etc/apt/keyrings/framebridge-archive-keyring.asc
\`\`\` ```
Replace \`trixie\` with \`noble\` or \`mint22\` for those tested profiles. Then use Replace `trixie` with `noble` or `mint22` for those tested profiles. Then use
normal APT commands: normal APT commands:
\`\`\`sh ```sh
sudo apt update sudo apt update
apt-cache policy framebridge-original-expanded apt-cache policy framebridge-original-expanded
sudo apt install --only-upgrade framebridge-original-expanded sudo apt install --only-upgrade framebridge-original-expanded
\`\`\` ```
Do not use trusted=yes or disable signature/validity checks. APT update/download Do not use trusted=yes or disable signature/validity checks. APT update/download
verification does not itself prove runtime restart or reboot persistence. verification does not itself prove runtime restart or reboot persistence.
@@ -92,7 +92,7 @@ Confirm the actual installed version and ready connection after each upgrade.
## Tool checks ## Tool checks
\`python3 tools/test_build_apt_repository.py\` creates disposable packages and a `python3 tools/test_build_apt_repository.py` creates disposable packages and a
disposable signing identity in a temporary directory. It tests actual isolated disposable signing identity in a temporary directory. It tests actual isolated
APT acceptance for each suite and rejects altered packages/indexes/signatures, APT acceptance for each suite and rejects altered packages/indexes/signatures,
unexpected versions, path traversal and bundled extra primary trust keys. unexpected versions, path traversal and bundled extra primary trust keys.