11ef6456af
All checks were successful
Build Alpine Packages / build-and-publish (push) Successful in 35m5s
389 lines
8.7 KiB
Markdown
389 lines
8.7 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```sh
|
|
curl -fsSLo /etc/apk/keys/fsp-ops-alpine.rsa.pub \
|
|
https://code.factoring.digital/api/packages/fsp-ops/alpine/key
|
|
```
|
|
|
|
Add the package repository:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```sh
|
|
apk add seaweedfs \
|
|
seaweedfs-master-openrc \
|
|
seaweedfs-volume-openrc \
|
|
seaweedfs-filer-openrc
|
|
```
|
|
|
|
For separated production nodes, install only the role running there:
|
|
|
|
```sh
|
|
apk add seaweedfs seaweedfs-master-openrc
|
|
apk add seaweedfs seaweedfs-volume-openrc
|
|
apk add seaweedfs seaweedfs-filer-openrc
|
|
```
|
|
|
|
Available OpenRC role packages:
|
|
|
|
```text
|
|
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:
|
|
|
|
```sh
|
|
apk del seaweedfs-openrc
|
|
apk add seaweedfs seaweedfs-master-openrc
|
|
```
|
|
|
|
### Configure Services
|
|
|
|
Runtime files are installed in the usual Alpine locations:
|
|
|
|
```text
|
|
/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:
|
|
|
|
```text
|
|
/usr/share/doc/seaweedfs/examples/
|
|
```
|
|
|
|
Enable and start only the services needed on the node:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
weed version
|
|
rc-service seaweedfs.master status
|
|
```
|
|
|
|
### Optional Packages
|
|
|
|
Install docs and generated examples:
|
|
|
|
```sh
|
|
apk add seaweedfs-doc
|
|
```
|
|
|
|
Install bash completion:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
apk upgrade seaweedfs
|
|
rc-service seaweedfs.master restart
|
|
```
|
|
|
|
Pin a specific package build when needed:
|
|
|
|
```sh
|
|
apk add seaweedfs=4.31-r3
|
|
```
|
|
|
|
### Install GreptimeDB
|
|
|
|
Install GreptimeDB:
|
|
|
|
```sh
|
|
apk add greptimedb
|
|
```
|
|
|
|
Check the installed binary:
|
|
|
|
```sh
|
|
greptime --version
|
|
```
|
|
|
|
## Background And Contribution
|
|
|
|
### Package Layout
|
|
|
|
Package sources live under:
|
|
|
|
```text
|
|
packaging/alpine/local/<pkgname>/
|
|
```
|
|
|
|
Currently packaged:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
packages/local/<arch>/
|
|
```
|
|
|
|
Signing keys and distfiles are cached under:
|
|
|
|
```text
|
|
.cache/abuild/
|
|
.cache/apk-distfiles/
|
|
```
|
|
|
|
### Build Commands
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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`:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
mise run apk:test-install
|
|
```
|
|
|
|
Use `SKIP_BUILD=1` to reuse existing local packages:
|
|
|
|
```sh
|
|
SKIP_BUILD=1 mise run apk:test-install
|
|
SKIP_BUILD=1 mise run apk:test-shell
|
|
```
|
|
|
|
### Adding Packages
|
|
|
|
Each package lives under:
|
|
|
|
```text
|
|
packaging/alpine/local/<pkgname>/
|
|
```
|
|
|
|
The only required file is `APKBUILD`. Package-specific helpers can be added as
|
|
hooks:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
packaging/alpine/local/seaweedfs/example-*.toml
|
|
packaging/alpine/local/seaweedfs/weed.bash-completion
|
|
```
|
|
|
|
Refresh generated sources through package-local hooks:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```text
|
|
INSTANCE_URL=https://code.factoring.digital
|
|
PACKAGE_OWNER=public
|
|
PACKAGE_NAME=alpine-packages
|
|
```
|
|
|
|
Repository secrets:
|
|
|
|
```text
|
|
PACKAGE_USER=<gitea package publisher>
|
|
PACKAGE_TOKEN=<token with package write access>
|
|
```
|
|
|
|
Pre-check the workflow locally with `act`:
|
|
|
|
```sh
|
|
mise run gitea-workflow-build
|
|
```
|
|
|
|
Publish already-built local packages manually:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
mise run apk:test-shell
|
|
rc-service seaweedfs.master start
|
|
weed version
|
|
```
|