packaging

Installers, OS packages, images, and service wiring for CopperlineOS (Phase‑0).
This repo builds and ships everything you need to install and run the CopperlineOS services on a Linux host: DEB/RPM packages, Flatpak/AppImage for demos, container images, systemd units, and udev rules.

TL;DR: one place to produce compositord, copperd, blitterd, and audiomixerd as first‑class system services, with sane defaults and repeatable builds.

---

Scope

• OS packages: Debian/Ubuntu (.deb), Fedora/RHEL/openSUSE (.rpm).
• App bundles: Flatpak (sandboxed demo), AppImage (portable demo).
• Containers: multi‑arch images (amd64/arm64) for dev & CI.
• System integration: systemd service/target units, socket paths, users/groups, udev rules.
• Release assembly: a manifest pins component versions/commits and feeds all builders.
• Signing: docs/scripts for key management (public keys only in this repo).

Out of scope: private keys, distro submission paperwork.

---

Layout

packaging/
├─ manifests/
│  └─ copperline-manifest.yaml     # pin versions/commits per component
├─ deb/                            # debhelper + dh-cargo glue (or cargo-deb)
├─ rpm/                            # spec files + macros (or cargo-rpm)
├─ flatpak/                        # org.copperline.CopperlineOS.yml (demo)
├─ appimage/                       # AppDir + recipe
├─ containers/
│  ├─ Dockerfile.compositord
│  ├─ Dockerfile.copperd
│  ├─ Dockerfile.blitterd
│  └─ Dockerfile.audiomixerd
├─ systemd/
│  ├─ copperline.target            # wants the core services
│  ├─ compositord.service
│  ├─ copperd.service
│  ├─ blitterd.service
│  └─ audiomixerd.service
├─ udev/
│  └─ 70-copperline.rules          # render-node access, input permissions
├─ etc/                            # default configs (/etc/copperline/*.toml)
│  ├─ compositord.toml
│  ├─ copperd.toml
│  ├─ blitterd.toml
│  └─ audiomixerd.toml
├─ scripts/
│  ├─ build-all.sh                 # build crates from pinned sources
│  ├─ stage-rootfs.sh              # assemble staging tree for packages
│  ├─ make-deb.sh / make-rpm.sh    # wrapper scripts
│  └─ sync-binaries.sh             # pull from GitHub Releases (alt path)
├─ keys/                           # *public* signing keys (ASCII‑armored)
└─ README.md

---

Supported targets (initial)

Target	Status	Notes
Debian 12/13	✅	deb/ via debhelper + dh-cargo (or cargo-deb for MVP)
Ubuntu 24.04	✅	same as Debian
Fedora 40/41	✅	rpm/ via rpmbuild (or cargo-rpm for MVP)
Flatpak	✅ (demo)	sandboxed; KMS access limited; good for trying UI
AppImage	✅ (demo)	portable binary for quick local runs
Containers	✅	great for CI and headless test rigs

---

Runtime model (defaults)

