📦 BAUER GROUP custom Raspberry Pi OS base images

Declarative, reproducible, CI-built Raspberry Pi OS images for production and development devices. Config lives in JSON, generation is driven by Python, actual image baking runs on top of CustomPiOS.

Supported hardware:

Base OS: Raspberry Pi OS arm64 (trixie, 2026-06-18).

• Declarative config in JSON, validated against a strict schema.
• Variant composition via extends — a child variant deep-merges onto a base, arrays of {name: ...} records merge by name.
• Env-var resolver for secrets (${VAR} / ${VAR:-default}), fail-fast on missing required values.
• Dockerised dev/build runtime — no host Python/qemu dependencies required; Linux · macOS · Windows (WSL / CMD / PowerShell).
• CI-ready image builds on GitHub Actions with matrix over all variants, artifact + release asset output, full metadata summary per run.
• Baked-in:
  • SSH enabled with hardened sshd_config.d (no root login, no challenge-response)
  • Docker CE + compose plugin, IPv6 NAT, sensible daemon.json
  • Portainer CE via docker-compose (restart: unless-stopped), installed by a first-boot oneshot — Docker daemon handles lifecycle from then on
  • Unattended upgrades with configurable maintenance + reboot windows, event-driven via apt-daily-upgrade.service post-hook
  • Dynamic MOTD banner showing variant, version, kernel, all interfaces with IPv4/IPv6, CAN state + bitrate, service health, pending reboots
  • Admin user with sudo NOPASSWD, su without password via pam_wheel

You need Raspberry Pi Imager v2.0.3 or later — earlier versions don't persist a custom repository between launches.

One-click:

Open BAUER GROUP repository in Raspberry Pi Imager

Imager opens with our catalog pre-loaded and asks for confirmation. After that, every future release shows up automatically — including Compute Module eMMC flashing via the built-in rpiboot.

Manual setup:

1. Open Raspberry Pi Imager → ⚙ Settings → Custom repository
2. Paste https://bauer-group.github.io/XPD-RPIImage/rpi-imager.json
3. Close the dialog. Imager reloads the OS list automatically — our variants appear under CHOOSE OS → BAUER GROUP.

Landing page with direct downloads + full checksums: https://bauer-group.github.io/XPD-RPIImage/

Full flashing guide (SD, USB-SSD, CM4/CM5 via rpiboot, balenaEtcher, manual dd): docs/flash.md.

# Linux / macOS / WSL

./tools/run.sh validate                    # validate every variant JSON
./tools/run.sh render canbus-plattform     # generate module artifacts
./tools/run.sh build  canbus-plattform     # full image build (privileged)

# Windows CMD

tools\run.cmd build canbus-plattform

# Windows PowerShell

.\tools\run.ps1 build -Variant canbus-plattform

See docs/tools-container.md for launcher reference.

cp .env.example .env

# edit .env - set ADMIN_PASSWORD and WIFI_PSK

make deps                                  # pip install requirements
make validate                              # schema-check every variant
make build VARIANT=canbus-plattform        # build the image

# .env is picked up automatically when it sits at the repo root.
# From elsewhere, pass it explicitly: make build ENV_FILE=path/to/.env

Output lands in dist/bgrpiimage-<variant>-v<version>.img.xz.

Push to main or open a PR → automatic build with SHA-stamped artifact (see docs/ci-cd.md).

A conventional commit on main → semantic-release cuts vX.Y.Z and the GitHub Release, then dispatches the image build on that tag so the .img.xz, .sha256 and .manifest.json assets are attached automatically.

The dispatch is a separate job using a PAT: the tag itself is pushed with GITHUB_TOKEN, and GitHub never triggers a workflow from a GITHUB_TOKEN event, so build.yml's tag trigger alone would never fire. If the PAT is ever missing, the release job fails loudly and the assets can be attached by hand:

gh workflow run build.yml --ref vX.Y.Z

