BaseHarbor v0.4.11

BaseHarbor v0.4.11

v0.4.11 focuses on repository adoption and developer experience while preserving the provider-neutral BaseHarbor architecture.

Highlights

• Existing repositories can be inspected locally or through normal HTTPS/SSH Git URLs.
• baha app init continues to generate the smallest portable contract from deterministic evidence.
• baha up -e ENV / --environment ENV selects deployment context without rewriting portable application intent.
• Repository-aware shortcuts: baha plan, baha status, baha doctor.
• Secret-safe structured read-only output through -o json / --output json for inspect, plan, status and doctor.
• Optional bounded AGENTS.md integration through baha app init --agents.
• The existing Compose implementation is documented as the local BaseHarbor Playground: the same lifecycle, security, bindings, readiness and ownership model, not a separate toy runtime.
• New five-minute onboarding documentation in English and German.
• Bash, Zsh and Fish completion with descriptions and environment value completion.
• A shared human-output system with stable columns and semantic states such as READY, VERIFIED, UPDATED and DELETED.
• Delayed contextual progress for slow lifecycle operations with plain line-oriented CI/non-TTY fallback.
• Global --quiet/--silent, --verbose and --no-color controls.
• Redesigned status and doctor trust views with grouped sections, final health state and actionable next steps.
• A read-only baha tui dashboard with Overview, Status and Doctor tabs.
• --no-input/ --non-interactive for strict automation, --plain for styling-free human output and root baha --version.
• Terminal-width-aware result/help wrapping, TTY-only paging, typo suggestions, dynamic local app-name completion and silent broken-pipe handling.

Final acceptance hardening

The final v0.4.11 release candidate was exercised against a clean MailFlow repository through the real lifecycle rather than only unit-level paths.

Validated flows include:

• fresh repository adoption and startup;
• repeated READY baha up as a true no-op;
• down -> STOPPED -> up -> READY with persistent state preserved;
• encrypted application backup and verified restore;
• strict fast-forward baha app update;
• required/generated OpenBao secrets;
• runtime broker and TLS readiness;
• ownership-safe destroy and partial-runtime recovery behavior.

The acceptance round also closed several developer-experience gaps:

• configurable workload host ports are resolved before the first Compose start instead of waiting on a later bind failure;
• undeclared logs/metrics/traces/provider checks stay absent from normal output;
• development no longer invents log collection intent;
• fresh OpenBao recovery prompts render the question and shell-style path prompt reliably;
• Ctrl-C cancels long-running lifecycle work promptly and restores terminal state;
• status/doctor required-secret reads are batched instead of performing repeated full OpenBao scope/login/read cycles;
• baha app update --check explains the exact dirty Git paths and change classes that block an automatic update.

These changes preserve the same fail-closed ownership, secret and provider boundaries. Performance improvements do not skip security verification.

Repository adoption

Inspection remains read-only and classifies evidence as Detected, Suggested or Possible. Remote inspection clones into temporary state and delegates authentication to Git. BaseHarbor rejects remote URLs with embedded credentials.

Weak or ambiguous evidence is never silently promoted into application intent. Existing provider/runtime ownership remains explicit and is not silently replaced.

Structured output

The following forms are supported:

baha app inspect . -o json
baha plan -o json
baha status -o json
baha doctor -o json

Human, JSON and TUI status/doctor surfaces use the same readiness model, including repository TLS health. Doctor JSON is derived directly from preflight results. Required-secret output contains readiness metadata only and never secret values.

Structured doctor output is read-only; doctor --fix -o json is rejected.

Agent repository guidance

baha app init --agents

BaseHarbor creates or updates only the bounded BaseHarbor section in AGENTS.md. Existing unrelated instructions are preserved. Repeated runs are idempotent and malformed/ambiguous managed markers fail closed.

This is repository guidance only. The agent-native machine interface and MCP server remain planned for v0.4.12.

Terminal experience

v0.4.11 treats the CLI as a product surface rather than a stream of implementation logs.

Human output now follows a small semantic vocabulary:

• CREATED / UPDATED / DELETED / REMOVED for mutations;
• STARTED / STOPPED / READY for runtime state;
• VERIFIED for protocol or data-path verification;
• FAILED, DEGRADED and SKIPPED where appropriate;
• OK only for checks that have no more precise state verb.

Status and doctor are intentionally scan-oriented. They group information by application, services, workload, observability and exposure instead of emitting one flat technical list. Expected failures include next actions and keep the non-zero exit code without printing a second duplicate generic error block.

Progress is delayed so short commands do not flash. When work takes noticeable time, BaseHarbor shows what it is waiting for. It never invents percentages or ETAs.

Interactive terminals may use color and a compact activity animation. Non-TTY/CI output stays static and line-oriented. NO_COLOR, TERM=dumb, --no-color and BASEHARBOR_REDUCED_MOTION=1 are respected.

Shell completion

baha completion bash
baha completion zsh
baha completion fish

Completion is deterministic and read-only. It covers command/subcommand discovery, common flags and useful fixed values such as dev, test and prod.

Interactive TUI

baha tui

The v0.4.11 TUI is intentionally read-only. It reuses BaseHarbor's structured application Status and Doctor models instead of introducing a second lifecycle or diagnostic implementation.

Views:

• Overview — application/environment identity and compact overall health;
• Status — grouped services, workload, observability and exposure state;
• Doctor — structured checks and actionable next steps.

Keys: Tab / arrows switch views, r refreshes, and q / Esc / Ctrl-C exits.

The TUI requires a real application-repository terminal. It fails closed under --plain, --no-input, pipes and CI and directs automation to status -o json.

Final CLI ergonomics

--no-input guarantees no prompt can be opened by the guided startup/init/backup/restore/recovery paths. Missing operator decisions are returned as actionable usage errors instead of guessed.

