Add reproducible build system, native Unraid plugin, and WebUI
- 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:
@@ -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.
|
||||
Reference in New Issue
Block a user