alpine-packages/README.md

Alpine Packages

Alpine 3.23 packaging for internal packages.

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

https://code.factoring.digital/api/packages/fsp-ops/alpine/v3.23/seaweedfs-alpine

Use In Production

Add The Package Repository

Install the registry signing key on each Alpine node:

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

Add the package repository:

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

apk update

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

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

Install SeaweedFS Node Roles

Install the base package plus only the OpenRC role packages needed on that node.

For a single-node test or a compact small deployment:

apk add seaweedfs \
  seaweedfs-master-openrc \
  seaweedfs-volume-openrc \
  seaweedfs-filer-openrc

For separated production nodes, install only the role running there:

apk add seaweedfs seaweedfs-master-openrc
apk add seaweedfs seaweedfs-volume-openrc
apk add seaweedfs seaweedfs-filer-openrc

Available OpenRC role packages:

seaweedfs-master-openrc   -> /etc/init.d/seaweedfs.master
seaweedfs-volume-openrc   -> /etc/init.d/seaweedfs.volume
seaweedfs-filer-openrc    -> /etc/init.d/seaweedfs.filer
seaweedfs-s3-openrc       -> /etc/init.d/seaweedfs.s3
seaweedfs-webdav-openrc   -> /etc/init.d/seaweedfs.webdav
seaweedfs-sftp-openrc     -> /etc/init.d/seaweedfs.sftp
seaweedfs-admin-openrc    -> /etc/init.d/seaweedfs.admin
seaweedfs-worker-openrc   -> /etc/init.d/seaweedfs.worker

The package name is seaweedfs, matching Alpine aports. If a node already has Alpine's old generic OpenRC package installed, remove it before installing a role-specific split:

apk del seaweedfs-openrc
apk add seaweedfs seaweedfs-master-openrc

Configure Services

Runtime files are installed in the usual Alpine locations:

/usr/bin/weed
/etc/seaweedfs/*.toml
/etc/conf.d/seaweedfs.*
/etc/init.d/seaweedfs.*

Edit /etc/conf.d/seaweedfs.<role> for command-line flags and /etc/seaweedfs/*.toml for SeaweedFS config. The packaged defaults are short and production-neutral; full upstream example configs are in:

/usr/share/doc/seaweedfs/examples/

Enable and start only the services needed on the node:

rc-update add seaweedfs.master default
rc-service seaweedfs.master start

rc-update add seaweedfs.volume default
rc-service seaweedfs.volume start

rc-update add seaweedfs.filer default
rc-service seaweedfs.filer start

Check the installed binary and service state:

weed version
rc-service seaweedfs.master status

Optional Packages

Install docs and generated examples:

apk add seaweedfs-doc

Install bash completion:

apk add bash-completion seaweedfs-bash-completion

seaweedfs-bash-completion is also selected automatically when seaweedfs and bash-completion are installed together.

Upgrade Or Pin

Use normal Alpine package operations:

apk upgrade seaweedfs
rc-service seaweedfs.master restart

Pin a specific package build when needed:

apk add seaweedfs=4.31-r3

Install GreptimeDB

Install GreptimeDB:

apk add greptimedb

Check the installed binary:

greptime --version

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

SeaweedFS Package

The APKBUILD repackages the official SeaweedFS Linux release tarballs. It does not build SeaweedFS from source. The package installs:

• weed as /usr/bin/weed
• minimal active config under /etc/seaweedfs/
• role-specific OpenRC subpackages
• upstream example configs under /usr/share/doc/seaweedfs/examples/
• generated bash completion as a separate subpackage

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

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 in an alpine:3.23 container and publishes 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