Prepare Fluxheim 0.5.0 release

Author: eldryoth

CHANGELOG.md

@@ -11,6 +11,14 @@ behavior when the change improves security or project direction.
 
 ### Added
 
+- Nothing yet.
+
+## 0.5.0 - Basic Sites Preview
+
+Released: 2026-05-06
+
+### Added
+
 - GitHub CI, Dependabot, CodeQL, dependency policy, and release-check scripts.
 - Feature preflight validation for mutually exclusive TLS backends and
   zero-retention privacy-mode incompatibilities.
@@ -44,6 +52,8 @@ behavior when the change improves security or project direction.
   restricted redirect statuses.
 - Wolfi, Alpine, SUSE Micro, and Debian runtime Containerfiles.
 - Container image publish workflow for GitHub Container Registry and Docker Hub.
+- RPM packaging spec for RHEL/openSUSE-style builds from vendored Cargo
+  dependencies.
 - Runtime UID/GID build args for container images, defaulting to non-root
   `65532:65532` while allowing deliberate root-runtime images.
 - Zero-retention privacy example config for `profile-privacy` builds.
@@ -92,6 +102,16 @@ behavior when the change improves security or project direction.
   `metrics`.
 - CodeQL uses the supported Rust `build-mode: none` setup.
 
+### Notes
+
+- This is a preview release for normal static HTML websites and simple
+  whole-vhost proxying with static TLS certificates. It is not the `1.0.0`
+  gateway release.
+- Known `1.0.0` gaps include SNI certificate selection across multiple
+  certificates, route-level proxy/static/redirect behavior, websocket-safe
+  proxying, per-route limits and timeouts, custom upstream error pages, and
+  secure static alias/directory listing behavior.
+
 ## 0.1.0 - Repository Baseline
 
 ### Added

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "fluxheim"
-version = "0.1.0"
+version = "0.5.0"
 edition = "2024"
 rust-version = "1.95"
 license = "EUPL-1.2"

Cargo.toml

@@ -23,18 +23,24 @@ Fluxheim is licensed under the European Union Public Licence 1.2.
 
 ## Status
 
-Fluxheim is under active early development. The public `1.0` target is
-intentionally narrow:
+Fluxheim is under active early development. The current `0.5.x` release line is
+the basic-sites preview:
 
 - static website hosting;
-- reverse proxying;
+- simple whole-vhost reverse proxying;
 - cache module baseline;
 - virtual hosts;
 - TLS with rustls as the default backend;
 - optional cleartext-to-HTTPS redirect;
 - strict request limits and secure defaults;
 - local and rootless Podman operation.
 
+The public `1.0` target is the first release intended to migrate Fluxheim's own
+real multi-site gateway configs. That means route-level proxy/static/redirect
+behavior, SNI certificate selection, websocket-safe proxying, per-route limits
+and timeouts, custom upstream error pages, and secure static alias/directory
+handling must be implemented and tested before `1.0.0`.
+
 Features such as load balancing, ACME automation, admin snapshots, metrics,
 WAF, Cloudflare origin support, PHP, CGI, and legacy protocols are planned as
 opt-in modules and are documented separately until they graduate.
@@ -299,7 +305,9 @@ layout for configs, TLS certificates, cache, state, logs, and static site roots.
 
 Fluxheim will not treat every planned feature as part of `1.0`.
 
-- `1.0`: stable static hosting and reverse proxy core.
+- `0.5`: basic vhosts, static HTML sites, static TLS, containers, and simple
+  whole-vhost proxying.
+- `1.0`: route-aware gateway core sufficient for the posted real site configs.
 - `1.1`: TLS policy hardening.
 - `1.2`: operational pack: logging, admin snapshots, rollback, metrics.
 - `1.3`: load balancer support.

README.md

