Overview

bisos.airflow is a BISOS package for managing an Apache Airflow platform (webserver, scheduler, triggerer, database, and DAG development/testing) as a set of BISOS Capability Bundles (CBS/CBM) and systemd-planted Command Services. It is under active initial development; this README is a starting point and will be expanded as the package matures.

The remainder of this document is carried over from bisos.dockerProc *(the starting-point template this package was copied from) and still describes docker/podman container lifecycle management. It will be rewritten to describe bisos.airflow as the package develops.*

Capability Materialization

The figure below shows the top-down layering of airflow.here’s Capability Materialization: the planted CBM pointer leaf (/bisos/platform/sys/cbm/collective/hereWeb/airflow/cbmProc.spcs) points to (and does not duplicate) the CBS (py3/bin/airflow-cbs.pcs), which declares the bundle of airflow-sbom.pcs, the 4 airflow-*-sysd.pcs units, and airflow-assemble.cs. py3/bin/airflowAdmin.cs sits below all of that as the day-to-day admin-facing CS an operator runs against the materialized installation.

Regenerate this figure (after editing py3/images/airflow-graphviz.pcs):

cd py3/images
./airflow-graphviz.pcs --format=all -i ngProcess all

bisos.dockerProc is a python package that uses the PyCS-Framework. It is a BISOS-Capability and a Standalone-BISOS-Package.

Architectural context. bisos.dockerProc is one realization of a general BISOS facility for building walkable trees on top of .spcs (Spread Planted Command Services) — currently the first realization, with bisos.lcnt (LaTeX content), static-web publication, and others planned. The .spcs mechanism itself lives in bisos.csSeed; the tree walker and WalkExampleSpec dataclass live in bisos.fileObj; the architecture that composes them (three-box layered figure, authoring recipe, canonical references) is documented at `bisos.pycs/spcs/README.org </bisos/git/auth/bxRepos/bisos-pip/pycs/spcs/README.org>`__. This README describes what makes this realization specific — path-anchoring on debian/, per-profile ports, cgroup variants, container-in-container safety, backup workflow, the six-image matrix of the companion bro_dockerfiles tree.

Package Documentation At Github

The information below is a subset of the full of documentation for this bisos-pip package. More complete documentation is available at: https://github.com/bisos-pip/capability-cs

Use Cases

bisos.dockerProc addresses several deployment scenarios in which the usual “one Dockerfile, one docker run line” pattern falls short. If any of the following describes your situation, this package is built for you.

cd bro_dockerfiles/debian/12/confined/vnc/xfce/bisos_deb12-fresh
./dockerProc.spcs -i containerProc_imageBuild
./dockerProc.spcs -i containerProc_instanceUp
./dockerProc.spcs -i containerProc_exec_installRawBisos    # bxGenesis bootstrap inside container
./dockerProc.spcs -i containerProc_instanceVerify
./dockerProc.spcs -i containerProc_fullClean

./ftoBranchProc.spcs -i fto_forwardToLeaves --cmndName=containerProc_exec_installRawBisos

Full Design at a Glance

The figure below captures the full design of bisos.dockerProc — the three execution platforms it spans, the pieces on each, and the flows between them. Part of the design (the Platform Registrar) is not yet implemented and is shown with a dashed border. Scan the legend first, then read the figure.

Legend:

Reading the figure, left to right:

• Container Platform (middle) — the anchor. This is the powerful VM where everything runs. Image identity comes from the leaf directory path in bro_dockerfiles (debian/<release>/<profile>/vnc/xfce/<imageName>/): dockerProc.spcs is planted in confined and privileged leaves; podmanProc.spcs is planted in rootless-sysd leaves. Both delegate to the engine-agnostic seed containerProc-seed.cs, which drives docker or podman according to the leaf’s profile.

