portage-engine

module
v0.0.0-...-6f7ae65 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 20, 2026 License: MIT

README

Portage Engine

CI Security Scan

Portage Engine is a self-hosted Gentoo binary-package build and publishing system. It runs native emerge builds on isolated workers, verifies and signs GPKG artifacts, and publishes a standard binhost that regular Portage clients can consume.

Status: trusted alpha. Proxmox VE (PVE), Terraform, and native Gentoo are the reference path. Repository CI and security gates are active, but the live Public Beta and GA infrastructure gates are not complete. Do not expose the trusted development stack directly to the internet. See the production boundary and remaining work.

The core pipeline is:

client → API/scheduler → disposable native worker → quarantine/verify
       → isolated signer → immutable binhost → emerge

Security boundaries:

  • PostgreSQL is the durable authority for jobs, leases, identity, signing, and capacity.
  • Builders are single-use; the isolated signer alone handles release keys.
  • Catalog policy pins repositories, profiles, images, resources, and egress.
  • OIDC and project RBAC scope writes; anonymous access is read-only and limited.

Quick start

Requirements: Go 1.26.6, Node.js 22.22.2 or newer, and Docker Compose for the local topology. make build installs the locked frontend dependencies and embeds the console in the dashboard binary.

git clone https://github.com/Volatoo/portage-engine.git
cd portage-engine

make build
make test

Start the loopback-only development stack:

cp .env.compose.example .env.compose
scripts/check-compose-ports.sh .env.compose
docker compose --env-file .env.compose run --rm portage-migrate
docker compose --env-file .env.compose up -d
scripts/verify-compose.sh .env.compose

The Compose defaults bind only to loopback. Replace credentials and add the documented HTTPS edge before allowing access from another network.

Use the binhost

Configure one catalog profile, then let native Portage install the package:

sudo ./bin/portage-client configure \
  -server=https://portage.example.org \
  -profile-id=pe/amd64/glibc/systemd/base-v1

emerge --getbinpkg app-editors/vim

Use --getbinpkgonly when falling back to a local source build is not allowed. Signing, multi-profile setup, build requests, and short-lived sessions are in the usage guide. The legacy API key is break-glass only; never send an API key or bearer token over untrusted HTTP.

Development checks

make test          # Go, release-contract, and recovery tests
make web           # console build, lint, and tests
make lint
make lint-security
make test-release

GitHub Actions additionally runs race-enabled integration tests, PostgreSQL operational gates, CodeQL, Trivy, govulncheck, npm audit, cross-platform builds, and runtime SBOM/provenance generation.

Documentation

Report vulnerabilities through the process in SECURITY.md. Never commit API tokens, infrastructure credentials, private signing keys, or production logs containing secrets.

License

MIT

Directories

Path Synopsis
cmd
artifact-lifecycle command
Command artifact-lifecycle audits, replicates, or garbage-collects one published binhost channel.
 Command artifact-lifecycle audits, replicates, or garbage-collects one published binhost channel.
builder command
Package main provides the Portage Builder service.
 Package main provides the Portage Builder service.
capacity-actuator command
Command capacity-actuator consumes PostgreSQL-fenced autoscale actions and owns the exact provider instances created for persistent phase executors.
 Command capacity-actuator consumes PostgreSQL-fenced autoscale actions and owns the exact provider instances created for persistent phase executors.
client command
Package main provides the Portage Engine client.
 Package main provides the Portage Engine client.
dashboard command
Package main implements the Portage Engine Dashboard.
 Package main implements the Portage Engine Dashboard.
desktop-runner command
Command desktop-runner executes deterministic GUI verification scenarios.
 Command desktop-runner executes deterministic GUI verification scenarios.
distcc-gate command
Command distcc-gate compares real local-only and distcc build evidence.
 Command distcc-gate compares real local-only and distcc build evidence.