@@ -0,0 +1,144 @@
+# Fluxheim 0.5.0 Release Notes
+
+## Version
+
+- Version: `0.5.0`
+- Release date: 2026-05-06
+- Git tag: `v0.5.0` after release validation
+- Git commit: fill in from `git rev-parse HEAD` before tagging
+- License: EUPL-1.2
+
+## Scope
+
+Fluxheim `0.5.0` is the basic-sites preview. It is intended for normal static
+HTML websites and simple whole-vhost reverse proxying with static TLS
+certificates.
+
+Stable preview scope:
+
+- static web serving for HTML, CSS, JavaScript, images, fonts, and other normal
+  site assets;
+- vhost routing by Host header;
+- static downstream TLS certificates, with rustls as the default backend;
+- optional global HTTP-to-HTTPS redirect;
+- simple whole-vhost reverse proxying to one upstream;
+- request/header/body limits;
+- default `Server: fluxheim` response header, removable by config;
+- secure header mutation policy;
+- static cache headers, ETag, conditional requests, and byte ranges;
+- rootless Podman/container examples for Wolfi, Alpine, SUSE Micro, and Debian
+  runtime variants;
+- RPM packaging spec for RHEL/openSUSE-style builds from vendored Cargo
+  dependencies;
+- release checks for formatting, linting, tests, dependency policy, advisory
+  policy, CodeQL, and local smoke coverage.
+
+Default Cargo features:
+
+- `proxy`
+- `web`
+- `cache`
+- `tls-rustls`
+- `security`
+
+## Highlights
+
+- Basic vhost static hosting and simple reverse proxying are now documented as
+  the preview release promise.
+- Container deployment examples include explicit graceful shutdown settings so
+  normal `podman compose down` does not fall back to `SIGKILL`.
+- The public `1.0.0` target is now defined as the gateway-ready release needed
+  for representative real multi-site configs.
+
+## Security And Stability Gate
+
+Fill this in immediately before tagging:
+
+- Gate command: `scripts/stable_release_gate.sh check` or stronger
+- Gate report directory:
+- Result:
+- `cargo audit` result:
+- `cargo deny check` result:
+- TLS scan result:
+- Load smoke result:
+- Request-framing smoke result:
+- Fuzz target compile result:
+- Podman smoke result:
+
+## Reviewed Advisory Exceptions
+
+- `protobuf < 3.7.2` may appear transitively through Pingora dependencies until
+  upstream updates. Do not accept this exception silently: record the exact
+  dependency path from `cargo audit`, confirm whether Fluxheim parses
+  attacker-supplied protobuf through that dependency in this release, and remove
+  the exception as soon as the upstream fix is available.
+
+## Breaking Changes
+
+- This is a pre-`1.0.0` preview release. Config shape and behavior may still
+  change when the change improves security or the `1.0.0` gateway target.
+
+## Upgrade Notes
+
+- Prefer `upstreams = ["host:port"]` over the older single `upstream = "host:port"`
+  field. Do not configure both in the same proxy block.
+- Use `[headers.*.add]`/`remove` for user-friendly header changes. The older
+  `set`/`unset` names remain compatible.
+- For containers, keep the container stop timeout higher than
+  `server.process.grace_period_seconds + graceful_shutdown_timeout_seconds`.
+
+## Known Limitations
+
+These are intentional `1.0.0` blockers, not `0.5.0` promises:
+
+- no multi-certificate SNI selection at runtime yet;
+- no route/location layer yet;
+- no route-level redirect/proxy/static actions yet;
+- no websocket-specific upgrade support yet;
+- no per-route body limits or upstream timeouts yet;
+- no custom upstream error pages yet;
+- no static alias or directory listing support yet;
+- no runtime ACME issuance yet.
+
+## Container Images
+
+Planned image tags after release validation:
+
+- GitHub Container Registry: `ghcr.io/valkyoth/fluxheim:v0.5.0-wolfi`
+- GitHub Container Registry: `ghcr.io/valkyoth/fluxheim:v0.5.0-alpine`
+- GitHub Container Registry: `ghcr.io/valkyoth/fluxheim:v0.5.0-suse-micro`
+- GitHub Container Registry: `ghcr.io/valkyoth/fluxheim:v0.5.0-debian`
+- Docker Hub: matching variant tags when Docker Hub credentials are configured
+- Runtime user: `65532:65532` by default
+- Default config path: `/etc/fluxheim/fluxheim.toml`
+- Static site path: operator-mounted, commonly `/srv/sites/...`
+- Cache path: `/var/cache/fluxheim`
+- State path: `/var/lib/fluxheim`
+
+## RPM Packaging
+
+The release includes [packaging/rpm/fluxheim.spec](packaging/rpm/fluxheim.spec)
+and [packaging/rpm/fluxheim.tmpfiles](packaging/rpm/fluxheim.tmpfiles).
+
+The spec expects a source tarball plus a vendored Cargo dependency tarball, then
+builds with `cargo --offline`:
+
+```bash
+cargo vendor vendor > /tmp/fluxheim-cargo-config.toml
+tar -czf fluxheim-0.5.0-vendor.tar.gz vendor
+```
+
+The default RPM feature set is `profile-core`. Builders can override it with:
+
+```bash
+rpmbuild -ba packaging/rpm/fluxheim.spec --define 'fluxheim_features profile-static-site'
+```
+
+## Checksums And Signatures
+
+Fill this in during the release:
+
+- Source archive checksum:
+- Binary checksums:
+- Container digests:
+- Tag signature:

