English | 简体中文

AlpineForm (apf) is a declarative configuration tool for Alpine Linux hosts. It validates HCL configuration, previews changes, converges a target over root SSH, and reports drift with the same configuration:

apf validate -> apf plan -> apf apply -> apf check

AlpineForm is pre-release software and is not an official Alpine Linux project. The first complete preview is v0.1.0-alpha.5. Alpha.1 through alpha.4 are retained as incomplete prereleases and must not be used. Compatibility guarantees are documented in the compatibility policy.

The blocking targets are persistent Alpine 3.21 through 3.24 x86_64 with OpenRC. The core manages files, directories, groups, users, authorized keys, APK repositories and packages, bounded or raw OpenRC services, hostname, timezone, kernel modules, sysctls, and verified prebuilt components. Every Beta domain runs in a fresh VM for every supported branch through apply, no-op plan, drift and repair where applicable, and reboot.

Binary, file, archive, and CA-certificate components are Beta under the four-branch blocking components case. Their source.url and source.sha256 fields may be evaluated from normalized inputs separately for each mounted instance; that expression syntax is additive alpha. Literal behavior, resource addresses, state schema v3, and alpineform.plan.alpha1 remain compatible, and target-side source-build semantics are unchanged.

Alpine 3.21 through 3.24 aarch64 remains Preview because it has cross-build and selector coverage but no blocking real-VM gate. Docker Engine and Compose are an implemented Preview domain covered by the four-branch x86_64 VM gate; they remain outside the v0.1 core promise because they depend on Alpine community. Rollback-safe named-table nftables is also an implemented Preview domain with a dedicated blocking four-branch rollback gate and a separate network-disruption approval. Target-side source builds are an independent Preview domain with checksummed inputs, offline argv execution, owned build dependencies, atomic installation, and a dedicated destructive Alpine VM gate; they remain outside the core promise. See the complete support matrix.

Release archives are built with CGO_ENABLED=0 for Linux and macOS on amd64 and arm64. The installer downloads the selected archive and checksums.txt, verifies SHA-256, and atomically installs apf:

curl -fsSL https://raw.githubusercontent.com/mofelee/alpineform/main/scripts/install.sh |
  sh -s -- --version v0.1.0-alpha.5
apf version

Every archive also carries the bilingual root documents and complete bilingual docs/ tree. The curl installer and make install place that material under <prefix>/share/alpineform; start with the documentation index.

Install into a private prefix:

sh scripts/install.sh \
  --version v0.1.0-alpha.5 \
  --prefix "$HOME/.local"

Homebrew is not published for this release. It will only be offered after its install, test, and upgrade paths have real automated evidence.

For a private repository or mirror, run the installer from an authenticated checkout and export GITHUB_TOKEN or GH_TOKEN; authenticated release assets are resolved through the GitHub API.

The control host needs apf and OpenSSH. The managed host must be a persistent Alpine 3.21 through 3.24 installation reachable as root with a key. Put the target in your OpenSSH configuration; online fact discovery does not require platform values in the AlpineForm file:

Host alpine
  HostName 192.0.2.10
  User root
  IdentityFile ~/.ssh/alpine
  IdentitiesOnly yes

examples/quickstart.apf.hcl creates a small managed directory and file:

host "alpine" {
  ssh {
    host = "alpine"
  }

  directories {
    directory "/etc/alpineform-example" {}
  }

  files {
    file "/etc/alpineform-example/managed.conf" {
      content = "managed-by=alpineform\n"
      mode    = "0644"
    }
  }
}

Run the complete workflow:

apf validate -f examples/quickstart.apf.hcl
apf plan --offline -f examples/quickstart.apf.hcl
apf plan -f examples/quickstart.apf.hcl
apf apply -f examples/quickstart.apf.hcl
apf check -f examples/quickstart.apf.hcl

apply previews before locking, replans inside a renewable per-host lease, and asks for approval of the actual locked plan. A clean check exits zero; drift prints the required actions and exits nonzero. Remote state is stored at /var/lib/alpineform/state.json with mode 0600.

Current state schema v3 reads v1 and v2 in memory and writes v3 on the next apply, including a fully no-op apply. Before that apply, retain a per-host backup plus the matching prior configuration and binary; see the state migration runbook.

Live nftables activation/deletion is separately marked as network-disrupting and requires apf apply --allow-network-disruption; --auto-approve alone is not sufficient.

Configuration uses *.apf.hcl. Variable inputs use alpineform.apfvars[.json], *.auto.apfvars[.json], explicit -var-file, -var, or APF_VAR_<name>. Reusable profile, component, script, locals, variable, and assert declarations compile into deterministic resource addresses and dependency order.

packages.package, files.file, and runtime services.service declarations accept static, same-scope typed depends_on references. Generated openrc.service declarations do not. Authored dependencies add ordering, including reverse ordering for explicit remote removal. They never activate OpenRC operations or change scripts. Inferred prerequisites and triggered_by relationships remain separate. See the DSL reference and plan relationship contract.

Start with the DSL and CLI reference, then use the domain guides:

• files, directories, groups, and users
• APK and packages
• OpenRC services
• system settings and kernel settings
• components and change scripts
• Docker Engine and Compose (Preview)
• rollback-safe nftables (Preview)

Operational contracts are covered by the architecture, state backend, lock model, security model, and operations runbook.

make build
make docs-check
make check
make vulncheck
make test-integration-layout

The real-VM harness and remote-libvirt settings are documented in the integration runbook. Release work follows the release process. Documentation changes follow the localization policy.

AlpineForm uses DebianForm v0.6.0 as an architecture and selected-code reference. NOTICE.md records the exact upstream commit and major changes. AlpineForm is independently versioned and does not accept DebianForm configuration or state. Licensed under the MIT License; see LICENSE.