Skip to main content

Docker Quickstart

Run Infracast locally using Docker Compose. Perfect for evaluation, development, or air-gapped environments.

Prerequisites​

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

Step 1: Clone and Configure​

# Clone the repository
git clone https://github.com/azgardtek/vulcan.git
cd vulcan

# Copy the example environment file
cp .env.example .env

Edit .env with your configuration:

.env
# Database
POSTGRES_USER=vulcan
POSTGRES_PASSWORD=change-me-in-production
POSTGRES_DB=vulcan

# API Configuration
API_SECRET_KEY=generate-a-32-byte-random-string
JWT_SECRET=another-32-byte-random-string

# License (optional - Free tier works without)
LICENSE_PUBLIC_KEY=

# Admin bootstrap
ADMIN_USERNAME=admin
ADMIN_PASSWORD=change-me-immediately

Step 2: Start the Stack​

docker compose up -d

This starts:

  • vulcan-api — Go API server on port 8080
  • vulcan-ui — React dashboard on port 3000
  • postgres — PostgreSQL 15 database

Step 3: Verify Installation​

# Check services are running
docker compose ps

# Check API health
curl http://localhost:8080/healthz
# Expected: {"status":"ok","db_connected":true}

# Check UI
open http://localhost:3000

Step 4: Bootstrap Admin User​

On first run, create the admin user:

docker compose exec vulcan-api ./vulcan bootstrap \
  --username admin \
  --password 'YourSecurePassword123!'

Step 5: Seed Demo Data (Optional)​

For evaluation, seed sample infrastructure data:

# 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 vulcan-api ./vulcan demo seed \
  --api-url http://localhost:8080 \
  --token "$TOKEN" \
  --tenant demo

This creates:

  • 167 sample nodes (AWS, on-prem, AD)
  • 189 relationship edges
  • 22 compliance findings

Step 6: Log In​

  1. Open http://localhost:3000
  2. Log in with admin / YourSecurePassword123!
  3. Select the demo tenant (if seeded) or create a new one

Docker Compose Services​

docker-compose.yml (excerpt)
services:
  vulcan-api:
    image: ghcr.io/azgardtek/vulcan:latest
    ports:
      - "8080:8080"
    environment:
      - DATABASE_URL=postgres://vulcan:${POSTGRES_PASSWORD}@postgres:5432/vulcan?sslmode=disable
    depends_on:
      - postgres

  vulcan-ui:
    image: ghcr.io/azgardtek/vulcan-ui:latest
    ports:
      - "3000:80"
    environment:
      - VITE_API_URL=http://localhost:8080

  postgres:
    image: postgres:15-alpine
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=vulcan
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=vulcan

volumes:
  pgdata:

Production Considerations​

Not for Production

This quickstart uses default credentials and single-node PostgreSQL. For production:

  • Use managed PostgreSQL (RDS, Cloud SQL)
  • Configure TLS termination (nginx, ALB)
  • Use proper secrets management
  • Set up monitoring and alerting
  • See Terraform Deployment for production setup

Upgrading​

# Pull latest images
docker compose pull

# Restart with new images
docker compose up -d

# Run database migrations (automatic in most versions)
docker compose exec vulcan-api ./vulcan migrate

Troubleshooting​

Database connection errors​

# Check postgres is running
docker compose logs postgres

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

API won't start​

# Check logs
docker compose logs vulcan-api

# Common issues:
# - DATABASE_URL misconfigured
# - Port 8080 already in use
# - Missing required env vars

UI shows "Network Error"​

  • Ensure API is running: curl http://localhost:8080/healthz
  • Check VITE_API_URL matches your API address
  • If using different ports, update CORS settings