--plain disables color and animated redraw while retaining semantic human output. Human detail rows and help descriptions wrap at terminal width, with continuation lines aligned under the detail column. Long help may use $PAGER only on an interactive TTY.

Configured application names can be completed from local BaseHarbor state without contacting providers. Common command and option typos provide nearest-match suggestions.

Deployment/runtime input precedence is documented as:

explicit CLI flag/input
  > process environment
  > protected local deployment state
  > safe BaseHarbor default

Portable application intent remains separate from these deployment choices.

Fast status snapshots

baha status is intentionally a fast snapshot, not a convergence or retry loop. Runtime-broker and provider checks are bounded by a short overall status budget; deeper diagnosis belongs to baha doctor and baha status --verbose.

Normal status output keeps implementation diagnostics such as Compose exec commands, curl invocations and raw OpenBao errors out of the primary view. Those details remain available in verbose mode.

Repository TLS state is rendered as a normal TLS section inside the same status hierarchy, so the final READY, STOPPED or DEGRADED summary is always the last state shown.

baha doctor follows the same rule. Normal doctor output summarizes actionable failure causes without leaking raw Compose commands, curl probes or OpenBao shell invocations; those details remain available with --verbose. Duplicate workload problem blocks and empty workload-service sections are omitted, TLS appears inside the doctor hierarchy, and the final health state remains last.

The TUI reuses the same concise human-detail mapping for its Status and Doctor views, keeping interactive output aligned with the CLI rather than exposing raw provider or Compose diagnostics.

Cross-command lifecycle audit

The final v0.4.11 audit tightened lifecycle consistency across repository commands rather than patching individual symptoms:

• rendered Compose security preflight now supplies non-sensitive placeholders only for BaseHarbor-declared required secrets, so security analysis never depends on reading the real OpenBao value;
• undeclared missing environment variables still fail closed;
• every repository workload start is guarded again immediately before start, covering apply, up, restore, backup restart and TLS reload/rollback paths;
• restore performs workload-security validation before destructive restore mutation;
• baha app preflight now includes repository workload security explicitly;
• doctor --fix uses the normal apply path after control-plane recovery; no repair-only security bypass remains;
• repository-manifest absence is represented by a typed sentinel error instead of parsing error-message text;
• legacy repair logic that parsed rendered [FAIL] output was removed completely;
• status/doctor JSON and the TUI now include the same TLS health used by human output.

BaseHarbor v0.4.10

BaseHarbor v0.4.10

v0.4.10 completes the first generic observability path in BaseHarbor and adds Tempo as the trace-storage reference provider without turning observability products into application requirements.

The release is deliberately about platform architecture, not adding another bundle of infrastructure products.

Provider observability without core product branches

Provider Integration Contract v1 can now describe provider-owned observability signals.

A running provider may register a safe OpenMetrics endpoint with BaseHarbor. The metrics platform consumes those registrations generically, so Prometheus does not need product-specific branches for Loki, Tempo, the OpenTelemetry Collector or future conforming providers.

Collection remains policy-controlled. A declaration says that a signal exists; it does not automatically authorize collection.

Shared Prometheus instances filter application-scoped provider signals by the applications registered in that exact sharing boundary. Provider sharing therefore does not create cross-application observability access.

The first managed providers using this mechanism are:

• OpenTelemetry Collector;
• Loki;
• Tempo.

Providers that do not expose a suitable metrics endpoint are unaffected.

Trace storage remains separate from OTLP transport

Applications continue to describe trace export through telemetry.otlp/v1. They do not request Tempo.

When deployment policy enables managed trace retention:

export BASEHARBOR_TRACES_ENABLED=true
baha app up

BaseHarbor:

1. provisions/reuses the shared Tempo reference provider;
2. connects the managed OpenTelemetry Collector to Tempo over a BaseHarbor-managed provider network;
3. exports the normal BaseHarbor OTLP verification trace through the Collector;
4. queries that same trace from Tempo;
5. reports the trace path ready only after real ingestion is proven.

Tempo 3.0.2 is the first Compose reference implementation of the provider-neutral traces/v1 platform contract.

Deliberately narrow placement support

v0.4.10 does not pretend to support isolation modes that the current Compose path cannot safely realize.

The Tempo reference adapter supports the default shared placement. Application-scoped, external and named-sharing-boundary Tempo placement are rejected before mutation.

This is intentional fail-closed behavior. Future providers/adapters may implement additional placements through the same contract without changing application intent.

Metrics behavior

When metrics collection is enabled, BaseHarbor now collects:

• declared application metrics/v1 sources;
• policy-authorized application-provider metrics;
• policy-authorized platform-provider metrics.

Provider targets are reconciled automatically and verified with a real Prometheus up=1 sample.

Prometheus joins only the provider networks required by the selected registrations. This collector reachability does not grant workloads or applications access to those provider networks.

Compatibility

Manifest v1 remains unchanged.

Existing application metrics, runtime-created metrics sources, centralized logs and OTLP transport remain compatible. No Tempo, Prometheus, Loki or provider-observability product detail is added to portable application intent.

Trace retention is opt-in deployment policy. Applications that already export OTLP traces continue to work exactly as before when managed trace storage is disabled.

Security

• Tempo runs as non-root.
• Its root filesystem is read-only.
• All Linux capabilities are dropped.
• no-new-privileges is enabled.
• Only explicit persistent storage and tmpfs paths are writable.
• The host-facing Tempo API is bound to loopback.
• Shared metrics collection filters provider signals by placement, sharing boundary and authorized application registrations.
• Provider observability registry state contains no credentials or secret values.
• Unsupported trace-provider placements fail before mutation.

Intentionally deferred

• Grafana is not part of v0.4.10 and is now post-v0.5 ecosystem work.
• Tempo application-scoped/external/named-boundary adapters are not implemented.
• Existing PostgreSQL, Valkey, OpenBao, SeaweedFS and Caddy providers are not given synthetic exporters merely to make them appear in Prometheus. They will advertise metrics only when their provider implementation exposes a safe supported signal.
• Kubernetes/OpenShift/cloud runtimes remain later runtime tracks.
• Broader policy/evidence work is scheduled for the new productized v0.4.13-v0.4.15 roadmap.

