RTFM · Packages
Managing packages with APK
APK organises around six verbs and one mental model: repositories publish signed index snapshots; world records what you asked for; commits reconcile the difference.
The verb set
| Command | Effect |
|---|---|
| apk update | refresh repository indexes |
| apk add pkg [pkg...] | install, then commit |
| apk del pkg | remove package and constraint |
| apk upgrade | update tracked packages to newest compatible |
| apk fix | repair/reinstall inconsistent pieces without touching world |
| apk search term | query available by name/description |
| apk info [pkg] | installed-package details (files, deps, description) |
| apk list --installed | everything currently present |
| apk policy pkg | which repositories offer which versions |
| apk dot pkg | render dependency graph as graphviz |
Searching and evaluating before installing
apk search ripgrep
apk policy ripgrep # repo versions offered
apk info ripgrep # after install: what got pulled inPreview habit: test unfamiliar packages on a throwaway VM or container first, or review dependency output before admitting a commit on production machines.
Repositories configuration
/etc/apk/repositories lists sources, one per line.
cat /etc/apk/repositories
apk update # mandatory after edits
apk policy curl # confirm availability post-editAdding random unsigned mirrors converts your package manager into arbitrary-code deployment. Stick to official repositories or mirrors you operate and sign yourself.
Upgrading discipline
apk update
apk upgrade --dry-run # preview
apk upgradeKernel upgrades deserve the dedicated kernel-chapter ritual: verify the installed image, update bootloader config, retain the prior kernel entry, deliberate reboot while calm.
Removing things properly
apk del ripgrep
apk info # confirm landscapeWhy APK suits the DIY thesis
Everything happens locally from signed repositories you can audit, cache, pin, and replicate offline. No phone-home, no subscription entitlement, no rented update channel; the same freedom arguments underpinning Saphira itself. Your package toolchain belongs to you.
Prove it works: confident stewardship
system upgraded across a release boundary with a documented rollback path, rehearsed on a scratch machine before production trust was placed.
world: the file that is your system
Verified from the installed apk manual (FILES section): /etc/apk/world holds the 'top level requirements and constraints'; the packages YOU asked for, as opposed to everything merely pulled in as dependencies. This one text file is the identity of the installation.
cat /etc/apk/world
# a typical router's world:
# akadata-baselayout
# openrc
# dhcpcd
# nftables
# openvswitch
# wireguard-tools
# haproxy
# The full dependency closure is computed FROM world:
apk info | wc -l # everything present
wc -l /etc/apk/world # everything YOU choseThis is why apk del is honest removal and why a messy system can be re-derived: world is declarative intent, the installed set is its consequence. Version pinning lives here too; apk add haproxy=3.2.4-r0 rewrites the entry with an exact constraint, and later apk upgrade respects it.
Back up /etc/apk/world with your configs. Combined with your repository URL it reproduces the package layer of a machine almost exactly; a documented recovery path beats a forensic rebuild.
Forensics: who owns this file, what changed here
Verified against the installed apk-tools: two commands answer the questions every admin eventually asks at 02:00.
apk info --who-owns /usr/bin/sed # which package owns a file?
apk audit /etc # files changed since install (config drift)
apk version -l '<' # packages with available upgrades
apk policy haproxy # which repo offers which candidate- --who-owns (-W) settles 'where did this binary come from' instantly; including the uncomfortable cases.
- audit compares installed files against the package checksums: modified configs show as such, which is exactly what you want to review before upgrades or incident response.
- version -l '<' lists everything behind the repository; the honest TODO list behind 'apk upgrade'.
Merging .apk-new files with mergetool
Upgrades never silently overwrite a configuration you edited: where your file differs from the packaged default, APK leaves the incoming version beside it as an .apk-new file. Those siblings accumulate quietly, and an unreviewed one means running new software against an old assumption.
saphira-mergetool exists for that exact moment. It walks the pending .apk-new files and merges each one against your edited configuration, so the review happens deliberately instead of whenever something breaks. Run it after upgrades, the same way apk audit frames the before picture.
Did we miss something?
If this page left something unanswered, found an error, or there is another subject you would like documented, tell us. Saphira’s documentation grows from real problems people need to solve.
Send feedback or request a new section →
Prefer not to do it yourself?
Everything needed to do the work yourself is documented here and remains free; we charge for human time, not for withholding knowledge. Sometimes the missing resource is simply time. The same people who build Saphira can provide paid professional help with implementation, migration, troubleshooting and administration.