maggesandClaude Sonnet 5
e2fefcdf9c
- 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>
84 lines
4.3 KiB
Markdown
84 lines
4.3 KiB
Markdown
# 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.
|