BaseHarbor v0.4.9

BaseHarbor v0.4.9

v0.4.9 adds centralized workload log collection without putting Loki into the portable application contract, and hardens the provider/runtime boundary that the rest of the v0.4 line depends on.

Centralized logs without product coupling

Repository workloads can now be collected through the provider-neutral logs/v1 lifecycle. Deployment policy decides whether collection is enabled and which provider placement is used.

The first Compose reference implementation uses:

• Grafana Loki 3.7.8 for log storage/query;
• Grafana Alloy 1.19.2 as the collection/forwarding component;
• shared placement by default, including optional named sharing boundaries;
• application placement for a dedicated application/environment provider.

Applications do not request Loki. BaseHarbor derives workload log sources from the selected repository Compose services and records the logical resources and provider placement in the protected provider registry.

Development enables application log collection by default. Test, staging and production remain opt-in through deployment policy.

Zero-trust workload preflight

Before BaseHarbor starts a repository workload it now evaluates the fully rendered Compose configuration for isolation bypasses.

The preflight detects privileged containers, runtime socket mounts, host networking, host PID/IPC namespaces, dangerous Linux capabilities, host devices and critical host filesystem mounts. Results are machine-readable and classified as allow, warn or deny.

Managed/non-development environments fail closed for isolation-breaking settings. Development can acknowledge explicitly supported exceptions, but no warning can silently bypass a deny policy.

BaseHarbor-managed Compose services are hardened as unprivileged runtimes. PostgreSQL, Valkey, OpenBao, Caddy, SeaweedFS, the OpenTelemetry Collector, Prometheus, Loki, Alloy and BaseHarbor's broker/executor/relay paths run with an explicit non-root identity or a BaseHarbor image that is itself non-root. Where technically supported they use read-only roots, drop all Linux capabilities, enable no-new-privileges and expose only required writable volumes/tmpfs. Loki and Alloy receive no Docker/Podman socket.

Compose-specific service UIDs are deployment detail. BaseHarbor-owned runtime images also prepare writable state directories for platform-assigned arbitrary non-root UIDs so future OpenShift/Kubernetes adapters do not need to inherit a fixed Compose UID. A provider image that cannot satisfy a target runtime's non-root/arbitrary-UID policy must be rejected for that runtime instead of requiring elevated privileges.

Executable provider conformance

The Provider Integration Contract v1 now has reusable executable lifecycle conformance tests rather than descriptor-only checks.

The suite exercises:

• unsupported placement failing before mutation;
• side-effect-free preflight;
• create followed by idempotent no-op convergence;
• binding and verification;
• deterministic drift/repair;
• provider failure between lifecycle phases;
• verify failure never becoming READY;
• retry convergence without unnecessary resource identity changes;
• ownership-safe destroy;
• secret-safe diagnostics.

A deterministic in-process fake provider drives fault-injection tests. The Loki reference provider consumes the same conformance harness.

Provider/core cleanup

The v0.4.9 audit removed a duplicated provider-descriptor switch in the application registry and now resolves descriptors through the canonical Provider Integration Contract registry. Remaining provider/placement switches are authoritative mapping points or provider-internal topology decisions rather than duplicated lifecycle knowledge.

Compatibility and upgrade impact

Manifest v1 is unchanged. Existing PostgreSQL, Valkey, OpenBao, Caddy, S3, OTLP, Prometheus and Runtime Resource API behavior remains compatible.

Log collection is deployment/platform behavior rather than a new product field in baseharbor.yaml. Existing repositories therefore do not need a manifest migration.

When logs are enabled, BaseHarbor adds a generated Compose logging override for selected workload services. Application-owned Compose source and volumes are not rewritten or taken over.

Security notes

• BaseHarbor-managed Compose containers must not require UID 0 for normal operation; validation checks both the configured user and the effective process UID.
• The bundled OpenBao service starts directly as non-root openbao, uses a read-only root filesystem, writes generated local config to an ephemeral writable /openbao/config tmpfs and suppresses privileged entrypoint chown attempts with the image-supported SKIP_CHOWN mode.
• BaseHarbor-owned runtime images prepare writable state paths for arbitrary platform-assigned non-root UIDs.
• Loki/Alloy receive no Docker or Podman socket.
• Loki API and Alloy syslog listeners are host-loopback only; provider-internal traffic stays on an internal network while a separate provider bridge exists only to realize those loopback host bindings.
• provider registry/state files are owner-only;
• log labels contain application/environment/service identity, not credentials;
• workload security analysis runs before workload mutation;
• unsupported provider placement fails closed;
• production-like environments cannot use development-only security acknowledgements.

Intentionally deferred

• Kubernetes/OpenShift runtime support is not part of v0.4.9.
• External Loki/provider loading is not implemented; the integration descriptor advertises only placements the current Compose adapter can realize.
• Grafana and Tempo are not provisioned by logs.
• Loki HA/object-storage topologies remain future provider profiles. The current single-binary reference topology uses provider-local persistent filesystem storage; a future topology that requires S3 must use provider-internal storage dependency wiring rather than granting an application S3 capability.
• A broad dynamic provider plugin runtime remains deferred.

BaseHarbor v0.4.8

BaseHarbor v0.4.8

v0.4.8 turns the capability platform into something applications can use not only at deployment time, but also while they are running.

The release combines four related steps:

1. continuous repository-to-contract reconciliation;
2. secure application-time resource operations, with S3 as the first real dynamic resource;
3. provider-neutral metrics collection with Prometheus as the first Compose reference provider;
4. explicit directional cross-application connectivity without weakening application isolation.

The application contract stays product-neutral throughout. BaseHarbor adds more infrastructure behavior without requiring applications to become BaseHarbor-specific.