RELEASE_NOTES_0.5.0.md

@@ -4,13 +4,14 @@ This roadmap is the working implementation plan. Keep it current as features
 move from design to code.
 
 Release sequencing is defined in [Versioning Plan](docs/versioning-plan.md).
-That plan keeps `1.0` intentionally small and promotes larger modules through
-later minor releases.
+That plan treats `0.5.x` as the basic-sites preview and `1.0.0` as the first
+gateway-ready release for Fluxheim's representative real multi-site configs.
+Larger modules still graduate through later minor releases.
 
 ## Current MVP Goal
 
-Fluxheim's first stable release should be a local/rootless-Podman friendly
-Pingora static web server and reverse proxy that can safely run small sites and
+Fluxheim's `0.5.x` preview should be a local/rootless-Podman friendly Pingora
+static web server and reverse proxy that can safely run small sites and simple
 origin frontends:
 
 - vhost routing with static web serving and single-upstream proxying;
@@ -19,11 +20,13 @@ origin frontends:
 - strict header/body limits and basic secure header policy;
 - release checks, license checks, and rootless container packaging.
 
-The near-term focus is hardening the already-working baseline rather than
-expanding into large research features. ACME runtime, SNI certificate selection,
-load balancing, admin snapshots, metrics, Sentinel Mesh/WireGuard,
-stale-while-revalidate, and persistent cache indexing remain important, but
-they should graduate after the `1.0` stable core according to the versioning
+The near-term focus is hardening the already-working baseline, then closing the
+`1.0.0` gateway gaps exposed by real configs: SNI certificate selection,
+path/location routing, route redirects, websocket-safe proxying, per-route body
+limits and timeouts, custom upstream error pages, static aliases, and directory
+listing. ACME runtime, load balancing, admin snapshots, metrics, Sentinel
+Mesh/WireGuard, stale-while-revalidate, and persistent cache indexing remain
+important, but they should graduate after `1.0.0` according to the versioning
 plan.
 
 After `1.0`, the first dedicated minor release should focus on TLS policy:

ROADMAP.md

@@ -1,15 +1,15 @@
 # Production Readiness
 
-Fluxheim is still pre-`1.0`. This page states what the first stable release is
-intended to support, what is deliberately outside the stable promise, and what
-operators should verify before using a build beyond local testing.
+Fluxheim is still pre-`1.0`. This page states what the current preview release
+is intended to support, what the first stable gateway release must support, and
+what operators should verify before using a build beyond local testing.
 
-## Stable 1.0 Target
+## 0.5 Basic-Sites Preview
 
-The `1.0` line is intentionally small:
+The `0.5.x` line is intentionally limited:
 
 - static file hosting from configured vhost roots;
-- reverse proxying to one configured upstream target;
+- simple whole-vhost reverse proxying to one configured upstream target;
 - vhost routing by exact and wildcard host names;
 - cache code compiled by default, with runtime caching disabled until a storage
   tier is configured;
@@ -23,6 +23,23 @@ The `1.0` line is intentionally small:
 - local release gates for formatting, linting, tests, license policy,
   dependency advisories, core feature profiles, and localhost smoke checks.
 
