Debian packaging via per-component Makefiles + fpm

[runleveldev]

Summary

Introduces Debian packaging for the three deployable components using per-component Makefiles + fpm publishes them to GitHub Releases as a flat APT repository, and rebuilds the container images to install those packages. The same component build commands are reused by local development (compose), the images, and CI.

Packages

Directory	Package	Arch	Contents
create-a-container/	opensource-server	amd64	Manager web app, job runner, systemd units
mie-opensource-landing/	opensource-docs	all	Prebuilt documentation site
pull-config/	opensource-agent	all	pull-config engine, instances, error pages

Everything installs under the /opt/opensource-server prefix (matching existing runtime references). opensource-server depends on opensource-agent + opensource-docs (the manager's rendered nginx config serves their files).

What's included

• Per-component Makefiles with a uniform contract — deps, build (default goal), install (DESTDIR/PREFIX-aware), dev, and deb/rpm/apk. VERSION is derived from git tags inline. The top-level Makefile delegates to all three and collects packages into dist/. make clean removes staging, build outputs, and built packages.
• nfpm.yaml per component — packages the staged tree via ${DESTDIR} interpolation (expand: true), so the config stays DRY and supports any DESTDIR. opensource-server ships its systemd units and enables them via a postinstall script; the logrotate drop-in is a config file. Distro-integration files live under create-a-container/contrib/.
• images/builder — runs make deb (Node.js, uv, nfpm) to produce the packages as an artifact-only stage. The docs/agent/manager images install them via RUN --mount=from=builder (no extra layers) and stage the release APT source so apt upgrade tracks future releases.
• CI — release.yml (on v* tags) builds the packages, generates flat-repo metadata (Packages, Packages.gz) and *_latest.deb aliases, and attaches them to the release. build-images.yml now tags :latest only on non-prerelease releases.
• Developer docs — new developers/release-pipeline.md plus stale-doc refreshes.
• LICENSE — Apache-2.0.

Behavioral changes worth noting

• container-creator-init.service (provisions a local PostgreSQL) moved from the package to the manager image, since the package only suggests postgresql and works with a remote database too. The package ships container-creator + job-runner.
• Fixed a latent unit bug: the access-log directory is created on demand via the correct LogsDirectory directive (was the invalid LogDirectory, which systemd silently ignored).
• :latest images now track non-prerelease releases instead of every merge to main.

Install / update (admins)

# One-off:
curl -fsSLO https://github.com/mieweb/opensource-server/releases/latest/download/opensource-agent_latest.deb
apt install -y ./opensource-agent_latest.deb

# Or as an apt source (also baked into the images):
echo 'Types: deb
URIs: https://github.com/mieweb/opensource-server/releases/latest/download/
Suites: ./
Trusted: yes' > /etc/apt/sources.list.d/opensource-server.sources
apt update && apt install opensource-server

Migrating an existing (non-package) system to packages

Existing deployments run from an in-place tree at /opt/opensource-server
(a git checkout built with the old make install), with systemd units in
/etc/systemd/system/. The packages own files under /opt/opensource-server/<component>/
and ship units in /usr/lib/systemd/system/, so the old in-place files must be
removed first or dpkg will refuse to overwrite files it does not own.

The good news: the package layout uses the same prefix and the same config
paths, so stateful config is preserved across the switch:

• /etc/default/container-creator (manager DB credentials) — kept; the packaged
  container-creator/job-runner units read the same file, so the existing
  database keeps working (local or remote).
• /etc/pull-config.d/* and /etc/cron.d/pull-config (agent) — these are
  conffiles in the package; local customizations are preserved on install.
• /var/log/opensource-server — recreated on demand by the unit's LogsDirectory.

Steps (run on the target container/host)

# 1. Stop the running services.
systemctl stop container-creator job-runner || true

# 2. Back up the config you want to keep (paranoia; the package preserves these).
cp -a /etc/default/container-creator /root/container-creator.env.bak 2>/dev/null || true
cp -a /etc/pull-config.d /root/pull-config.d.bak 2>/dev/null || true

# 3. Remove the old in-place units and disable them so they don't shadow the
#    packaged units in /usr/lib/systemd/system.
rm -f /etc/systemd/system/container-creator.service \
      /etc/systemd/system/job-runner.service
systemctl daemon-reload

# 4. Remove the old in-place tree so the package can own /opt/opensource-server.
#    The old install put the whole repo (or a bind mount) here; the package only
#    writes to component subdirs, so clear the lot. Config lives in /etc and is
#    untouched (do NOT remove /etc/default/container-creator or /etc/pull-config.d).
rm -rf /opt/opensource-server

# 5. Add the release APT source and install the package(s) for this role.
#    `releases/latest/download/` serves the newest non-prerelease release. To
#    pin a specific release (or a prerelease, which `latest` skips), use the tag
#    URL instead, e.g. https://github.com/mieweb/opensource-server/releases/download/2026.6.3/
cat >/etc/apt/sources.list.d/opensource-server.sources <<'EOF'
Types: deb
URIs: https://github.com/mieweb/opensource-server/releases/latest/download/
Suites: ./
Trusted: yes
EOF
apt update

# Manager (pulls in opensource-agent + opensource-docs automatically):
apt install -y opensource-server
# Agent-only node:
#   apt install -y opensource-agent
# Docs-only node:
#   apt install -y opensource-docs

Notes:

• On a manager, the local PostgreSQL provisioning unit
  (container-creator-init.service) is part of the image, not the package. On
  a bare-metal/LXC host that already has /etc/default/container-creator, it is
  not needed — the existing DB config is reused. For a brand-new manager without
  that file, provision the database and write /etc/default/container-creator
  yourself (local or remote), then start container-creator.
• After this, updates are just apt update && apt upgrade (the source tracks the
  latest non-prerelease release).
• If dpkg still reports a conflict on a specific file under
  /opt/opensource-server, a leftover from the old tree was missed — remove that
  path and re-run apt install.

Verification

• All three packages build via make deb; inspected metadata, deps, conffiles, scripts, modes, and the node_modules/.bin/sequelize symlink.
• Built and boot-tested all three images against the real release source: docs serves :80, agent has pull-config + cron, manager has all units active (incl. the image-owned init), app on :3000, DB provisioned, /var/log/opensource-server auto-created, and apt update works inside the final image.
• Migration tested end-to-end: launched the pre-package manager image (:main), seeded DB state (a marker row; 53 applied migrations), then ran the migration steps above against the 2026.6.3 prerelease (via its tag URL). Result: apt install opensource-server succeeded with no dpkg file conflicts, units moved to /usr/lib/systemd/system and were enabled + restarted by the postinstall, the app returned 200, and all DB state and /etc/default/container-creator credentials were preserved (marker row intact, migration count unchanged, password identical). Agent (pull-config/cron/nginx/dnsmasq), docs site, and error-pages were all functional afterward.

Notes / follow-ups

• The bootstrap v2026.6.2 release needed a manual Packages.gz upload (GitHub rejects the empty uncompressed Packages; apt uses the .gz). Future releases generate both automatically.
• GPG signing of the APT repo is out of scope (Trusted: yes for now).

Draft for review — happy to split into smaller PRs if preferred.

[Copilot]

Pull request overview

This PR introduces a packaging-and-release pipeline that builds the three deployable components as OS packages (via per-component Makefiles + fpm), publishes them to GitHub Releases as a flat APT repository, and updates the Docker images to install those packages instead of copying/building the repo in-image.

Changes:

• Added per-component packaging Makefiles (+ fpm metadata) and a shared package-version helper derived from git describe.
• Added a builder image and Docker Bake wiring so docs/agent/manager images install .deb artifacts produced by the builder stage.
• Added/updated CI + developer docs to publish release assets (debs + Packages/Packages.gz) and document the release pipeline.

Reviewed changes

Copilot reviewed 31 out of 34 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
pull-config/Makefile	New component Makefile: stages pull-config + instances + error pages and builds packages via fpm.
pull-config/install.sh	Removes the legacy imperative install script (replaced by Makefile install).
pull-config/.gitignore	Ignores component packaging artifacts (.pkg/, built packages).
pull-config/.fpm	Defines opensource-agent package metadata and Debian dependencies.
package-version	New helper to derive format-specific package versions from git tags/describe output.
mie-opensource-landing/zensical.toml	Adds “Release Pipeline” to docs navigation.
mie-opensource-landing/Makefile	New component Makefile to build/stage docs site and package with fpm.
mie-opensource-landing/docs/developers/release-pipeline.md	New developer documentation describing packaging, images, and release workflow.
mie-opensource-landing/docs/developers/pull-config.md	Updates pull-config docs to reflect Makefile-based build/packaging.
mie-opensource-landing/docs/developers/docker-images.md	Updates image docs to describe installing packaged payloads via builder context.
mie-opensource-landing/.gitignore	Ignores docs packaging artifacts and built packages.
mie-opensource-landing/.fpm	Defines opensource-docs package metadata.
Makefile	Replaces old install targets with delegation to component Makefiles and adds package collection to dist/.
LICENSE	Adds Apache-2.0 license text.
images/opensource-server.sources	Adds an APT source file pointing at releases/latest/download/ (trusted).
images/manager/Dockerfile	Installs packaged manager/docs artifacts from builder output; enables init unit; keeps PG install.
images/manager/container-creator-init.service	Adjusts init sequencing and runs sequelize migrations + seeds on first boot.
images/docs/Dockerfile	Installs nginx + opensource-docs from builder output; stages the APT source file.
images/docker-bake.hcl	Adds a builder target and wires it as a context for docs/agent/manager builds.
images/builder/Dockerfile	New artifact-only image that builds the three .deb packages into /dist.
images/agent/Dockerfile	Installs opensource-agent package from builder output; stages the APT source file.
create-a-container/Makefile	New component Makefile: builds client bundle, stages runtime tree + units + logrotate, packages with fpm.
create-a-container/contrib/systemd/job-runner.service	Adds packaged job-runner systemd unit.
create-a-container/contrib/systemd/container-creator.service	Fixes log directory creation by using LogsDirectory.
create-a-container/contrib/preremove.sh	Adds pre-removal script to stop/disable units on package removal.
create-a-container/contrib/postinstall.sh	Adds post-install script to enable and (when applicable) restart units.
create-a-container/contrib/opensource-server.logrotate	Adds packaged logrotate config for /var/log/opensource-server/*.log.
create-a-container/.gitignore	Ignores component packaging artifacts and built packages.
create-a-container/.fpm	Defines opensource-server package metadata, deps, scripts, and conffile.
compose.yml	Tweaks dev install commands for create-a-container (server deps omit dev; client deps installed explicitly).
.gitignore	Ignores top-level dist/ artifacts.
.github/workflows/release.yml	New workflow: builds packages via bake, generates Packages/Packages.gz, uploads to the release.
.github/workflows/build-images.yml	Updates triggers and “latest” tagging behavior to align with non-prerelease releases.
.dockerignore	Updates ignored build outputs; intends to ignore packaging artifacts.

[cmyers-mieweb]

LGTM