Adding a new variant is a 10-line JSON file — see docs/variants.md.

  ┌─────────────────────┐     ┌───────────────────┐     ┌────────────────────┐
  │ config/variants/*.json │──▶│ scripts/generate.py │──▶│ src/modules/*/filesystem/ │
  │  (declarative, JSON)  │     │  (validate + merge │     │  root/opt/bgrpiimage/    │
  └─────────────────────┘     │   + env resolve)   │     │   (inputs for CustomPiOS)│
                              └───────────────────┘     └────────────┬───────┘
                                                                      │
                                                                      ▼
                                                ┌─────────────────────────┐
                                                │ guysoft/custompios       │
                                                │ (privileged build in    │
                                                │  docker or GH runner)    │
                                                └───────────┬─────────────┘
                                                            │
                                                            ▼
                                            ┌──────────────────────────┐
                                            │ dist/bgrpiimage-…img.xz  │
                                            └──────────────────────────┘

More detail: docs/architecture.md.

⚠️ Default credentials shipped by this image:

• admin user password → 12345678
• WiFi PSK for IOT @ BAUER-GROUP → 12345678

These are published defaults, on purpose: the images are public, so a discoverable credential is what makes them usable at all. The admin password is shipped expired — the first login (console or SSH) forces you to set a new one before you get a session, so it cannot silently stay in place. The WiFi PSK is not protected that way: treat an untouched image as safe only on an isolated lab network until you have rotated it. On first boot the login banner screams about it and the MOTD keeps reminding you until you rotate the admin password.

Bake real values into the image during the build:

1. Copy .env.example → .env, set real values.
2. Rebuild: ./tools/run.sh build <variant> --env-file ./.env.
3. Never commit .env (already gitignored).

In CI, set ADMIN_PASSWORD and WIFI_PSK as repository secrets — the workflow passes them through automatically.

Every image ships /usr/local/sbin/bgrpiimage-setup — a one-stop helper for the routine post-flash changes:

sudo bgrpiimage-setup password                       # rotate admin pw
sudo bgrpiimage-setup password alice                 # rotate another user
sudo bgrpiimage-setup wifi "MyNet" "s3cret" DE       # join a WiFi
sudo bgrpiimage-setup wifi --disable                 # tear down wlan0
sudo bgrpiimage-setup ip eth0 dhcp                   # back to DHCP
sudo bgrpiimage-setup ip eth0 static 10.0.0.5/24 10.0.0.1 1.1.1.1
sudo bgrpiimage-setup status                         # overview

All IP changes land as /etc/systemd/network/05-bgrpiimage-<iface>.network — the 05- prefix sorts before the shipped 10-eth.network / 20-wlan.network, and systemd-networkd applies only the first matching file, so ours wins. The defaults are left in place, so reverting is just deleting the file.

See docs/post-flash-setup.md for the full subcommand reference.

.
├── config/
│   ├── schema.json                        # JSON schema for variant config
│   └── variants/
│       ├── base.json                      # generic base variant
│       └── canbus-plattform.json          # extends base + CAN additions
├── scripts/
│   ├── generate.py                        # JSON → CustomPiOS module files
│   ├── bootstrap.sh                       # clones CustomPiOS into ./CustomPiOS
│   ├── build.sh                           # full image build (privileged docker)
│   └── requirements.txt
├── src/                                   # CustomPiOS distro
│   ├── config                             # distro-level config
│   ├── modules/                           # bgrpiimage-{base,users,network,boot,
│   │                                      #              hardware,can,docker,portainer,
│   │                                      #              unattended-upgrades}
│   └── variants/                          # per-variant shell config (generated)
├── tools/                                 # portable dev/build runtime
│   ├── Dockerfile
│   ├── run.sh / run.cmd / run.ps1
├── .github/workflows/build.yml            # CI pipeline
├── Makefile                               # local convenience targets
└── docs/

MIT — see LICENSE.