alpine-packages/README.md

Alpine Packages

Alpine stable packaging for internal packages.

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

Available Packages

• SeaweedFS: seaweedfs
• GreptimeDB: greptimedb

Use In Production

Add The Package Repository

Install the registry signing key on each Alpine node:

cd /etc/apk/keys
curl -fsSLOJ https://code.factoring.digital/api/packages/public/alpine/key

Keep the filename returned by Gitea. Alpine matches repository signatures by key filename, otherwise apk update reports UNTRUSTED signature.

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

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 tasks
Name                  Description
apk:build             Build the Alpine package in Docker for the default architecture
apk:build-aarch64     Build the Alpine package in Docker for aarch64
apk:build-all         Build the Alpine package in Docker for all configured architectures
apk:build-x86_64      Build the Alpine package in Docker for x86_64
apk:checksum          Refresh APKBUILD checksums in Docker
apk:ci-build          Build all configured Alpine packages directly in the current Alpine...
apk:ci-smoke          Install-test built packages directly in the current Alpine environment
apk:clean             Remove generated Alpine package build outputs
apk:lint              Run Alpine APKBUILD lint in Docker
apk:packages          List built Alpine packages and dependencies
apk:publish-check     Run lint, multi-arch build, package listing, and smoke test
apk:publish-gitea     Publish built packages to the Gitea Alpine package registry
apk:shell             Open an Alpine package build shell in Docker
apk:smoke             Install-test built packages from the local repository in Docker
apk:test-install      Test README installation instructions in a fresh Alpine container
apk:test-shell        Open an Alpine shell with the current local package build installed
apk:update-generated  Refresh packaged upstream examples and shell completions
gitea-workflow-build  Run the Gitea build workflow locally through act as a pull_request event

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

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