Add reproducible build system, native Unraid plugin, and WebUI
Build Packages / Build .txz packages (push) Failing after 9s
Lint / ShellCheck (push) Failing after 43s
Lint / Validate .plg XML (push) Successful in 10s
Lint / EditorConfig (push) Failing after 6s

- versions.env pins podman, conmon, crun, netavark, aardvark-dns, passt,
  and fuse-overlayfs to verified upstream source checksums; SlackBuild
  recipes, scripts/build-packages.sh, checksums.sh, release.sh, and
  update-versions.sh implement the reproducible pipeline; GitHub Actions
  workflows build in a Slackware container and publish releases without
  committing any binaries.

- plugin/podman.plg installs/updates/removes all eight packages (the
  seven components plus the plugin's own unraid-podman scaffolding
  package) via upgradepkg, using the official Unraid array-event hook
  mechanism (event/disks_mounted, event/stopping) instead of editing
  /boot/config/go. rc.podman and the sbin/ helper scripts implement
  storage creation, config seeding/sync, preflight checks, autostart
  with per-container Safe-Mode, and package verify/update/rollback.

- webui/plugins/podman implements the Dashboard, Containers, Pods,
  Images, Volumes, Networks, Logs, Terminal, Compose, and Settings
  panels against the approved mockup (webui/mockups/prototype.html),
  talking to podman system service exclusively via PodmanClient.php
  (libpod REST API over the Unix socket), with two documented
  exceptions: Terminal's one-shot exec model and Compose's use of the
  podman compose CLI, since libpod has no REST equivalent for either.

- docs/ARCHITECTURE.md and docs/ROADMAP.md record the design decisions
  and honest current status (syntax-checked, unit- and
  integration-tested against fake sockets/servers; not yet run against
  a real Unraid/Podman/Slackware system).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-11 10:51:14 +00:00
co-authored by Claude Sonnet 5
parent 58ffc0c226
commit e2fefcdf9c
124 changed files with 9611 additions and 0 deletions
+83
View File
@@ -0,0 +1,83 @@
# Contributing to unraid-podman
Thanks for your interest in contributing. This project is in an early,
architecture-first stage — please read [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
before proposing structural changes, so new work stays consistent with the agreed
design (RAM-root persistence model, no systemd, Docker coexistence, etc.).
## Ground rules
- Discuss non-trivial changes in an issue before opening a PR — this repo makes
deliberate, sometimes non-obvious trade-offs (see the "Offene Fragen / Risiken"
section of the architecture doc) and we'd rather align early than rework a PR.
- Keep persistence discipline: anything written under `/etc`, `/usr`, `/var` on a
running Unraid system is lost on reboot. Any new config or state must be mirrored
to `/boot/config/plugins/podman/` or an array/cache path — see
[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#7-persistenz-strategie-zusammenfassung-der-prinzipien).
- No systemd. Init/process management goes through `plugin/rc.d/rc.podman` in the
classic BSD `start|stop|restart|status` style.
- Don't introduce changes that could destabilize a coexisting Docker installation
(shared storage paths, shared bridge/network names, shared iptables chains).
## Repository layout
See the "Repository structure" section in [README.md](README.md). In short:
| Directory | What goes here |
|---|---|
| `packages/` | One subdirectory per Slackware `.txz` package (podman, conmon, crun, netavark, aardvark-dns, containers-common, fuse-overlayfs, passt) |
| `plugin/` | The `.plg` manifest, `rc.d/rc.podman`, `sbin/` helper scripts, and default files staged for `/boot/config/plugins/podman/` |
| `webui/` | Dynamix-style GUI pages under `plugins/podman/` (later phase) |
| `config/` | Default `containers.conf` / `storage.conf` / `registries.conf` / `policy.json` templates |
| `scripts/` | Build and release tooling, not shipped to end users |
| `docs/` | Architecture, install guide, FAQ, troubleshooting, roadmap |
## Development setup
Podman package builds must target Slackware compatibility with Unraid's current
base — this generally means building inside a Slackware-compatible container
rather than on your own distro. Run `scripts/build-packages.sh` (optionally
`scripts/build-packages.sh <name>` for a single package) inside such a
container; `scripts/ci/setup-slackware-buildenv.sh` bootstraps the toolchain
and C library dependencies the build needs. `.github/workflows/build-packages.yml`
runs the same scripts in CI and is the reference for the exact container image
and setup sequence.
For anything touching `plugin/rc.d/rc.podman`, `plugin/sbin/*.sh`, or `podman.plg`,
test on a real or virtualized Unraid instance — behavior around RAM-root, `/boot`
persistence, and array/cache availability at boot cannot be fully validated on a
generic Linux box.
## Coding conventions
- **Shell scripts** (`rc.podman`, `sbin/*.sh`, `scripts/*.sh`): POSIX-compatible
where practical, `set -eu` at minimum, and must pass
[ShellCheck](https://www.shellcheck.net/) (see `.github/workflows/lint.yml`).
- **Slackware package recipes** (`packages/*`): follow standard `SlackBuild`
conventions (`slack-desc` limited to 70 columns / 11 lines, `doinst.sh` for
post-install steps).
- **PHP/JS in `webui/`**: follow the conventions of Unraid's existing Dynamix
plugins for consistency with the rest of the GUI.
- Commit messages: [Conventional Commits](https://www.conventionalcommits.org/)
(`feat:`, `fix:`, `docs:`, `build:`, `ci:`, ...) so changelog generation and
history stay readable.
## Pull requests
1. Fork, branch off `main`, keep PRs focused on a single concern.
2. Update `CHANGELOG.md` under `[Unreleased]` for any user-facing change.
3. Update relevant docs under `docs/` if behavior or structure changes.
4. Make sure CI (lint / package build checks) passes.
5. Describe how you tested the change, especially for anything touching boot
behavior, persistence, or Docker coexistence.
## Reporting bugs / requesting features
Use the issue templates under `.github/ISSUE_TEMPLATE/`. For security-relevant
reports (rootful socket exposure, privilege escalation, etc.), follow
[SECURITY.md](.github/SECURITY.md) instead of a public issue.
## Code of Conduct
This project follows the [Code of Conduct](.github/CODE_OF_CONDUCT.md). By
participating, you agree to uphold it.