Debian packaging for the Calaos-OS packages. Calaos-OS is the Debian (bookworm) based distribution of the Calaos home automation suite. Most packages here do not ship the application itself: they ship a systemd unit plus helper scripts that run an OCI container with podman, and pull the container image on install.
Each top-level directory is one source package with its own debian/ and
Makefile. The directory name is what you pass to the build; the Debian
package name is in debian/control and can differ.
| Directory | Package | What it is | Default image / source |
|---|---|---|---|
calaos-meta |
calaos |
Meta package pulling the whole Calaos-OS stack | none |
calaos-keyring |
calaos-keyring |
APT sources (/etc/apt/sources.list.d/calaos.list) and the archive signing key; the key is downloaded from deb.calaos.fr at build time |
none |
calaos-server |
calaos-server |
Calaos main server (container) | ghcr.io/calaos/calaos_base:$(VERSION) |
calaos-home |
calaos-home |
Calaos Home touchscreen GUI (container) | ghcr.io/calaos/calaos_home:$(VERSION) |
calaos-web-app |
calaos-web-app |
Prebuilt static web UI into /usr/share/calaos/webapp, mounted read-only into the server container |
tarball from the calaos/calaos-web-app GitHub release |
envoy |
calaos-envoy |
Enphase Envoy service (container) | ghcr.io/raoulh/envoy:$(VERSION) |
grafana |
calaos-grafana |
Grafana (container) | docker.io/grafana/grafana:$(VERSION) |
haproxy |
calaos-haproxy |
HAProxy (container) | docker.io/library/haproxy:$(VERSION)-alpine |
hue2mqtt |
calaos-hue2mqtt |
Philips Hue to MQTT bridge (container) | ghcr.io/calaos/hue2mqtt:$(VERSION) |
influxdb |
calaos-influxdb |
InfluxDB (container) | docker.io/library/influxdb:$(VERSION)-alpine |
mosquitto |
calaos-mosquitto |
Mosquitto MQTT broker (container) | docker.io/library/eclipse-mosquitto:$(VERSION) |
zigbee2mqtt |
calaos-zigbee2mqtt |
Zigbee2MQTT (container) | docker.io/koenkk/zigbee2mqtt:$(VERSION) |
All packages are Architecture: all. Container packages depend on podman
and calaos-container. calaos-container, calaos-ddns and the remote UI
packages are not built here; the keyring points at their own apt
repositories (see calaos-keyring/calaos.list).
How the container packages work:
Makefilebuildwritescontainer.source(IMAGE_SRC=...,SERVICE_NAME=...), installed as/usr/share/calaos/<package>.source.- The systemd unit loads that file as
EnvironmentFileand starts the container (start_calaos_server,start_calaos_home,start_z2mqtt, or podman directly in the unit). postinstcallspull_calaos_image, a helper that is not defined in this repository (presumably provided by thecalaos-containerdependency).*_prescripts (haproxy, mosquitto, hue2mqtt, envoy, zigbee2mqtt) create default config under/mnt/calaos/...and config templates go to/usr/share/calaos/conf-template/(envoy, hue2mqtt).- Units are installed enabled for calaos-server, calaos-home, haproxy and
mosquitto; envoy, grafana, hue2mqtt, influxdb and zigbee2mqtt use
--no-enable.
Builds run in a Debian bookworm container (image calaos-os-builder, defined
by Dockerfile: devscripts, debhelper, lintian, fakeroot, ...). Docker is the
only host requirement.
make # list commands
make docker-init # (re)build the builder image
make build-calaos-server PKGVERSION=4.5.0
make build-grafana PKGVERSION=11.6.0 IMAGE_SRC=docker.io/grafana/grafana:11.6.0
make docker-shell # shell in the builder
build-<dir> runs /build_deb <dir> <PKGVERSION> <IMAGE_SRC> in the
container (privileged, repo mounted at /src and /work). build_deb:
- converts the first
-of the version to~(e.g.3.0.2-dev.0becomes3.0.2~dev.0); - replaces the
1.2.3placeholder indebian/changelogand theVERSIONdefault in the packageMakefile, andIMAGE_SRCif one was given; - runs
apt-get build-dep,dpkg-buildpackage -us -uc -bandlintian; - runs
make cleanand moves the.debtopkg/at the repo root.
PKGVERSION is required. NOCACHE=1 forces a rebuild of the image without
Docker cache. The .deb files are unsigned; the apt repository does the
signing.
Nothing is published by a push or a pull request: there is no push trigger.
Two GitHub Actions workflows build and release:
.github/workflows/build_deb.yml: triggered by arepository_dispatchevent of typebuild_debwithclient_payloadfieldspkgname,version,image_src,prerelease. Used to trigger builds from other repositories..github/workflows/build_deb_manual.yml:workflow_dispatchwith inputspkgname(a choice list),version,image_src(required for a package that has an image),prerelease.
Both run make build-<pkgname> PKGVERSION=... IMAGE_SRC=..., upload pkg/*.deb
as a workflow artifact, create a GitHub Release tagged <pkgname>-<version>
(with the .deb attached), then call a webhook (DEB_REPO_WEBHOOK_URL) to
refresh the apt repository. Secrets used: CALAOS_REL_TOKEN,
DEB_REPO_WEBHOOK_URL, DEB_REPO_WEBHOOK_SECRET. The apt repository itself
(https://deb.calaos.fr/calaos/pkgdebs, suite bookworm, as configured in
calaos-keyring/calaos.list) is managed outside this repository. It files a
GitHub prerelease under the pre-releases component and any other release
under releases; the keyring only lists releases.
The Calaos OS version shown on a box is the version of the calaos meta
package (calaos-meta). It is calendar based:
| Channel | Format | Example |
|---|---|---|
| stable | YYYY.MM, or YYYY.MM.N (N >= 1) for another release in the same month |
2026.11, 2026.11.1 |
| dev | YYYY.MM~dev.M, or YYYY.MM.N~dev.M before YYYY.MM.N (the git tag uses -dev.M) |
2026.12~dev.0, 2026.11.1~dev.0 |
Bump it only when a set of component releases is published, by running the
Release Calaos OS workflow (.github/workflows/release_calaos_os.yml,
Actions tab, from main) with the channel and, optionally, the version.
Left empty, the version is computed from the UTC month of the run and from
the calaos versions already in the apt indexes (step 2):
- stable:
YYYY.MM, or the next.N(2026.11.1,2026.11.2...) once a stable of the month exists; - dev: the stable that would be computed, then
~dev.Mwith M one above the highest pre-release of that base, from 1 (2026.11~dev.1,2026.11~dev.2; after the stable2026.11,2026.11.1~dev.1).
A version typed in wins over the computation. The version, the channel and
dry_run are shown at the top of the run summary and in the logs; when
prepare refuses the version, the summary shows its error message instead.
The apt indexes lag the publish webhook. Right after a release, wait for the
index to be updated before starting the next run: a run that does not see the
release yet computes the same version again (the existing
calaos-meta-<version> tag then stops it, so nothing is published twice), and
a dev run that does not see the new stable yet can compute a ~dev.M below
that stable, which no dev box would install. Either
way the workflow then:
- refuses a version that does not match the channel format, or that is not
strictly greater (
dpkg --compare-versions) than the latestcalaospublished in the channel; - reads the apt indexes of every repository in
calaos-keyring/calaos.list(componentreleasesfor stable,releasesandpre-releasesfor dev, so that a stable release newer than every pre-release still wins), and takes the highest version of each package; when the arches disagree, it keeps the lowest of the per-arch highest versions, so the pin can be met on every arch that publishes the package; - pins every
calaos-*entry ofcalaos-meta/debian/controlto(>= <that version>), and writes a changelog entry listing those versions, which is also the release note;olaandchronystay unversioned; - builds the deb, creates the release
calaos-meta-<version>(a prerelease for dev) and refreshes the apt repository.
A calaos-* package listed in Depends but absent from the channel stops
the release. dry_run builds the deb as an artifact and publishes nothing:
use it to check the generated Depends first. A dev release should be
started once the component prereleases it needs are in the apt repository;
a stable one once their stable releases are.
If the GitHub release is created but the apt refresh step fails, any rerun
with the same version stops on the existing tag, "Re-run failed jobs"
included (it reruns the whole job). The release is already in place: trigger
the apt repository webhook by hand, or release the next version (.N+1, or
~dev.M+1).
The same steps run locally, without network, from fetched indexes:
./calaos_os_release fetch dev calaos-keyring/calaos.list apt-index
./calaos_os_release prepare dev 2026.12~dev.0 apt-index calaos-meta notes.md
./calaos_os_release prepare dev "" apt-index calaos-meta notes.md # computed
./calaos_os_release next dev 2026.11 2026.11 2026.11.1~dev.2 # 2026.11.1~dev.3
make test # offline tests of calaos_os_release, in the builder image
prepare rewrites calaos-meta/debian/{control,changelog} in place: do not
commit the result. prepare only reads the index files of the channel
(<repo>.<component>.<arch>), so an apt-index directory reused from a dev
fetch does not leak pre-releases into a stable release. The generic workflows
do not publish calaos-meta, which would go out without pins:
build_deb_manual.yml does not offer it and build_deb.yml refuses it.
Bump: the version is not stored in the repo. Trigger a build with the new
version (and image_src if the image tag is not $(VERSION)). Edit the
package directory only to change packaging itself.
Add: copy a similar directory (for example mosquitto for a container
service), then:
- adjust
debian/control(Package,Depends),Makefile(PKGNAME, defaultIMAGE_SRC,installtarget), the systemd unit,postinst; - keep the
1.2.3placeholder indebian/changelog, whichbuild_debsubstitutes; - add the directory to the
pkgnameoptions in.github/workflows/build_deb_manual.yml; - add the package to the
Dependsofcalaos-meta/debian/controlif it must be part of a default install, without a version: the Release Calaos OS workflow adds the bound; - test with
make build-<dir> PKGVERSION=0.0.1.
Packaging files declare GPL-3.0+ in each debian/copyright (Calaos Team);
hue2mqtt/debian/copyright additionally carries an MIT notice (Dan
Trickey). There is no top-level LICENSE file.