alpine-packages/README.md

Alpine Packages

Alpine stable packaging for internal packages.

This repository builds signed x86_64 and aarch64 APKs and publishes them to the Gitea Alpine package registry:

https://code.factoring.digital/api/packages/public/alpine/v3.23/alpine-packages

Available Packages

• SeaweedFS: seaweedfs plus OpenRC role, docs, and completion subpackages.
• GreptimeDB: greptimedb plus OpenRC service subpackages and default configs.

Use In Production

Add The Package Repository

Install the registry signing key on each Alpine node:

curl -fsSLo /etc/apk/keys/public-alpine.rsa.pub \
  https://code.factoring.digital/api/packages/public/alpine/key

Add the stable package repository:

printf '%s\n' \
  'https://code.factoring.digital/api/packages/public/alpine/v3.23/alpine-packages' \
  >> /etc/apk/repositories

apk update

If a forked or future registry is private, include a Gitea user and package token in the repository URL:

https://<user>:<token>@code.factoring.digital/api/packages/public/alpine/v3.23/alpine-packages

Install Packages

Package-specific install and service guidance lives next to each APKBUILD:

• SeaweedFS
• GreptimeDB

Background And Contribution

Package Layout

Package sources live under:

packaging/alpine/local/<pkgname>/

Currently packaged:

seaweedfs    SeaweedFS 4.31 release binary and OpenRC role splits
greptimedb   GreptimeDB 1.0.2 built from source for x86_64

Package-specific details are in the linked package READMEs above.

Local build output is written under:

packages/local/<arch>/

Signing keys and distfiles are cached under:

.cache/abuild/
.cache/apk-distfiles/

Build Commands

mise run apk:lint
mise run apk:build
mise run apk:build-all
mise run apk:packages
mise run apk:smoke
mise run apk:test-install
mise run apk:test-shell
mise run apk:publish-check

apk:build targets x86_64 by default. Multi-arch builds target x86_64 and aarch64; override with ALPINE_ARCHES when needed:

ALPINE_ARCHES="x86_64 aarch64" mise run apk:build-all

Unqualified build and install-test tasks discover all packages. GreptimeDB is a source build and can take close to an hour; it is limited to x86_64 during production evaluation. Target fast package work explicitly:

Build or test a subset of packages with ALPINE_PACKAGE or ALPINE_PACKAGES:

ALPINE_PACKAGE=seaweedfs mise run apk:build
ALPINE_PACKAGES="seaweedfs other-package" mise run apk:build-all
ALPINE_PACKAGE=seaweedfs mise run apk:test-install
ALPINE_PACKAGE=greptimedb mise run apk:checksum
ALPINE_PACKAGE=greptimedb mise run apk:build
ALPINE_PACKAGE=greptimedb SKIP_BUILD=1 mise run apk:test-install

Docker-backed build tasks keep Cargo registry, Rustup, and Cargo target caches in named Docker volumes. The default volume scope is derived from the Git remote owner/repository and is split by package and architecture. Override it when needed:

ALPINE_APK_CACHE_SCOPE=public-alpine-packages ALPINE_PACKAGE=greptimedb mise run apk:build
ALPINE_APK_CACHE_PREFIX=alpine-apk-ci ALPINE_PACKAGE=greptimedb mise run apk:build

Use the test shell to inspect the package in Alpine with the current build installed:

ALPINE_PACKAGE=seaweedfs mise run apk:shell
mise run apk:test-shell

Use the install test to validate the production instructions against the local package repository in a fresh Alpine container:

mise run apk:test-install

Use SKIP_BUILD=1 to reuse existing local packages:

SKIP_BUILD=1 mise run apk:test-install
SKIP_BUILD=1 mise run apk:test-shell

Adding Packages

Each package lives under:

packaging/alpine/local/<pkgname>/

The only required file is APKBUILD. Package-specific helpers can be added as hooks:

packaging/alpine/local/<pkgname>/scripts/test-install.sh
packaging/alpine/local/<pkgname>/scripts/update-generated-sources.sh

Repo-level tasks discover all packaging/alpine/local/*/APKBUILD files. Hook tasks skip packages that do not provide the requested hook.

Start new packages from the blueprint:

packaging/alpine/blueprint/

For compiled software, declare build tools in makedepends and use normal Alpine build(), check(), and package() functions in the package's APKBUILD.

Generated Package Sources

Generated files should live next to the package's APKBUILD so abuild checksum can track them as ordinary package sources. For SeaweedFS, that includes:

packaging/alpine/local/seaweedfs/example-*.toml
packaging/alpine/local/seaweedfs/weed.bash-completion

Refresh generated sources through package-local hooks:

mise run apk:update-generated
ALPINE_PACKAGE=seaweedfs mise run apk:update-generated
mise run apk:checksum

Run apk:checksum after changing any file listed in source=.

Gitea Workflow

The workflow at .gitea/workflows/build.yml builds against alpine:3.23 and publishes to registry branch v3.23 on push or tag. It skips publishing for pull request events.

Repository variables:

INSTANCE_URL=https://code.factoring.digital
PACKAGE_OWNER=public
PACKAGE_NAME=alpine-packages

Repository secrets:

PACKAGE_USER=<gitea package publisher>
PACKAGE_TOKEN=<token with package write access>

Pre-check the workflow locally with act:

mise run gitea-workflow-build

Publish already-built local packages manually:

INSTANCE_URL=https://code.factoring.digital \
PACKAGE_OWNER=public \
PACKAGE_NAME=alpine-packages \
PACKAGE_USER=... \
PACKAGE_TOKEN=... \
mise run apk:publish-gitea

Alpine Package Rules

Do:

• Keep local package sources next to the APKBUILD.
• Put full upstream scaffolds in /usr/share/doc/seaweedfs/examples/, not active /etc.
• Install only the OpenRC role packages needed on each node.
• Keep /etc/conf.d defaults short and production-neutral.
• Increment pkgrel for package-only changes; reset it when pkgver changes.
• Run mise run apk:publish-check before opening a PR.

Don't:

• Edit generated src/, pkg/, or packages/ output.
• Hand-edit checksum lines when abuild checksum can update them.
• Install all OpenRC roles by default.
• Put long upstream examples into active /etc defaults.

Practical PR Checklist

Before opening a PR, run:

mise run apk:publish-check
mise run gitea-workflow-build
mise run apk:test-install

Then test at least one installed role in the package shell:

mise run apk:test-shell
rc-service seaweedfs.master start
weed version