Continuous application evolution

BaseHarbor now treats application intent as evolving desired state rather than a one-time setup questionnaire.

Repository inspection can distinguish capabilities that are already satisfied from new, ambiguous or stale evidence. Newly detected requirements remain suggestions until explicitly accepted; failure to rediscover an existing capability never authorizes BaseHarbor to remove it.

Runtime-operation evidence is also separated from authorization. Detecting code that may create an S3 bucket or register a metrics source does not grant that operation automatically.

This gives BaseHarbor one path from initial adoption through later application growth without regenerating or replacing the application's contract.

Runtime Resource API

v0.4.8 completes the first real application-time resource path.

A running application can use the per-application Runtime Resource API for explicitly authorized capability operations. Mutations are asynchronous and idempotent, with persistent operation state that survives broker restart.

The security boundary remains strict:

• the per-application broker has no Docker/Podman socket;
• provider-global administrator credentials never enter the application workload or broker;
• authorization is service-scoped rather than application-wide;
• runtime resources remain application-owned;
• cross-application read/bind/delete is denied;
• secret-bearing bindings are returned only through the authenticated binding path;
• operation metadata remains free of credentials.

Development brokers also expose the embedded OpenAPI 3.1 documentation on a loopback-only port. Interactive API documentation is on by default for development and remains off by default for test/staging/production.

Dynamic S3 resources

object-storage.s3/v1 is the first capability wired through the Runtime Resource API.

An authorized application service can create, inspect and delete an S3 bucket at runtime. BaseHarbor executes the provider mutation through the shared mTLS Runtime Provider Executor rather than giving the application provider-global credentials.

SeaweedFS remains the first reference provider. Runtime-created buckets receive scoped credentials and can be consumed through the normal S3 API with authenticated Put/Get verification.

The same application-facing capability remains suitable for future Ceph RGW, AWS S3 or other conforming providers.

Provider-neutral metrics

Applications can declare a normal OpenMetrics-compatible endpoint:

workload:
  compose: compose.yaml
  services:
    - api

metrics:
  sources:
    - name: application
      service: api
      port: 8080
      path: /metrics

That source is represented by metrics/v1. There is no prometheus: true field and no Prometheus target configuration in baseharbor.yaml.

Prometheus 3.14.0 is the first Compose reference provider.

BaseHarbor:

• detects conventional OpenMetrics//metrics repository evidence;
• generates file-discovery targets automatically;
• labels series with application/environment/service/source identity;
• requires a real successful scrape visible as up=1;
• supports both statically declared and explicitly authorized runtime-created metrics sources;
• does not start Grafana, Loki or Tempo as a side effect.

Generic provider placement

During the metrics implementation, v0.4.8 closes a broader architecture gap.

Provider placement is now an explicit generic BaseHarbor domain:

Capability
  -> Provider
  -> Placement
       - application
       - shared
           - optional sharing boundary
       - external
  -> Runtime realization of the selected placement

The normal developer path remains simple. BaseHarbor chooses safe defaults unless an operator deliberately asks for more control.

For Prometheus the current Compose implementation supports:

• shared — the safe default;
• shared with a named sharing boundary;
• application — a dedicated application-scoped Prometheus instance.

The generic model supports external, but the Prometheus reference provider does not advertise external placement in v0.4.8 because an external metrics collection adapter is not implemented yet. Such a request fails before mutation instead of being silently downgraded.

Advanced Compose operators can currently override Prometheus placement through deployment state:

BASEHARBOR_PROVIDER_PROMETHEUS_SCOPE=shared|application
BASEHARBOR_PROVIDER_PROMETHEUS_SHARING_BOUNDARY=<name>

This follows BaseHarbor's UX rule:

Convention by default, configuration by choice.

Provider placement remains outside portable application intent.

The placement scopes now have strict provider-instance meaning:

• application is a dedicated provider instance for exactly one application/environment; Compose realizes it with dedicated provider runtime state;
• shared is lazy BaseHarbor Platform/Core Runtime infrastructure and remains shared even when only one application currently consumes it;
• external remains outside BaseHarbor lifecycle ownership.

Explicit cross-application connectivity

v0.4.8 also adds a minimal platform-level connectivity policy for cases where isolated applications must communicate:

app-a/api -> app-b/sql

The rule is written once. It is not duplicated in both application contracts and it is independent from provider sharing.

BaseHarbor resolves the concrete environment, runtime service, target network and target TCP port from runtime state. Explicit environment or port qualification is required only when resolution is ambiguous.

Compose preserves the direction technically. Source and target are not placed on one common bridge network. BaseHarbor creates a connection-specific source link and a hardened relay from the version-matched BaseHarbor Runtime image. Only the source and relay join that link; the relay additionally joins one target network and forwards only to the resolved target service/port. The target never joins the source link.

The relay has no host-published port or Docker/Podman socket, runs non-root with a read-only root filesystem, drops Linux capabilities and enables no-new-privileges.

Connectivity policy survives app down; relay runtime is suspended and reconciled on later app up/apply. Application/global destroy fails closed while connectivity policy still references managed applications.

Zero-Trust metrics isolation

Shared does not mean flat access.

Every participating application receives its own isolated metrics network. Shared Prometheus is attached only to the application networks explicitly registered for its placement boundary.

This means five applications can safely use different shapes on one BaseHarbor installation, for example:

App A + B -> shared/default
App C     -> application-scoped
App D + E -> shared/team-x

without exposing D/E's provider trust boundary to A/B.

Runtime metrics registration is service-scoped. A service can register only itself, and the runtime API accepts target port/path semantics rather than arbitrary hosts or URLs. BaseHarbor derives the actual scrape identity server-side.

Target state contains no application credentials or provider-global secrets.

Placement changes are lifecycle-safe

Provider placement is persisted in the protected provider registry.

Lifecycle cleanup therefore uses the registered/current placement rather than assuming that today's environment override still matches the placement used during the previous apply.