+## Stable 1.0 Target
+
+The `1.0` line should be the first gateway-ready release for representative
+real multi-site configs. In addition to the `0.5.x` behavior, it must support:
+
+- SNI certificate selection across multiple configured certificates;
+- route-level exact, prefix, and fallback matching;
+- route actions for proxy, static serving, and redirects;
+- cleartext ACME challenge exception routes plus HTTPS redirect for everything
+  else;
+- apex/`www` redirect vhosts that preserve the request URI safely;
+- websocket-safe proxying and prefix stripping for routes such as `/chat/`;
+- per-route body limits and upstream connect/read/send timeouts;
+- custom upstream error pages;
+- static aliases and secure directory listing;
+- container DNS behavior suitable for local Podman deployments.
+
 ## Not Stable In 1.0
 
 These features may exist in code, documentation, or feature flags, but they are

docs/production-readiness.md

@@ -46,16 +46,18 @@ scripts/release_checks.sh
 
 The wrapper runs formatting, clippy, tests, selected feature builds, example
 config validation, `cargo deny check`, `cargo audit`, and localhost smoke tests.
-It may include incubator-module smoke checks during development; the `1.0` core
-build matrix below defines what is stable release scope.
+It may include incubator-module smoke checks during development. The `0.5.x`
+preview scope is basic static/proxy/TLS behavior; the `1.0` gateway scope is
+defined in the versioning plan and must cover representative multi-site gateway
+configs before a stable tag.
 
 For the stable-release gate without incubator module checks, use:
 
 ```bash
 scripts/stable_release_gate.sh release
 ```
 
-Run the 1.0 core localhost smoke directly when changing stable static/proxy
+Run the core localhost smoke directly when changing stable static/proxy
 behavior:
 
 ```bash
@@ -70,14 +72,14 @@ Confirm GitHub CodeQL default setup is enabled for `main`. Do not also enable an
 advanced CodeQL workflow for the same repository; GitHub rejects advanced SARIF
 uploads when default setup is active.
 
-Confirm the Rust CI workflow still runs the `1.0` core feature matrix in both
-check and release modes, plus the `scripts/smoke_1_0_core.sh` localhost smoke.
+Confirm the Rust CI workflow still runs the core feature matrix in both check
+and release modes, plus the `scripts/smoke_1_0_core.sh` localhost smoke.
 
 ## TLS And Certificate Storage
 
 - Static certificate chains and private keys are supported. Bought certificates
   remain a first-class deployment mode.
-- The 1.0 core smoke generates a temporary static certificate and proves both
+- The core smoke generates a temporary static certificate and proves both
   static and proxied vhosts over a TLS listener.
 - ACME config and renewal queue planning are implemented, but account/order and
   challenge runtime work is not release-ready yet. Do not document automated
@@ -91,11 +93,12 @@ fluxheim --config path/to/fluxheim.toml --check-tls-storage
 On Unix, private keys should be owner-only (`0600`) and ACME storage directories
 should be owner-only (`0700`).
 
-## 1.0 Core Build Matrix
+## Core Build Matrix
 
-For a `1.0.x` release, confirm the stable core binaries compile. This matrix
-intentionally excludes post-1.0 modules such as load balancing, metrics, admin,
-ACME runtime, WAF, PHP/CGI, Cloudflare automation, legacy HTTP, and WASM.
+For a `0.5.x` preview or `1.0.x` release, confirm the stable core binaries
+compile. This matrix intentionally excludes post-1.0 modules such as load
+balancing, metrics, admin, ACME runtime, WAF, PHP/CGI, Cloudflare automation,
+legacy HTTP, and WASM.
 
 ```bash
 scripts/validate-1-0-core.sh release
@@ -112,9 +115,10 @@ scripts/validate-1-0-core.sh check
 
 Passing memory-safe Rust builds is not enough for a proxy. Before every stable
 release, run this gate against the stable modules included in that release and
-record the results in the release notes. For `1.0.x`, the target is the
-static/proxy/TLS core. For later minors, include every module promoted to
-`stable` in that release.
+record the results in the release notes. For `0.5.x`, the target is the
+documented basic-sites preview. For `1.0.x`, the target is the gateway core
+needed for representative multi-site configs. For later minors, include every
+module promoted to `stable` in that release.
 
 Local checks that can be run from this repository: