Bartl startup mechanism

Technical Spec

This page explains the normative application contract in README.md, under Application contract and qualification. The startup mechanism is one contribution to Bartl's broader operating philosophy. The obligations apply per supported configuration; no particular container or Kubernetes architecture is prescribed.

Open the normative application contract

State selects the path, not the name of a requested operation.

Startup contract and inputs

Release, declared state and target configuration must be technically verifiable. A backup is optional and is queried only without local state. Startup requires neither a mode selector nor a separate initialization permission.

Input	Contract
Versioned release	An immutable application artifact with a known engine version and its product-specific migration logic.
Fully declared state	An inventory of owned mutable state, its consistency relationships and a reliably detectable state version. Foreign persistence is a dependency, not automatic permission to modify it.
Optional backup	The latest verified backup for this customer and application. No configured backup store, or a configured store containing no backup, means absence rather than failure.
Target configuration	Endpoints and credentials supplied by the target. They belong neither to the release nor to backed-up state.

Observations before action

observe_local_state() distinguishes valid local state with a known version from confirmed absence. Observation errors, damaged state and incomplete state stop startup.
observe_backup() runs only without local state. It returns the latest fully published and verified backup for the customer and application, or absence. Lookup and integrity errors stop startup instead of falling back to initialization.
The engine and state versions are equal, the engine is newer, or the engine is older.
Release, existing state, any backup used and target configuration must be complete and mutually consistent.

Observed startup path

The mechanism does not decide from an install, restore or upgrade label. Components may cooperate, but transition ownership and current completion signals must be unambiguous. Observe again after every state change.

until serving():
    local = observe_local_state()
    if local.exists:
        engine version vs local.version:
            equal:    serving()
            engine >: migrate(local)
            engine <: abort("downgrade")
    else:
        backup = observe_backup()
        if backup.valid: restore(backup)
        else:            init()

Evaluation

Valid local state and equal version: The application can serve.
Valid local state and newer engine: Native product-specific migration runs. Unsupported transitions or failures stop startup; success returns to observation.
Valid local state and older engine: Startup aborts because a downgrade is not permitted.
No local state and a valid backup: Native restore reconstructs the latest verified backup for the customer and application. Failure stops startup; success returns to observation.
No local state and no backup: Native initialization creates fresh state. Failure stops startup; success returns to observation. A failed backup lookup is not an absent backup.
Invalid, incomplete, contradictory or unknown inputs: Startup aborts before state is changed or served.

Mechanism invariants

An implementation follows the pattern only if it preserves these properties across every startup case.

One decision loop: Normal startup, first initialization, and restore begin with the same observation and use the same abort conditions.
Fail closed: Damaged or partially created state, incomplete backups, and contradictory versions are never reinterpreted as an empty startup state.
Verify before use: A backup is restored only after its publication, inventory, and integrity have been verified.
Migration belongs to the product: Bartl coordinates the transition. Existing native initialization and migration remain with the product; add only missing observation, coordination and verification.
Observe again: Initialization, restore, and migration return to the beginning. Only valid compatible state reaches serving().
Controlled abort: Downgrade, inconsistency, and missing prerequisites end visibly. The mechanism neither guesses replacement values nor skips checks.

Application duties

The application supplies concrete procedures for its own state. A common decision structure requires neither identical code nor a universal operator. Multiple components may cooperate through an explicit protocol.

State boundary: declare the complete owned inventory and consistency relationships; change foreign or shared persistence only within explicitly assigned responsibility.
Observation: reliably distinguish empty, valid, incomplete, damaged and unknown state and its relevant version; a marker alone is insufficient.
Lifecycle: derive normal start, initialization, restore and migration from the same observations; native failures stop startup, successful changes return to observation.
Capture and reconstruction: produce complete consistent recovery points, verify before use and restore without the source; identify software, keys and target prerequisites.
Safe execution: handle interruption, repetition and conflicting changes; stale completion signals and unverified partial state must not release serving.
Result verification: verify native transition results before normal startup and expose machine-readable failures. Package qualification demonstrates agreed application behavior; it is not a privileged acceptance ceremony on every restart.

Meaning of serving()

serving() starts the native application with its normal readiness behavior. Successful reconstruction needs no second technical release command. The complete service contract covers source isolation, fencing, reachability, activation and recovery time. People authorize the outcome and accepted risks; maintained procedures must enforce that decision technically.

Evidence for catalogue inclusion

Start with one justified supported configuration per application, declaring releases, transitions, persistence and target prerequisites. The following cases require executable evidence with exact artifacts and claim boundaries. Individual passing cases are not complete qualification; a shared test runner is not prescribed.

First initialization: confirmed empty owned state produces a usable installation through native initialization, both without a configured backup store and with a configured store containing no backup.
Normal restart: valid state and identity survive without backup access, reinitialization or unnecessary restore.
Source-independent restore: the latest verified complete backup for the customer and application restores the intended data, identities and permissions.
Release transition: supported native migration succeeds; unknown transitions and downgrades are rejected without destructive fallback.
Interruption and repetition: partial state is recognized; retry, conflicting execution and stale completion signals remain safe.
Missing or contradictory inputs: unreachable storage, damaged data and incomplete backups never authorize an empty installation.
Foreign state: an application failure does not reset a shared database or another service.
Application acceptance: package qualification demonstrates agreed usability after each supported transition; a successful container or job is insufficient.

Executable WordPress reference

bartl-wordpress illustrates the startup mechanism for one concrete WordPress, MySQL, and Docker Compose configuration. The details below describe the existing reference, not additional normative startup conditions. Its evidence does not automatically qualify every catalogue case.

Declared state: MySQL database and wp-content/uploads
Immutable release: WordPress core, plugins, and themes in the image
Backup format: database.sql, uploads.tar, state.json, and SHA256SUMS in one archive
Publication: Archive plus .sha256 sidecar, with the sidecar published last as the commit marker
Restore: Newest fully published backup on an empty compatible target
Failure behavior: On an empty target, abort on a missing store mount; always abort on an incomplete pair, checksum failure, or invalid inventory

Open the reference and runbook on Codeberg

Claim boundary

The spec describes only the startup mechanism for the application and its declared state.

Part of the startup mechanism

observe state and versions
verify backups before use
initialize, restore, or run product-specific migration
serve valid state or abort in a controlled way

Not covered by the startup mechanism

provision target infrastructure, network, DNS, TLS, or identity
operate external backup storage
supply generic backup or migration logic for other products
guarantee availability, target quality, or restart time
coordinate traffic or write authority
replace a complete operations or recovery process

The WordPress reference demonstrates these properties only for its pinned configuration. Other applications need their own state inventory, backup format, migration logic, and executable evidence.

Back to the landing page