When placement changes, BaseHarbor converges and verifies the new metrics path first, then removes the previous provider target/trust-edge state, and only afterward reconciles the provider registry.

Runtime-only metrics permissions also receive protected provider-registry state even when no static metrics.sources entry exists.

Collection policy

Metrics collection remains separate from provider placement.

Compose defaults:

• dev / development: enabled;
• test / staging / production: disabled;
• BASEHARBOR_METRICS_ENABLED=true|false: explicit operator override.

An application can keep metrics/v1 intent while collection is disabled for a deployment. In that case BaseHarbor does not resolve or provision a metrics provider.

Global and application lifecycle

Application destroy removes only the application's metrics state according to the registered placement:

• shared placement removes that application's targets and trust-edge registration;
• application placement removes the dedicated Prometheus instance;
• external providers remain externally lifecycle-owned.

Global baha destroy --yes enumerates and removes every BaseHarbor-owned shared Prometheus instance, including named sharing boundaries.

Shared provider lifetime remains independent from a single application. Global baha down stops existing shared Platform/Core Runtime provider containers without deleting their networks, volumes or provider state; baha up resumes those providers and reconciles persisted cross-application connections. Application-scoped provider runtimes remain owned by their application lifecycle.

Compatibility and upgrade impact

Manifest version remains 1.

Existing applications without metrics intent r...

BaseHarbor v0.4.7

BaseHarbor v0.4.7

BaseHarbor v0.4.7 adds a provider-neutral OpenTelemetry Protocol (OTLP) transport foundation before the individual metrics, logs and traces platforms planned for the next releases.

Why this matters

Applications should be able to emit telemetry without depending on which observability products an environment uses.

v0.4.7 makes that boundary explicit:

application instrumentation
        |
        | telemetry.otlp/v1
        v
OTLP transport/binding
        |
        +-- shared OpenTelemetry Collector today
        +-- external OTLP destination
        +-- other conforming providers later

OpenTelemetry is the ecosystem and instrumentation model. OTLP is the portable protocol. The OpenTelemetry Collector is one provider implementation, not part of application identity.

Added

• Versioned telemetry.otlp/v1 Capability Specification.
• Manifest v1 OTLP signal declarations for traces, metrics and logs.
• OTLP HTTP/protobuf export as the initial v1 transport.
• OpenTelemetry Collector 0.161.0 as a lazy shared Compose reference provider.
• External OTLP destination support without BaseHarbor taking lifecycle ownership.
• Standard OpenTelemetry workload bindings:
  • OTEL_EXPORTER_OTLP_ENDPOINT
  • OTEL_EXPORTER_OTLP_PROTOCOL
  • OTEL_SERVICE_NAME
  • OTEL_RESOURCE_ATTRIBUTES
• Common application/environment/workload/resource/provider identity.
• Secret-safe provider lifecycle instrumentation hooks for preflight/apply/bind/verify.
• Real OTLP export verification using a protobuf trace accepted by the selected endpoint.
• Capability, manifest, binding, negative and real Collector acceptance coverage.

Changed

OTLP now follows the same shared BaseHarbor lifecycle as other provider-backed capabilities:

resolve
  -> preflight
  -> provision
  -> bind
  -> verify

The managed Collector is created only when an application explicitly requests OTLP transport. Multiple applications may reuse that shared provider while their logical telemetry resources remain application-owned.

Repository workloads using the managed Collector attach to a dedicated BaseHarbor telemetry network. External OTLP destinations do not create or own a BaseHarbor Collector.

Application contract

An instrumented application can declare the signals it exports without naming an observability product:

workload:
  compose: compose.yaml
  services:
    - api
    - worker

telemetry:
  otlp:
    signals:
      - traces
      - metrics

BaseHarbor injects the resolved endpoint and standard OpenTelemetry resource identity into the selected workloads.

External OTLP destinations

A deployment can bind an existing endpoint without changing portable application intent:

export BASEHARBOR_OTLP_ENDPOINT=https://otel.example.com

Optional authorization headers use BASEHARBOR_OTLP_HEADERS. These are deployment/runtime inputs and are never written into the portable application manifest.

Verification

Readiness does not mean that a Collector container exists.

BaseHarbor sends a real OTLP HTTP/protobuf trace to the resolved endpoint and requires the endpoint to accept it. This proves the transport/binding path that later Prometheus, Loki and Tempo integrations will build on.

Security

• OTLP credential/header material is not part of baseharbor.yaml.
• Provider-registry and portable capability metadata contain no plaintext telemetry credentials.
• External provider lifecycle ownership remains external.
• Invalid or missing OTLP binding semantics fail before provider mutation.
• Global destroy removes only the BaseHarbor-owned shared Collector.

No implicit observability stack

Requesting telemetry.otlp/v1 does not provision:

• Prometheus;
• Loki;
• Tempo or Jaeger;
• Grafana;
• dashboards or alerting.

Those remain separate platform/provider concerns and are intentionally handled by later capability releases.

Deprecated

Nothing.

Removed

Nothing.

Compatibility & upgrade notes

• Manifest version remains 1.
• Existing manifests require no migration.
• OTLP is additive and opt-in.
• Existing PostgreSQL, Valkey, OpenBao, secure bindings, managed exposure and S3 behavior remains compatible.
• Compose remains the complete current runtime implementation.
• Applications continue using standard ecosystem protocols and configuration; no BaseHarbor SDK is required.

Intentionally deferred

• OTLP/gRPC application binding.
• Receive-mode/application-hosted OTLP endpoints.
• Prometheus metrics platform integration.
• Loki log platform integration.
• Tempo/Jaeger trace platform integration.
• Grafana dashboards.
• Advanced sampling/routing policy.
• OpAMP/control-plane management.
• Kubernetes/OpenShift collector deployment.

BaseHarbor v0.4.6

BaseHarbor v0.4.6