• Platform Registrar (middle, dashed) — design-only in this phase. The current implementation derives host-side ports from the leaf path (fixed 2222/2223/… table). This works for one user with one instance per profile. The moment you have multiple users on one VM — or multiple instances of the same image per user — fixed ports collide. The Registrar is the reserved slot for that: a per-user, per-image, per-instance store at /bisos/platform/registrar/dockerProc/<user>/<imageName>/instance0..N/ that assigns and tracks host-side ports. Path gives the image identity; registrar gives the instance identity.

• Two consumers of the registrar (both drawn as blue dashed edges). .spcs reads assigned ports on the platform side to do run / composeUp / verify for the right host-side ports. Remote User reads the same assignments (over ssh) to generate its local .ssh/config LocalForward entries so its ssh client tunnels the right host ports to the right instances.

• Remote User (left) — corporate host, port-22-only. Typical deployment target: a workstation behind corporate networking where everything but outbound port 22 is blocked. The user cannot open VNC/noVNC/SSH-alt ports directly to the platform. Instead, the Remote User’s .ssh/config is populated with LocalForward entries that tunnel the assigned host-side ports through the single port-22 ssh connection. The user then points local ssh/vnc/browser clients at localhost:<forwarded-port>. The .ssh/config entries are a generated artefact: their content comes from the registrar.

• Container Instances (right) — many per user. Each running container exposes the same fixed container-side ports (22 for ssh, 5901 for VNC, 6901 for noVNC). What varies per instance is the host-side mapping. The figure shows image-A / inst0, inst1, image-B / inst0, ... instN as representative — one image can have many instances; a user can have many images.

What is implemented today vs what the figure describes:

• Implemented: image path → .spcs → seed → engine → running container. The dockerProc.spcs and podmanProc.spcs planting, the seed’s build / composeUp / run / verify commands, and podmanHostVerify.cs for host readiness are all in place. Verified on both docker (deb13 privileged sysd, cgroup v1 + v2) and podman (deb13 rootless-sysd).

• Not yet implemented: everything downstream of Platform Registrar. Its shape is fixed in the figure so subsequent multi-tenant work can add it without redesign.

Table of Contents TOC

• Overview

• Capability Materialization

• Package Documentation At Github

• Use Cases

  • RawBisos-Reconstruction — BISOS’s Equivalent of the Common CI/CD Pipeline

  • Reproducible XFCE Desktops on Debian 12 and 13

  • Choosing Among Three Init/Isolation Profiles for the Same Image

  • Multi-Tenant: N Engineers on One Powerful VM

  • Corporate Firewall: Only Port 22 Outbound

  • Path-Derived Configuration Instead of Per-Leaf Config Files

• Full Design at a Glance

• Part of BISOS — ByStar Internet Services Operating System

• bisos.dockerProc is a Command-Only PyCS Facility

• The spcs Pattern: Directory Path as Configuration

  • Companion Repo: brodockerfiles

  • Path-to-parameter Mapping

• Three Init/Isolation Profiles

• Installation

  • Installation With pip

  • Installation With pipx

• Usage

  • Planting a `.spcs`` File in a Leaf Directory <#planting-a-spcs-file-in-a-leaf-directory>`__

  • The Seed Commands: image, instance, verify+status, combined

  • Host Readiness Check: ``podmanHostVerify.cs` <#host-readiness-check-podmanhostverifycs>`__

  • Docker / Podman Installation via `-sbom.pcs`` Files <#docker–podman-installation-via–sbompcs-files>`__

  • Cheat Sheet: ``dockerCmnds.cs` / podmanCmnds.cs <#cheat-sheet-dockercmndscs–podmancmndscs>`__

• Key Files

• Documentation and Blee-Panels

• Support

Part of BISOS — ByStar Internet Services Operating System

Layered on top of Debian, BISOS (By* Internet Services Operating System) is a unified and universal framework for developing both internet services and software-service continuums that use internet services. See Bootstrapping ByStar, BISOS and Blee for information about getting started with BISOS.

