Deployment
How Cockpit v2 ships and runs — a single self-contained deployment, containers, migrations, health probes, high availability and observability.
Single deployable unit
Cockpit v2 deploys as one self-contained artifact. A single service process serves the REST API, the KMIP listener and the background jobs together. It ships as a minimal, non-root container image containing only the application and its runtime data.
REST API
The full management and cryptographic API surface consumed by the UI, the PKCS#11 provider and external clients.
KMIP listener
The KMIP endpoint runs in-process alongside the REST API — no separate service to deploy or scale.
Background jobs
Scheduled and deferred work (outbox delivery, maintenance tasks) run inside the same binary.
Containers
A Docker Compose stack is provided for local and development use; production runs on Kubernetes.
| Environment | Shape |
|---|---|
| Local / development | A Docker Compose stack: API + UI + HTTPS ingress + PostgreSQL + Redis. |
| Production | Kubernetes, running the same minimal, non-root image. |
Migrations
Schema changes are applied automatically at boot. Cockpit v2 uses a consolidated, idempotent init script together with numbered incremental migrations. Applied migrations are tracked in the database, so each version is applied exactly once and startup is safe to repeat.
Migrations run when the service starts. The init script is idempotent, and the incremental migrations are tracked in the database — bringing up a fresh node or rolling a new version forward requires no separate migration step.
High availability and resilience
Cockpit v2 is designed to run as stateless API nodes behind an L7/TLS load balancer. All authentication state lives in the JWT, so any node can serve any request and nodes can be added or removed freely.
Stateless API nodes
All auth state is carried in the JWT; nodes sit behind an L7/TLS load balancer and scale horizontally.
Connection pooling
Database connection pooling keeps database access bounded and efficient under load.
Retry with jitter
Transient failures are retried with jittered backoff to avoid synchronized retry storms.
Graceful shutdown
In-flight requests are allowed to drain cleanly when a node is stopped or rolled.
Exactly-once effects
A transactional event outbox plus idempotency keys keep side effects consistent across retries.
Cache fallback
Reads fall back from Redis to the database, so a cache outage degrades rather than fails.
Data-tier HA
A PostgreSQL primary with replicas and Redis HA are recommended for production.
For production, run a PostgreSQL primary with replicas and a highly available Redis deployment. The API tier stays stateless, so resilience is concentrated in the data tier and the load balancer.
Health probes
Cockpit v2 exposes dedicated endpoints for Kubernetes to drive liveness, readiness and overall health checks:
| Probe | Endpoint | Purpose |
|---|---|---|
| Liveness | /live | Signals that the process is alive; a failure triggers a restart. |
| Readiness | /ready | Signals that the node is ready to receive traffic; a failure removes it from the load balancer. |
| Health | /health | Overall health check (cache connectivity); returns a non-200 status if the cache is unreachable. |
Observability
Cockpit v2 emits structured JSON logs, carrying request, tenant and user context on every entry. Metrics and alerting integrate with standard operational tooling.
Structured logs
Structured JSON logs, enriched with request / tenant / user context.
Metrics
A Prometheus metrics endpoint for scraping runtime and request metrics.
SIEM forwarding
Log forwarding to Splunk, syslog or Elastic; other SIEM integration types can be configured but are not yet actively forwarded.
Alerting
Webhook and email alerting for operational and security events.
Configuration
Cockpit v2 is configured entirely through environment variables. This keeps configuration explicit, container-native and easy to manage through Kubernetes secrets and config maps.
# Cockpit v2 reads all configuration from the environment.
DATABASE_URL=postgres://...
REDIS_URL=redis://...
# See the full reference for the complete set of variables.For the complete environment-variable reference and a production .env example, see the Cockpit v2 configuration reference.
Any throughput, latency or footprint numbers quoted for Cockpit v2 are indicative targets, not benchmarked guarantees. Validate them against your own environment before relying on them for capacity planning.