BaseHarbor v0.4.6 adds provider-neutral S3-compatible object storage as the next real capability behind the shared provider contract.

Why this matters

Applications often need object storage long before they need a full observability or AI/RAG stack. BaseHarbor now lets an application request logical S3 buckets without coupling the application contract to SeaweedFS, Ceph, AWS or another storage product.

The same separation used for databases, secrets and managed exposure now applies to object storage:

application intent
  object-storage.s3/v1
        |
        v
provider boundary
        |
        +-- SeaweedFS today
        +-- Ceph RGW / AWS S3 / other conforming providers later

Added

• Versioned object-storage.s3/v1 Capability Specification.
• Manifest v1 object-storage declarations with one or multiple logical buckets.
• --s3 and repeatable --s3-bucket NAME application-init/create paths.
• SeaweedFS 4.47 as the first lazy shared Compose reference provider.
• Bucket-scoped SeaweedFS IAM identities and credentials.
• Provider-neutral secure-binding/v1 metadata for S3 access.
• Standard S3/AWS-compatible host and workload bindings.
• Authenticated AWS SigV4 Put/Get readiness in apply, up, status and doctor.
• Provider-registry ownership for the shared SeaweedFS instance and application-owned logical buckets.
• Real Docker/Compose acceptance coverage for the S3 lifecycle.

Changed

• Object-storage provider lifecycle now uses the shared plan/preflight/provision/bind/verify path.
• SeaweedFS administrative IAM commands are delivered through stdin so per-bucket credentials never appear in process arguments or runtime error messages.
• Application backup/restore fails closed while S3 object contents are outside the recovery unit.

Application contract

A repository can request object storage without naming a product:

services:
  object_storage:
    buckets:
      attachments: {}
      exports: {}

or:

baha app init mailflow \
  --s3-bucket attachments \
  --s3-bucket exports

Provider-native bucket names, IAM identities, ports, storage topology and SeaweedFS configuration remain protected provider/deployment state.

Application-facing bindings

For an unambiguous preferred bucket BaseHarbor publishes normal S3/AWS configuration such as:

S3_ENDPOINT
S3_BUCKET
S3_REGION
AWS_ENDPOINT_URL
AWS_REGION
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY

Named buckets additionally receive S3_<NAME>_* variables and protected file bindings.

Repository workloads use the internal provider endpoint through a BaseHarbor-owned object-storage integration network. Host-side processes use a loopback-only endpoint. Applications need no BaseHarbor SDK or runtime login.

Security

• Each logical bucket receives separate credentials scoped to that bucket.
• SeaweedFS IAM is explicitly enabled.
• BaseHarbor does not persist a global S3 superuser credential for the reference provider.
• S3 credential files are owner-only.
• baha app env masks S3 access-key and secret-key values by default.
• Plaintext credentials do not enter portable capability metadata, provider-registry records or normal diagnostics.
• A shared provider process does not imply shared bucket authorization.

Readiness and lifecycle

Success is not based on a running SeaweedFS container. BaseHarbor signs a real S3 request and verifies a Put/Get flow with the application's bucket-scoped credentials.

baha app down preserves the shared provider and bucket data. baha app destroy --yes removes only the application's managed buckets/identities and state. The shared provider remains available for other applications and is removed only by global baha destroy --yes after application bindings are gone.

Recovery boundary

Object contents are not yet part of the BaseHarbor encrypted application recovery unit. v0.4.6 therefore fails closed for baha app backup and baha app restore when managed object storage is declared. BaseHarbor will not present an incomplete S3 recovery as successful backup/restore.

Deprecated

Nothing.

Removed

Nothing.

Compatibility & upgrade notes

• Manifest version remains 1.
• Existing manifests require no migration.
• PostgreSQL, Valkey, OpenBao, secure bindings, managed exposure and existing Compose workflows remain compatible.
• Object storage is additive and opt-in; no SeaweedFS runtime is created unless an application explicitly requests S3.
• SeaweedFS is a reference implementation, not application identity.

Provider replacement

The capability lifecycle, Provider Integration Contract v1, provider registry and conformance tests prove that the same logical S3 request can be satisfied by another conforming driver without changing application intent.

The current public v0.4.6 workflow selects the built-in SeaweedFS reference implementation for managed Compose object storage. General dynamic external-provider loading/selection remains separate platform work; no product-specific fields are added to the application contract in anticipation of it.

Intentionally deferred

• Generic dynamic external-provider loading and public provider-selection policy.
• Ceph RGW, AWS S3 and cloud/provider adapters as shipped BaseHarbor provider implementations.
• Object-storage data capture/restore inside BaseHarbor application recovery units.
• Application-requested replication/topology/tiering/versioning policy.
• Public object-storage endpoint exposure.
• Kubernetes/OpenShift object-storage runtime/provider mappings.

BaseHarbor v0.4.5

BaseHarbor v0.4.5

BaseHarbor v0.4.5 adds a shared secure-binding and workload-identity foundation for capability providers.

Why this matters

BaseHarbor already had strong security primitives in the Compose/OpenBao path: application-scoped OpenBao access, a runtime broker, mTLS, protected binding files, required/generated secrets, identity rotation and revocation behavior.

Until now, those pieces existed mainly as implementation-specific runtime behavior. v0.4.5 extracts the stable security semantics into the shared capability/provider domain so later SQL, S3, messaging, vector, AI and MCP providers do not each invent their own credential and trust plumbing.

Added

• secure-binding/v1, a provider-neutral binding specification for workload identity, credential references, trust material, authorization metadata, secret references and security lifecycle declarations.
• Secure binding metadata on the shared capability Binding model used below CLI-specific code.
• SPIFFE workload identity mapping for the existing Compose/OpenBao runtime identity: spiffe://baseharbor/apps/<application>/<environment>.
• Machine-readable security diagnostics and explicit renewal/rotation/revocation support declarations.
• WorkloadBinding.security in baseharbor.provider/v1 so future external gRPC/Protocol Buffer providers consume the same security model.