BISOS is a foundation for The Libre-Halaal ByStar Digital Ecosystem which is described as a cure for losses of autonomy and privacy in a book titled: Nature of Polyexistentials

bisos.dockerProc is part of BISOS. It is a standalone package that can be used independently of the full BISOS environment.

bisos.dockerProc is a Command-Only PyCS Facility

bisos.dockerProc is a command-line tool. It is a PyCS multi-unit command service. PyCS is a framework that converges development of CLI tools and services. PyCS is an alternative to FastAPI, Typer and Click.

bisos.dockerProc uses the PyCS-Framework to:

1. Provide a seed (containerProc-seed.cs) and two planted command services (dockerProc.spcs for docker leaves, podmanProc.spcs for rootless-sysd leaves) that manage container image build, compose, run, verify, status, and clean.

2. Derive all operating parameters from the leaf directory path in which each .spcs is planted — there are no per-leaf parameter files.

3. Provide standalone helpers: podmanHostVerify.cs (host readiness check for rootless-sysd), dockerProc-sbom.pcs / podman-sbom.pcs (install docker / podman via bisos.sbom), and dockerCmnds.cs / podmanCmnds.cs (cheat sheet of direct-engine invocations).

The core of PyCS-Framework is the bisos.b package (the PyCS-Foundation).

The spcs Pattern: Directory Path as Configuration

/=.spcs= is a general BISOS facility, not a bisos.dockerProc invention. For the architectural picture — three-box layered figure, the WalkExampleSpec typed-data mechanism, the branch-side walker Cmnds (fto_forwardToLeaves, fto_walkRunExternal), and how to build a new consumer — see `bisos.pycs/spcs/README.org </bisos/git/auth/bxRepos/bisos-pip/pycs/spcs/README.org>`__. This section summarises how bisos.dockerProc uses .spcs./

A .spcs file (Spread Planted Command Service) is a thin Python file whose behaviour is entirely context-dependent on the directory in which it is planted. The same file content is spread across many directories; each instance is contextualised by its location. The leaf directory path encodes all parameters — there are no per-leaf configuration files.

Two .spcs variants exist here:

• dockerProc.spcs — planted in leaves that use docker.

• podmanProc.spcs — planted in leaves that use rootless podman.

Both delegate to the same engine-agnostic seed, containerProc-seed.cs, which parses the leaf path (via bisos.dockerProc.containerProc_seedInfo.paramsFromPlantPath()) to derive engine, profile, ports, base image, and cgroup support.

debian/
  <majorRelease>/           12 or 13
    confined/vnc/xfce/      unprivileged, entrypoint.sh init
      <imageName>/
    privileged/vnc/xfce/    --privileged (docker), systemd PID 1
      <imageName>/
    rootless-sysd/vnc/xfce/ rootless podman, systemd PID 1
      <imageName>/

cd /bisos/git/bxRepos/bxObjects
git clone https://github.com/bxObjects/bro_dockerfiles.git

Three Init/Isolation Profiles

The <profile> path segment selects one of three init/isolation profiles:

• confined: unprivileged, no systemd; services (VNC / noVNC / sshd) launched manually by entrypoint.sh.

• privileged: full systemd as PID 1; runs --privileged on docker. Requires the docker-compose.cgv1.yml overlay on cgroup-v1 hosts.

• rootless-sysd: full systemd as PID 1, but unprivileged via rootless podman. Requires cgroup v2 with controller delegation. Motivated by the multi-tenant “N engineers on one shared VM” use case where --privileged is a security dealbreaker.

Rootless-sysd delivers the systemd fidelity of the privileged profile with the security posture of the confined profile. It is the target model for multi-tenant use once the Platform Registrar (see the Full Design at a Glance figure) is implemented.

Installation

You can install bisos.dockerProc with pip or pipx.

pip install bisos.dockerProc

pipx install bisos.dockerProc

Usage

