# 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/public/alpine/v3.23/alpine-packages
```

## Use In Production

### Add The Package Repository

Install the registry signing key on each Alpine node:

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

Add the package repository:

```sh
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:

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

### 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
```

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:

```sh
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:

```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
```