Changed

• Managed secrets/v1 bindings now expose their existing identity, trust, authorization and required-secret semantics through provider-neutral references.
• Secure binding validation now happens during plan construction, before provider preflight and before any mutation.
• Credential, trust and secret references must be opaque baseharbor:// references; credential-bearing URLs and plaintext values are not valid binding references.

Security

• OpenBao AppRole names, RoleIDs, SecretIDs, policies, KV paths and PKI internals remain provider state.
• Tokens, passwords, private keys and secret values do not enter the secure-binding model, provider diagnostics or portable application intent.
• Application and environment identity remain isolated; different applications/environments receive distinct logical identity and credential references.
• Shared provider infrastructure does not imply shared authorization.
• Least-privilege authorization metadata is explicit and currently maps managed-secret workloads to read-only secret consumption.

Compatibility

• Manifest version remains 1 and no new application-facing security fields are required.
• Existing OpenBao, runtime-broker, mTLS, required/generated-secret and restore behavior remains authoritative and compatible.
• Compose remains the complete current runtime provider.
• Existing v0.4.4 exposure behavior is unchanged.

Intentionally deferred

• Human login, OIDC, RBAC, MFA, JIT elevation and breakglass remain v0.6 work.
• Full cross-provider zero-downtime credential/certificate rotation remains tracked separately.
• Managed public certificate issuance/renewal remains outside this release.
• A dynamic external provider loader is still not introduced.

BaseHarbor v0.4.4

BaseHarbor v0.4.4

BaseHarbor v0.4.4 adds the first provider-neutral traffic/exposure foundation while hardening the v0.4 lifecycle discovered through real-world regression testing.

Why this matters

Until now BaseHarbor could already discover application-owned Compose publishers and verify HTTP/HTTPS readiness, but that logic was still largely CLI/Compose-oriented. v0.4.4 separates two concepts that must stay independent:

• endpoint discovery/observation — understanding an application endpoint without taking ownership;
• managed exposure — explicitly asking BaseHarbor to make a logical workload endpoint reachable through HTTP/HTTPS.

Applications therefore keep ownership of existing publishers. BaseHarbor only provisions traffic infrastructure when the application contract explicitly requests managed exposure.

Added

The new exposure.http/v1 capability describes portable application intent:

workload:
  compose: compose.yaml
  services:
    - web

exposure:
  http:
    - name: public
      service: web
      port: 8080
      protocol: https
      visibility: public

The contract contains no Caddy-specific configuration. Concrete FQDN, host port, certificate source, Compose network and proxy configuration remain deployment/provider state.

Caddy is the first Compose reference provider. It is application-scoped in the provider registry and owns only its proxy/routing state. BaseHarbor's generated workload override owns the stable exposure integration network and attaches only explicitly exposed services; Caddy consumes that network as an external dependency.

visibility: public is the default host-facing realization. visibility: internal is loopback-only in the current Compose provider.

Changed

Existing app-owned HTTP/HTTPS readiness and managed exposure now use the same endpoint/probe semantics:

• redirects are reachable;
• HTTP 5xx is NOT READY;
• unreachable endpoints are NOT READY;
• logical workload service names are stable identities;
• generated Compose container names never become the application contract.

The same typed state feeds lifecycle verification, status/doctor and future API/Web UI/Operator surfaces.

Security

Managed exposure participates in the normal BaseHarbor lifecycle rather than a Caddy-specific side path:

resolve
  -> preflight all
  -> provision
  -> bind
  -> verify

It is coordinated with application apply/up, down/destroy, backup/restore and existing/BYOC TLS updates.

Failed new or changed Caddy realization rolls BaseHarbor-owned traffic state back. Application Compose source and application-owned persistent volumes are never deleted by the exposure provider.

v0.4 hardening included

This release also contains the regression fixes accumulated after exercising v0.4.0-v0.4.3 against real repositories and restart/destroy flows:

• repository manifests are authoritative over heuristic inspection evidence;
• quick init no longer promotes possible env-secret names into required secrets;
• intentionally stopped applications/control plane report STOPPED rather than failed readiness;
• provider-registry corruption fails during preflight before workload mutation;
• failed workload convergence cleans only resources created by the failed attempt;
• runtime mTLS identities are reused unless real rotation is required, preventing stale bind-mounted certificate/key inodes;
• app destroy --full-reset explicitly removes BaseHarbor-owned repository deployment/TLS state while preserving source and application-owned data;
• global baha destroy --yes provides ownership-aware control-plane cleanup;
• fresh OpenBao recovery-file UX is explicit and fail-closed.

Compatibility & upgrade notes

• Manifest version stays at v1.
• Managed exposure is optional and additive; existing manifests require no changes.
• Existing app-owned HTTP/HTTPS publishers keep their previous behavior and ownership.
• Compose remains the complete runtime implementation.
• Provider-specific traffic state is protected BaseHarbor state and does not need to be committed.
• Applications using managed HTTPS currently need the existing/BYOC TLS deployment mode.

Deprecated

Nothing is deprecated in v0.4.4.

Removed

Nothing from the supported v0.4.3 CLI, Manifest v1 workflow or application-owned publisher lifecycle is removed.

Intentionally deferred

v0.4.4 does not claim:

• managed ACME;
• OpenBao PKI certificate issuance;
• automatic certificate renewal/rotation;
• Traefik provider support;
• Kubernetes Gateway API or OpenShift Routes;
• cloud load balancers or service mesh;
• private OCI registry / air-gapped provider distribution.

Those remain separate follow-up tracks so this release keeps one small, testable provider contract.

BaseHarbor v0.4.3

BaseHarbor v0.4.3

BaseHarbor v0.4.3 makes repository understanding a first-class, deterministic capability and establishes the open provider-integration contract that later BaseHarbor integrations will follow.