image-factory command
migrate command
Command portage-migrate applies the embedded, reviewed PostgreSQL schema.
 Command portage-migrate applies the embedded, reviewed PostgreSQL schema.
server command
Package main implements the Portage Engine Server.
 Package main implements the Portage Engine Server.
signer command
Command signer runs the isolated Portage GPKG signing worker.
 Command signer runs the isolated Portage GPKG signing worker.
internal
binpkg
Package binpkg manages binary package storage and queries.
 Package binpkg manages binary package storage and queries.
builder
Package builder provides configuration transfer capabilities.
 Package builder provides configuration transfer capabilities.
capacity
Package capacity executes PostgreSQL-fenced capacity actions against cloud providers.
 Package capacity executes PostgreSQL-fenced capacity actions against cloud providers.
catalog
Package catalog owns the server-side mapping from user-facing build IDs to immutable infrastructure inputs.
 Package catalog owns the server-side mapping from user-facing build IDs to immutable infrastructure inputs.
dashboard
Package dashboard implements the web dashboard for monitoring build cluster.
 Package dashboard implements the web dashboard for monitoring build cluster.
dashboard/webassets
Package webassets serves the built operator console — the Vite bundle under web/ — out of the Go binary, so the dashboard stays one self-contained artifact with nothing to deploy beside it.
 Package webassets serves the built operator console — the Vite bundle under web/ — out of the Go binary, so the dashboard stays one self-contained artifact with nothing to deploy beside it.
desktop
Package desktop implements deterministic native-desktop verification.
 Package desktop implements deterministic native-desktop verification.
distcc
Package distcc defines the narrow Distributed Build Alpha contract shared by the scheduler, disposable builders, and compile-worker authorization plane.
 Package distcc defines the narrow Distributed Build Alpha contract shared by the scheduler, disposable builders, and compile-worker authorization plane.
gpg
Package gpg provides GPG signing functionality for binary packages.
 Package gpg provides GPG signing functionality for binary packages.
iac
Package iac manages infrastructure provisioning using Terraform.
 Package iac manages infrastructure provisioning using Terraform.
iam
Package iam defines the authenticated control-plane identity and project authorization vocabulary.
 Package iam defines the authenticated control-plane identity and project authorization vocabulary.
imagefactory
Package imagefactory validates offline image-factory inputs and produces immutable image provenance manifests without performing network access.
 Package imagefactory validates offline image-factory inputs and produces immutable image provenance manifests without performing network access.
metrics
Package metrics provides monitoring and metrics collection.
 Package metrics provides monitoring and metrics collection.
migrations
Package migrations owns the embedded PostgreSQL schema and its one-shot migration runner.
 Package migrations owns the embedded PostgreSQL schema and its one-shot migration runner.
notification
Package notification provides build completion notification capabilities.
 Package notification provides build completion notification capabilities.
persistence
Package persistence defines the PostgreSQL storage contract used by the control plane.
 Package persistence defines the PostgreSQL storage contract used by the control plane.
profilecontract
Package profilecontract validates an operator-selected Portage profile against the repositories already pinned on a builder image.
 Package profilecontract validates an operator-selected Portage profile against the repositories already pinned on a builder image.
runtimecache
Package runtimecache provides Redis-backed ephemeral coordination.
 Package runtimecache provides Redis-backed ephemeral coordination.
server
Package server implements the core Portage Engine server functionality.
 Package server implements the core Portage Engine server functionality.
signing
Package signing implements the isolated, digest-bound GPKG signing boundary.
 Package signing implements the isolated, digest-bound GPKG signing boundary.
storage
Package storage provides interfaces and implementations for storing build artifacts.
 Package storage provides interfaces and implementations for storing build artifacts.
workergateway
Package workergateway implements the attempt-bound reverse execution channel used by disposable native builders.
 Package workergateway implements the attempt-bound reverse execution channel used by disposable native builders.
pkg
config
Package config provides configuration management for Portage Engine.
 Package config provides configuration management for Portage Engine.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.