Installation Guide

Get Cascade Platform running locally in 3-5 minutes using Docker Compose.

Prerequisites

Before you begin, make sure you have:

Optional (for development):

• Go 1.23+ (if building from source)
• Make (for convenience commands)

Docker Compose Installation

Step 1: Clone the Repository

git clone https://github.com/cascade-platform/cascade.git
cd cascade

Step 2: Start the Platform

Start all infrastructure services with a single command:

make setup

This command:

1. Starts all Docker containers
2. Waits for services to be healthy
3. Displays service URLs and next steps
4. Takes ~3-5 minutes (first run downloads Docker images)

Step 3: Verify Installation

Check that all services are running and healthy:

make health

Expected output:

✓ PostgreSQL       (port 5432)
✓ Redis            (port 6379)
✓ Temporal         (port 7233)
✓ NATS             (port 4222)
✓ Ory Kratos       (port 4433)
✓ SpiceDB          (port 8443)
✓ Grafana          (port 3000)

All services should show ✓ (green checkmarks).

What Gets Installed

Core Services

What Each Does

PostgreSQL - Stores all application data (workflows, instances, state)

Redis - Powers caching (UI rendering), context storage for agents, vector embeddings

Temporal - Executes workflows with durability and replay guarantees

NATS - Enables event-driven workflows (webhook triggers, external signals)

Ory - Handles user authentication (OAuth2, sessions, MFA)

SpiceDB - Manages fine-grained access control (who can do what)

Grafana - Visualizes system health (via Prometheus, Loki, Jaeger)

Next Step

All set! Your platform is ready. Continue to the next guide:

→ 5-Minute Quickstart

Troubleshooting

”Docker is not running”

Error: Cannot connect to the Docker daemon

Solution:

# Start Docker (macOS/Windows)
open -a Docker
 
# Start Docker (Linux)
sudo systemctl start docker

“Port already in use”

Error: Error response from daemon: bind: address already in use

Solution: Change the port in docker-compose.yml:

services:
  postgres:
    ports:
      - "5433:5432"  # Changed from 5432 to 5433

“Services won’t start”

Error: service did not converge or containers keep restarting

Solution: Check logs:

# View all logs
docker-compose logs -f
 
# View specific service logs
docker-compose logs -f postgres
docker-compose logs -f temporal

“Insufficient resources”

Error: Cannot allocate memory or Docker crashes

Solution: Increase Docker memory allocation:

• Docker Desktop (macOS/Windows): Settings → Resources → Memory (increase to 6-8GB)
• Linux: Edit /etc/docker/daemon.json and restart Docker

”Health check fails”

Error: make health shows ✗ for some services

Solution: Wait longer (services take time to start):

# Wait 30 seconds and try again
sleep 30
make health

Or check service logs:

docker-compose logs redis

“Cannot connect to services”

Error: Applications can’t reach PostgreSQL, Redis, etc.

Solution: Services are available at:

• PostgreSQL: localhost:5432
• Redis: localhost:6379
• Temporal: localhost:7233
• NATS: localhost:4222

Stopping and Restarting

Stop All Services

docker-compose down

Restart Services

docker-compose up -d

Reset Everything (clean slate)

# Stop and remove all containers, volumes, networks
docker-compose down -v
 
# Start fresh
make setup

Kubernetes Installation (Advanced)

For production or Kubernetes deployments:

→ See Kubernetes Deployment Guide (coming in Phase 5)

Next Steps

Your platform is ready! Continue with:

1. 5-Minute Quickstart - Deploy your first app
2. First Workflow - Build a real workflow
3. Core Concepts - Understand the platform

Need help? Check Troubleshooting or ask in our community.