The primary workflow is: clone bro_dockerfiles, cd into a leaf directory, and run dockerProc.spcs or podmanProc.spcs there. The .spcs file is already planted in each leaf as part of the companion repo.

cp $(which dockerProc.spcs) .

cp $(which podmanProc.spcs) .

chmod +x dockerProc.spcs   # or podmanProc.spcs

cd /bisos/git/bxRepos/bxObjects/bro_dockerfiles/debian/13/privileged/vnc/xfce/bisos_deb13-sysd
./dockerProc.spcs

cd /bisos/git/bxRepos/bxObjects/bro_dockerfiles/debian/13/privileged/vnc/xfce/bisos_deb13-sysd
./dockerProc.spcs -i containerProc_imageBuild
./dockerProc.spcs -i containerProc_instanceUp
./dockerProc.spcs -i containerProc_instanceVerify

./dockerProc.spcs -i containerProc_instanceUp   --cgroupVer="v1"
./dockerProc.spcs -i containerProc_instanceDown --cgroupVer="v1"

cd /bisos/git/bxRepos/bxObjects/bro_dockerfiles/debian/13/rootless-sysd/vnc/xfce/bisos_deb13-rootless-sysd
./podmanProc.spcs -i containerProc_imageBuild
./podmanProc.spcs -i containerProc_instanceUp --detach="true"
./podmanProc.spcs -i containerProc_instanceVerify

podmanHostVerify.cs -i verify

dockerProc-sbom.pcs -i sbom_apt_install   # installs docker-ce + friends
podman-sbom.pcs    -i sbom_apt_install    # installs podman + rootless deps

dockerCmnds.cs
podmanCmnds.cs

Key Files

An overview of the relevant files of the bisos.dockerProc package (starting-point template; to be updated to reflect bisos.airflow’s actual files):

• py3/bin/containerProc-seed.cs — the engine-agnostic seed both .spcs delegate to.

• py3/bin/dockerProc.spcs — Spread Planted CS for docker leaves.

• py3/bin/podmanProc.spcs — Spread Planted CS for rootless-sysd leaves.

• py3/bin/podmanHostVerify.cs — host readiness check for rootless-sysd.

• py3/bin/dockerProc-sbom.pcs / py3/bin/podman-sbom.pcs — engine install via bisos.sbom.

• py3/bin/dockerCmnds.cs / py3/bin/podmanCmnds.cs — cheat-sheet CS (symlinked).

• py3/bisos/dockerProc/containerProc_seedInfo.py — Engine=/=Profile=/=CgroupVer enums, ContainerParams dataclass, paramsFromPlantPath() pure function.

• py3/bisos/dockerProc/containerProc_seed.py — atexit registration.

• py3/bisos/dockerProc/containerProc_csu.py — CS command implementations. Cmnds are organized by noun: containerProc_image* (build/delete), containerProc_instance* (up/down/delete/restart/ps/logs/exec/verify/status), and containerProc_fullClean (combined).

• py3/images/containerProc-graphviz.pcs — source for the “Full Design at a Glance” figure.

• py3/setup.py, py3/pypiProc.sh — PyPI packaging (setup.py is dblock-driven; do not hand-edit).

Documentation and Blee-Panels

bisos.airflow is part of the ByStar Digital Ecosystem http://www.by-star.net.

This module’s primary documentation is in the form of Blee-Panels. Blee-Panels are in the ./panels directory. From within Blee and BISOS these panels are accessible under the Blee “Panels” menu.

See file:./panels/bisos.airflow/_nodeBase_/fullUsagePanel-en.org for a starting point.

The companion repo bro_dockerfiles has its own README with details on each image variant, host cgroup v1/v2 compatibility, and the per-leaf build / verify recipes.

bisos.dockerProc is best developed with Blee, the By* BISOS Libre-Halaal Emacs Environment — a layer on top of Emacs and BISOS which creates a comprehensive integrated usage and development environment.

Support