• Socket paths: /run/copperline/*.sock (world‑readable no; group‑readable yes).
• System user/group: copperline:copperline created by packages.
• DRM access: prefer render nodes (/dev/dri/renderD*) for GPU work; for KMS, run with seat management (seatd/logind).
• Audio: ALSA device per distro defaults; rtkit for RT scheduling if available.

udev rule (excerpt)

70-copperline.rules (installed to /etc/udev/rules.d):

KERNEL=="renderD*", SUBSYSTEM=="drm", GROUP="copperline", MODE="0660"
KERNEL=="midi*", SUBSYSTEM=="snd", GROUP="copperline", MODE="0660"

(Tweak groups to fit your distro’s policy; some use video/audio groups.)

---

systemd services (MVP)

systemd/copperline.target

[Unit]
Description=CopperlineOS core services
Wants=compositord.service copperd.service blitterd.service audiomixerd.service

systemd/compositord.service

[Unit]
Description=CopperlineOS Compositor (Vulkan/KMS)
After=network.target
Requires=systemd-udevd.service
Wants=seatd.service

[Service]
Type=simple
User=copperline
Group=copperline
Environment=COMPOSITORD_SOCKET=/run/copperline/compositord.sock
Environment=COMPOSITORD_BACKEND=kms
Environment=COMPOSITORD_MODE=1920x1080@60
RuntimeDirectory=copperline
ExecStart=/usr/bin/compositord
Restart=on-failure
# Consider AmbientCapabilities=CAP_SYS_TTY_CONFIG for KMS in special cases

[Install]
WantedBy=multi-user.target

systemd/copperd.service

[Unit]
Description=CopperlineOS Timeline Engine
After=compositord.service

[Service]
Type=simple
User=copperline
Group=copperline
Environment=COPPERD_SOCKET=/run/copperline/copperd.sock
ExecStart=/usr/bin/copperd
Restart=on-failure

[Install]
WantedBy=copperline.target

(Similar units ship for blitterd and audiomixerd.)

Overriding settings

Use drop‑ins: systemctl edit compositord then add, for example:

[Service]
Environment=COMPOSITORD_BACKEND=wayland
Environment=COMPOSITORD_OUTPUT=HDMI-A-1

---

Manifest‑driven builds

All package builders read a single manifest to decide which commits/tags to build:

# manifests/copperline-manifest.yaml
version: 0
components:
  compositord: { repo: https://github.com/CopperlineOS/compositord, ref: v0.1.0 }
  copperd:     { repo: https://github.com/CopperlineOS/copperd,     ref: v0.1.0 }
  blitterd:    { repo: https://github.com/CopperlineOS/blitterd,    ref: v0.1.0 }
  audiomixerd: { repo: https://github.com/CopperlineOS/audiomixerd, ref: v0.1.0 }
  tools:       { repo: https://github.com/CopperlineOS/tools,       ref: v0.1.0 } # for portctl, etc.

The scripts/build-all.sh clones at those refs, builds release binaries, and stages them under build/stage/ like so:

/usr/bin/compositord
/usr/bin/copperd
/usr/bin/blitterd
/usr/bin/audiomixerd
/etc/copperline/*.toml
/usr/lib/systemd/system/*.service
/etc/udev/rules.d/70-copperline.rules

---

Building packages

Debian/Ubuntu (.deb)

Option A: debhelper + dh-cargo

sudo apt install build-essential debhelper dh-cargo pkg-config libdrm-dev
./scripts/build-all.sh
./scripts/stage-rootfs.sh
cd deb && debuild -b -us -uc
# Outputs: ../copperline_0.1.0_amd64.deb etc.

Option B: cargo‑deb for each crate (fast MVP)

cargo install cargo-deb
./scripts/build-all.sh  # or build each project with cargo-deb
# Each project: cargo deb --no-build --manifest-path path/to/Cargo.toml --install ./build/stage/usr/bin/<name>

Fedora/RHEL/openSUSE (.rpm)

Option A: rpmbuild

sudo dnf install rpm-build rpmdevtools cargo libdrm-devel
./scripts/build-all.sh && ./scripts/stage-rootfs.sh
rpmbuild -bb rpm/copperline.spec   --define "_topdir $PWD/build/rpm"   --define "version 0.1.0"

Option B: cargo‑rpm

cargo install cargo-rpm
# Then use cargo rpm init/build in each project (see rpm/README)

Flatpak (demo sandbox)

flatpak-builder --user build flatpak/org.copperline.CopperlineOS.yml --install
flatpak run org.copperline.CopperlineOS

(KMS access is limited in Flatpak; use Wayland/X11 backend for demos.)

AppImage (portable demo)

./appimage/make-appimage.sh  # wraps binaries into an AppDir and packs an AppImage

Containers

# Build and tag multi-arch images (requires buildx)
docker buildx build -f containers/Dockerfile.compositord --platform linux/amd64,linux/arm64   -t ghcr.io/copperlineos/compositord:0.1.0 --push .

---

Reproducibility & signing

• Set SOURCE_DATE_EPOCH in builders for deterministic timestamps.
• Embed build metadata via environment (commit SHA, dirty flag).
• Signing: Debian repo signing (apt), RPM GPG signing — keep private keys off-repo.
  • Place public keys in keys/ and document how to trust them.

---

SELinux/AppArmor

• Ship permissive profiles initially with clear labels; encourage users to opt‑in and report denials.
• Target least privilege: no root, no broad caps; prefer device ACLs via udev + groups.

---

Uninstall / cleanup

# Debian/Ubuntu
sudo apt remove copperline

# Fedora/RHEL
sudo dnf remove copperline

# Extras
sudo systemctl disable --now copperline.target
sudo rm -f /etc/udev/rules.d/70-copperline.rules

(Actual package names may split per service; adjust accordingly.)

---

Troubleshooting

• Permission errors: ensure user is in copperline (or video/audio) groups; re‑login.
• No KMS: set COMPOSITORD_BACKEND=wayland|x11 and run under a desktop session.
• Audio xruns: enable rtkit and confirm audiomixerd got RT scheduling.
• Sockets missing: check service logs (journalctl -u compositord).

---

License

Build scripts and packaging files are licensed under Apache‑2.0 OR MIT.

---

See also

• Core services: compositord · copperd · blitterd · audiomixerd
• Protocol & clients: ports · sdk-rs · sdk-c
• Docs & site: docs · website