Streamline Alpine package sources

README.md

@@ -1,14 +1,16 @@
-# SeaweedFS Alpine package base
+# SeaweedFS Alpine Package
 
-This repository is set up to build a local SeaweedFS Alpine package with `mise` while keeping all Alpine tooling inside Docker.
+Local Alpine packaging for SeaweedFS `4.31`. The workflow runs Alpine tooling
+inside Docker and writes signed packages under `packages/local/<arch>/`.
 
-## Tasks
+## Commands
 
 ```sh
 mise run apk:build
 mise run apk:build-all
 mise run apk:build-x86_64
 mise run apk:build-aarch64
+mise run apk:update-generated
 mise run apk:checksum
 mise run apk:lint
 mise run apk:packages
@@ -18,57 +20,72 @@ mise run apk:shell
 mise run apk:clean
 ```
 
-`mise` also declares the Docker CLI as a project tool dependency, so the package workflow has a single command surface.
-
-## Tool stub
-
-The SeaweedFS release binary is also available as a mise HTTP tool stub:
-
-```sh
-./bin/weed version
-```
-
-The stub is pinned to SeaweedFS `4.31` and includes Linux x64 and arm64 release URLs with SHA-256 checksums.
-
-The default build targets `x86_64`. Multi-arch builds currently target `x86_64` and Alpine's `aarch64`; override this with `ALPINE_ARCHES`, for example:
+`apk:build` targets `x86_64` by default. Multi-arch builds target `x86_64` and
+`aarch64`; override with `ALPINE_ARCHES` when needed:
 
 ```sh
 ALPINE_ARCHES="x86_64 aarch64" mise run apk:build-all
 ```
 
-Generated packages and repository indexes are written under `packages/`, typically:
+The release binary is also exposed as a mise HTTP tool stub:
 
-```text
-packages/local/x86_64/
-packages/local/aarch64/
+```sh
+./bin/weed version
 ```
 
-Because this package repackages upstream release binaries, all targets are built from the native Docker builder platform by default (`ALPINE_BUILD_PLATFORM=linux/amd64`). No QEMU/binfmt setup is required.
+## Package Layout
 
-The signing key and distfiles cache are kept in `.cache/abuild/` and `.cache/apk-distfiles/` so repeated builds use the same local repository key.
+```text
+packaging/alpine/local/seaweedfs/APKBUILD
+packaging/alpine/local/seaweedfs/*.toml
+packaging/alpine/local/seaweedfs/example-*.toml
+packaging/alpine/local/seaweedfs/weed.bash-completion
+packaging/alpine/local/seaweedfs/seaweedfs.*.confd
+packaging/alpine/local/seaweedfs/seaweedfs.initd
+packages/local/<arch>/
+```
 
-## Local repository
+The package repackages upstream release tarballs, so builds use
+`ALPINE_BUILD_PLATFORM=linux/amd64` by default. Signing keys and distfiles are
+cached in `.cache/abuild/` and `.cache/apk-distfiles/`.
 
-To test the package in an Alpine container:
+## Test And Publish
 
 ```sh
 mise run apk:smoke
-```
-
-Before publishing or handing the local repository to another system, run:
-
-```sh
 mise run apk:publish-check
 ```
 
-That runs APKBUILD linting, rebuilds all configured architectures, lists the generated package metadata, and performs the install smoke test.
+`apk:publish-check` runs APKBUILD linting, rebuilds configured architectures,
+lists package metadata, and installs the built packages in an Alpine container.
 
-To install OpenRC service scripts as well:
+Install from the local repo with the base package plus the role-specific OpenRC
+subpackage you need:
 
 ```sh
 apk add seaweedfs seaweedfs-master-openrc
 ```
 
+Optional generated material is split out:
+
+```sh
+apk add seaweedfs-doc
+apk add bash-completion seaweedfs-bash-completion
+```
+
+The doc split installs upstream scaffolds under
+`/usr/share/doc/seaweedfs/examples/`. The bash completion split installs
+`/usr/share/bash-completion/completions/weed` and is also selected by
+`install_if` when `seaweedfs` and `bash-completion` are installed together.
+
+This repository publishes `seaweedfs`, matching Alpine aports. Remove Alpine's
+old generic OpenRC package before installing a role split:
+
+```sh
+apk del seaweedfs-openrc
+apk add seaweedfs seaweedfs-master-openrc
+```
+
 The OpenRC subpackages are:
 
 ```text
@@ -82,15 +99,32 @@ seaweedfs-admin-openrc    -> seaweedfs.admin
 seaweedfs-worker-openrc   -> seaweedfs.worker
 ```
 
-Each service has matching defaults in `/etc/conf.d/seaweedfs.*`. Remote targets use distinct variables such as `SEAWEEDFS_MASTER`, `SEAWEEDFS_FILER`, and `SEAWEEDFS_ADMIN`; `SEAWEEDFS_OPTS` remains available for additional flags. Enable only the roles needed for a node, for example:
+Each service has defaults in `/etc/conf.d/seaweedfs.*`. Enable only the roles
+needed on the node:
 
 ```sh
 rc-update add seaweedfs.master default
 rc-service seaweedfs.master start
 ```
 
-If the repository key is not copied into `packages/local/x86_64/`, copy the public key from `.cache/abuild/*.rsa.pub` into `/etc/apk/keys/` in the test system before running `apk update`.
+If the repo key is missing on a target system, copy `.cache/abuild/*.rsa.pub`
+into `/etc/apk/keys/` before `apk update`.
 
-## Package inputs
+## Alpine Package Dos And Don'ts
 
-The package lives in `packaging/alpine/local/seaweedfs/APKBUILD`. It repackages SeaweedFS `4.31` release binaries from GitHub and installs the `weed` binary. Generated scaffold configs are installed under `/etc/seaweedfs/`.
+Do:
+
+- Keep local `source` files next to the `APKBUILD`.
+- Put full upstream scaffolds in `/usr/share/doc/seaweedfs/examples/`, not active `/etc`.
+- Run `mise run apk:update-generated` when updating generated examples or completions.
+- Run `mise run apk:checksum` after changing any package source file.
+- Increment `pkgrel` for package-only changes; reset it when `pkgver` changes.
+- Keep installed defaults short and production-neutral.
+- Run `mise run apk:publish-check` before handing off a repository.
+
+Don't:
+
+- Edit generated `src/`, `pkg/`, or `packages/` output.
+- Hand-edit checksum lines when `abuild checksum` can do it.
+- Bundle long upstream examples as active `/etc` defaults.
+- Install all OpenRC roles on a node by default.