Preflight and Postflight Checks

Control Zero Self-Managed includes automated health checks that run before installation (preflight) and after installation or upgrade (postflight). These checks verify that the environment meets requirements and that all services are operating correctly.

Preflight Checks

Preflight checks run before installation to verify the host environment is ready.

Running preflight checks

czctl preflight

Check Reference

Check	What It Verifies	Failure Meaning
docker-version	Docker 24.0 or later is installed	Docker is missing or outdated. Install or upgrade Docker before proceeding.
compose-version	Docker Compose 2.20 or later is installed	Docker Compose is missing or outdated. Install the Compose plugin.
disk-space	At least 10 GB available on the Docker data partition	Insufficient disk space. Free space or expand the volume.
memory	At least 4 GB RAM available	Insufficient memory. Add RAM or reduce other workloads.
cpu-cores	At least 2 CPU cores available	Insufficient CPU. The compiled policy engine requires 2 cores minimum for acceptable latency.
port-availability	Default ports (443, 8443, 8080, 9000) are not in use	Port conflict. Stop the conflicting service or configure alternate ports.
file-permissions	The installation directory is writable	Permission issue. Run the installer as a user with write access to the target directory.
clock-sync	System clock is within 5 minutes of UTC	Clock skew can cause license validation failures and audit log timestamp issues. Configure NTP.

Output format

[preflight] Checking Docker version... [pass] Docker 26.1.3
[preflight] Checking Compose version... [pass] Docker Compose 2.27.0
[preflight] Checking disk space... [pass] 48 GB available
[preflight] Checking memory... [pass] 16 GB available
[preflight] Checking CPU cores... [pass] 4 cores
[preflight] Checking port 443... [pass] Available
[preflight] Checking port 8443... [pass] Available
[preflight] Checking port 8080... [pass] Available
[preflight] Checking port 9000... [pass] Available
[preflight] Checking file permissions... [pass] /opt/controlzero is writable
[preflight] Checking clock sync... [pass] Clock offset: +0.3s

[preflight] Result: ALL CHECKS PASSED (10/10)

Postflight Checks

Postflight checks run after installation or upgrade to verify all services are healthy.

Running postflight checks

czctl postflight

Check Reference

Check	What It Verifies	Failure Meaning
gateway-health	Gateway service responds to health endpoint	The gateway container may not have started. Check logs with docker compose logs gateway.
api-health	Management API responds to health endpoint	The API container may not have started. Check logs with docker compose logs api.
policy-engine	Policy engine evaluates a test policy within latency threshold	The policy engine is not responding. May indicate a configuration or resource issue.
audit-db-write	A test record can be written to and read from the audit database	Database is not accepting writes. Check disk space and container status.
dashboard-access	Dashboard is reachable on the configured port	The dashboard container or reverse proxy may not be running.
license-valid	The installed license key passes validation	License key is invalid, expired, or missing. See Licensing.
health-endpoints	All service health endpoints return HTTP 200	One or more services are degraded. Check individual service logs.
tls-cert	TLS certificates are valid and not expiring within 30 days	Certificate is invalid or expiring soon. Renew or regenerate certificates.
scout-connectivity	Scout agent (if configured) can reach the API	Network path between Scout and API is blocked. Check firewall rules.

Output format

[postflight] Checking gateway health... [pass] Responding on port 8443
[postflight] Checking API health... [pass] Responding on port 8080
[postflight] Checking policy engine... [pass] Evaluation latency: 1.2ms
[postflight] Checking audit database... [pass] Write/read successful
[postflight] Checking dashboard access... [pass] Accessible on port 443
[postflight] Checking license... [pass] Valid until 2027-04-01
[postflight] Checking health endpoints... [pass] All endpoints returning 200
[postflight] Checking TLS certificate... [pass] Expires in 342 days
[postflight] Checking Scout connectivity... [skip] Scout not configured

[postflight] Result: ALL CHECKS PASSED (8/8, 1 skipped)

Running Checks Manually

Individual checks

Run a single check by name:

czctl preflight --check disk-space
czctl postflight --check gateway-health

Verbose output

For detailed diagnostic information on each check:

czctl postflight --verbose

JSON output

For integration with monitoring systems:

czctl postflight --format json

{
  "timestamp": "2026-04-03T10:00:00Z",
  "checks": [
    { "name": "gateway-health", "status": "pass", "detail": "Responding on port 8443" },
    { "name": "api-health", "status": "pass", "detail": "Responding on port 8080" }
  ],
  "summary": { "total": 8, "pass": 8, "fail": 0, "skip": 1 }
}

Common Failures and Fixes

Check	Common Cause	Fix
disk-space	Docker images and audit logs consuming space	Run docker system prune --volumes and configure log rotation
port-availability	Another service on the same port	Stop the conflicting service or change Control Zero ports in docker-compose.yml
clock-sync	No NTP configured in isolated environment	Set up NTP against an internal time source
gateway-health	Configuration error in gateway.yml	Check docker compose logs gateway for the specific error
audit-db-write	Database volume full	Expand the volume or purge old audit data per your retention policy
license-valid	Expired license key	Apply a new key with czctl update-license per Licensing
tls-cert	Self-signed cert expired	Regenerate with czctl generate-ca --domain <domain> --output config/certs/ and redeploy