The release is intentionally compatibility-preserving: Manifest v1 and the current Compose lifecycle remain unchanged.

What changed

Developers can now inspect an application repository without creating or changing anything:

baha app inspect .
baha app inspect . --json

The shared inspection core collects evidence from common Compose/Dockerfile files, dependency manifests, environment-variable names, source imports, configuration files, published ports and health checks.

Findings have explicit confidence:

• Detected — strong evidence that can safely feed non-interactive initialization;
• Suggested — useful evidence that still requires confirmation;
• Possible — weak evidence that BaseHarbor reports but never auto-selects.

Guided baha app init now reuses this same shared core rather than maintaining separate CLI-only detection logic.

Why it matters

Repository understanding is now reusable infrastructure instead of wizard-specific code.

Later S3, telemetry, messaging, AI/MCP and vector capability releases can add detectors to one engine and expose the same result through CLI, future Web UI/API and future Operator surfaces.

This also makes automation safer: machine-readable inspection output has explicit evidence and confidence instead of opaque guesses.

Provider ecosystem foundation

v0.4.3 also includes the Provider Integration Contract v1 work completed after v0.4.2.

BaseHarbor now has:

• versioned Capability Specifications;
• baseharbor.provider/v1 as the provider protocol contract;
• a shared semantic boundary for built-in and future external providers;
• gRPC/Protocol Buffers as the future language-neutral external transport;
• JSON Schema 2020-12 for provider operator configuration;
• OCI as the future digest-first provider packaging/distribution path;
• explicit async-operation, idempotency, deadline/cancellation and binding-secret rules;
• open supply-chain direction using OCI referrers plus standard signature/SBOM/provenance mechanisms.

No external plugin loader is introduced yet. Current providers remain built into BaseHarbor and continue using the existing runtime implementation.

Safety

Repository inspection is strictly read-only.

• it does not write baseharbor.yaml;
• it does not materialize BaseHarbor runtime state;
• environment-file values are discarded before inspection/output;
• only variable names are retained;
• symlinked files are skipped so inspection does not follow repository-controlled links outside the tree;
• common generated/vendor directories such as .git, .baseharbor, node_modules, vendor, build output and virtual environments are ignored;
• large candidate files are bounded rather than loaded without limit.

Suggested and Possible capability findings are never silently converted into application requirements. If app init --quick has no Detected capability and no explicit detected workload, it now fails closed and asks the developer to use interactive setup or explicit flags.

Behavior correction

A repository that contains an explicit application workload but no backend-capability evidence no longer receives an invented PostgreSQL requirement from app init --quick.

Compose provider detection is also scoped to service identity/image evidence, avoiding false provider classification merely because an application service contains variables such as DATABASE_URL.

Compatibility & upgrade impact

No baseharbor.yaml migration is required.

Existing repositories and explicit app init flags continue to work.

Compose remains the complete current runtime implementation. PostgreSQL, Valkey and OpenBao provisioning behavior is unchanged.

The new provider protocol is an architecture/API foundation for later external providers; installing or loading external provider modules is intentionally deferred.

Deferred work

v0.4.3 does not yet add:

• AI-assisted repository analysis;
• automatic mutation based on Suggested/Possible evidence;
• external provider loading;
• provider OCI download/execution;
• Kubernetes/OpenShift/cloud runtime providers;
• the later S3/observability/messaging capability implementations.

Those build on the deterministic inspection and provider-contract foundations introduced here.

BaseHarbor v0.4.2

BaseHarbor v0.4.2

BaseHarbor v0.4.2 separates an application's logical resource from the provider instance that happens to serve it.

That distinction lets BaseHarbor reuse infrastructure where sharing is sensible, keep dedicated infrastructure isolated where it matters, and adopt existing external services without pretending BaseHarbor owns them.

The developer workflow stays the same: no Manifest v1 migration is required.

Added

BaseHarbor now understands three provider scopes:

• shared — one BaseHarbor-managed provider can serve multiple applications;
• application-scoped — a provider belongs to one application and cannot cross that ownership boundary;
• external — an existing/BYO provider can satisfy a logical resource while its lifecycle stays outside BaseHarbor.

The provider registry is persisted in protected BaseHarbor state and records logical resource-to-provider-instance bindings plus explicit lifecycle ownership.

Changed

The current stack now maps naturally to the registry:

OpenBao              -> shared
PostgreSQL instances -> application-scoped
Valkey instances     -> application-scoped

A second application can reuse the same compatible shared provider without BaseHarbor accidentally provisioning a duplicate. Dedicated providers remain isolated to their owning application.

Existing v0.4.1 applications are adopted automatically after the next successful baha app apply or baha app up.

Destroying an application removes its bindings and BaseHarbor-owned application-scoped provider records while shared and external provider instances remain.

Security

Provider registry state is written atomically with owner-only permissions and read/modify/write updates are serialized so concurrent BaseHarbor operations cannot silently overwrite each other.

Application-scoped providers fail closed on cross-application binding attempts. Corrupt, duplicate or ambiguous registry state is rejected.

External provider entries use non-secret references only; credentials and secret-bearing connection data remain outside the registry. BaseHarbor never treats an external provider as lifecycle-owned.

Deprecated

No public baha command or Manifest v1 field is deprecated in v0.4.2.

Removed

Nothing from the supported v0.4.1 CLI, Manifest v1 or Compose workflow is removed.

Compatibility & upgrade notes

No baseharbor.yaml migration is required.

Provider placement remains deployment/operator state and is intentionally not added to portable application intent.

v0.4.2 does not yet add a public provider-selection syntax, replace existing Compose provisioning, or implement Kubernetes/OpenShift/cloud providers. Those remain separate milestones so this release stays focused and compatible.

The practical benefit is architectural but concrete: later shared observability, dedicated databases, customer-managed services and cloud providers can be introduced without changing what the application says it needs.

For detailed technical history, see CHANGELOG.md.