Skip to main content

Docker Quickstart

Run Infracast locally using Docker Compose. Suitable for evaluation, development, and air-gapped environments.

Verified 2026-09-14

Every command on this page was checked against the shipped docker-compose.yml, Dockerfile, and CLI. If a command here fails, it is a bug — please report it.

Prerequisites​

  • Docker 20.10+ and Docker Compose v2
  • 4 GB RAM minimum (8 GB recommended)
  • 10 GB disk space

Step 1: Get the Distribution​

git clone <distribution-url>   # provided with your license entitlement
cd infracast

Step 2: Start the Stack​

docker compose up -d

This starts two services:

  • infracast — the API server on port 8080
  • postgres — PostgreSQL 16 on port 5432

Database migrations run automatically at startup, so there is no separate migrate step.

Change the default credentials

The bundled docker-compose.yml ships evaluation defaults — including INFRACAST_JWT_SECRET=change-me-in-production and a postgres password of infracast. Override both before exposing this to anything but localhost. See Production Considerations.

Step 3: Verify Installation​

# Check both services are running
docker compose ps

# Check API health
curl http://localhost:8080/healthz

Step 4: Create the Admin User​

The API has no default login. Create the first user with the user create command:

docker compose exec infracast ./infracast user create \
  --username admin \
  --password 'YourSecurePassword123!' \
  --role system-admin

Available roles: system-admin, tenant-admin, security-analyst, auditor, read-only.

Confirm it works by requesting a token:

curl -s -X POST http://localhost:8080/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"YourSecurePassword123!"}'

Step 5: Seed Demo Data (Optional)​

For evaluation, seed sample infrastructure:

# Get an auth token
TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"YourSecurePassword123!"}' | jq -r '.token')

# Seed demo data
docker compose exec infracast ./infracast demo seed \
  --api-url http://localhost:8080 \
  --token "$TOKEN" \
  --tenant demo \
  --profile standard

Two profiles are available:

  • standard — roughly 200 nodes across AWS, on-prem, and Active Directory
  • enterprise — 1,000+ nodes across AWS, Azure, GCP, VMware, and on-prem

Add --reset to clear existing demo data before seeding.

Step 6: Log In​

The API serves on http://localhost:8080. The web dashboard is distributed separately from this compose stack — see your license entitlement for the UI distribution, or use the API directly:

curl -s http://localhost:8080/api/v1/tenants \
  -H "Authorization: Bearer $TOKEN"

Useful CLI Commands​

The container entrypoint is the infracast binary, so any CLI subcommand can be run through docker compose exec:

docker compose exec infracast ./infracast version
docker compose exec infracast ./infracast discover --help
docker compose exec infracast ./infracast audit --framework nist-800-53
docker compose exec infracast ./infracast license info

Run ./infracast <command> --help for full options on any command.

Configuration​

The API server is configured with INFRACAST_* environment variables. The most common:

VariablePurpose
INFRACAST_DB_URLPostgreSQL connection string
INFRACAST_JWT_SECRETSigning secret for auth tokens
INFRACAST_ADDRListen address (default :8080)
INFRACAST_LOG_LEVELdebug, info, warn, error
INFRACAST_CREDENTIAL_MASTER_KEYMaster key for the encrypted credential vault
INFRACAST_LICENSE_KEYLicense key for paid tiers

Production Considerations​

Not for Production

This quickstart uses evaluation defaults and single-node PostgreSQL. For production:

  • Use managed PostgreSQL (RDS, Cloud SQL)
  • Replace every default secret, especially INFRACAST_JWT_SECRET and the database password
  • Set INFRACAST_CREDENTIAL_MASTER_KEY to a strong generated value
  • Configure TLS termination (nginx, ALB)
  • Use proper secrets management
  • Set up monitoring and alerting
  • See Terraform Deployment for production setup

Upgrading​

# Pull the latest image
docker compose pull

# Restart with the new image
docker compose up -d

Migrations run automatically on startup, so no separate migration step is required.

Troubleshooting​

Database connection errors​

# Check postgres is running
docker compose logs postgres

# Verify connection
docker compose exec postgres psql -U infracast -c "SELECT 1"

API won't start​

# Check logs
docker compose logs infracast

Common causes:

  • INFRACAST_DB_URL misconfigured or postgres not yet healthy
  • Port 8080 already in use
  • Missing required environment variables

Authentication failures​

  • Confirm the user exists — re-run ./infracast user create
  • Reset a password with ./infracast user reset-password
  • Confirm INFRACAST_JWT_SECRET did not change between issuing and using a token; changing it invalidates all existing tokens