Files

T

xavierkandCommandCodeBot c45b07003a docs(migration): add make-install-to-package runbook and no-move continuity tests for #50

Migration runbook at docs/install/migrate-from-makeinstall.md covers the
mandatory remove-then-install path, why over-install is forbidden, no-move
continuity guarantees, and reset-to-dormant expectations.

Acceptance criteria MG-1 through MG-4 added to the install criteria section.

Containerized tests verify no-move continuity: existing group makes sysusers
a no-op, existing store dir makes tmpfiles a no-op, hand-edited config
survives as a non-database file, and store schema is caught up by the
upgrade-path migration. Dead code from a prior merge removed.

Co-authored-by: CommandCodeBot <noreply@commandcode.ai>

2026-09-03 12:56:43 +05:30

4.6 KiB

Raw Blame History

Migrating from make-install to packages

This runbook covers the transition from a sudo make install system to the native deb or rpm package. Packages are the primary delivery; make install remains as the dev fallback. The two deliveries are mutually exclusive per machine.

Why over-install is forbidden

Installing a package over a make-install system silently breaks things:

Stale admin units shadow vendor units. make install places fenris-collect.timer and fenris-collect.service in /etc/systemd/system/. The package installs them in /usr/lib/systemd/system/ (vendor placement). Systemd loads admin units first — the stale copy takes precedence, and the package update never reaches the running system.
The local wrapper shadows the package wrapper. make install places the fenris wrapper at /usr/local/bin/fenris. The package places it at /usr/bin/fenris. The shell finds /usr/local/bin first on PATH — the old checkout-relative wrapper runs instead of the package wrapper.

Neither condition is reversible by reinstalling the package. The only safe path is remove-then-install.

Pre-migration checklist

Confirm no monitoring period is actively running that you want to preserve across the gap:
```
fenris status
```
The migration resets the system to dormant (see No-move continuity below). You opt back in with fenris monitor resume.
If you have hand-edited configuration at /etc/fenris/fenris.conf, note it. The config survives the migration in place (see below).

Remove step

sudo make uninstall

This performs the sanctioned disable (fenris-monitor disable --now), closing the current monitoring period as user_disabled. It then removes all make-install artifacts: the venv at /opt/fenris, the wrapper at /usr/local/bin/fenris, the helpers at /usr/libexec/fenris/, the units in /etc/systemd/system/, and the polkit policy. The placement manifest at /var/lib/fenris/manifest.txt is removed.

What survives the remove:

/var/lib/fenris/observations.db (and WAL sidecars, .bak) — the observation store
/var/lib/fenris/ directory itself — root-written, group-read
/etc/fenris/fenris.conf — your hand-written configuration
The fenris system group — created by groupadd -f during make-install
Journal entries — age out naturally

Install step

sudo apt install fenris       # Debian/Ubuntu
sudo dnf install fenris       # Fedora

The package installs into its own layout without touching the surviving store, config, or group.

No-move continuity

These invariants are verified by the containerized acceptance tests (issue #50):

Asset	Make-install state	Package post-install	Mechanism
`fenris` group	Exists (`groupadd -f`)	Unchanged	`systemd-sysusers` is a no-op when the group already exists
`/var/lib/fenris` directory	Exists (mode 2750, root:fenris)	Unchanged	`systemd-tmpfiles --create` is a no-op when the directory already exists
`observations.db` + sidecars	Present from prior monitoring	Unchanged, never owned by the package	Package owns the directory only; store contents are never ghosted
`/etc/fenris/fenris.conf`	Hand-edited device selector	Survives in place; package default lands as `.dpkg-new` / `.rpmnew`	dpkg conffile / rpm `%config(noreplace)` semantics
Store schema	Version from prior Fenris release	Caught up by the upgrade-path migration	`postinst` / `%post` runs `migrate_to_latest()` on upgrade

The package detects the make-install system has been removed by the absence of the two markers:

/var/lib/fenris/manifest.txt (the placement manifest)
/etc/systemd/system/fenris-collect.timer (pre-manifest make installs)

If either marker exists, the package installation aborts with a pointer to this runbook.

Reset-to-dormant

make uninstall's sanctioned disable closes the open monitoring period as user_disabled. After the package install, the system is dormant — the timer is installed but disabled, nothing is running, no monitoring period is open.

To resume monitoring:

fenris monitor resume

This is the sanctioned opt-in. It enables the timer and opens the first monitoring period in one step. The migration costs at most one short sample gap (the interval between make uninstall and fenris monitor resume), honestly recorded in the endurance timeline.

Verification

After migration, confirm the package is correctly installed:

fenris status

The status command should show the dormant state: timer disabled, no active monitoring period, and the observation store intact from the prior make-install system.

4.6 KiB Raw Blame History