Docker Compose

Deploy Stategraph using Docker Compose. This is the fastest way to get started and is suitable for development, evaluation, and small team deployments.

Releases

Stategraph server images are distributed via GitHub Container Registry. Use the latest tag for the most recent stable release, or pin to a specific version from the releases page.

Prerequisites

• Docker Engine 20.10 or later
• Docker Compose v2.0 or later
• Port 8080 available

Quick Start

1. Create a project directory

mkdir stategraph && cd stategraph

2. Create the docker-compose.yml file

services:
  db:
    image: postgres:17-alpine
    user: postgres
    environment:
      POSTGRES_PASSWORD: "stategraph"
      POSTGRES_USER: "stategraph"
      POSTGRES_DB: "stategraph"
    healthcheck:
      test: ["CMD", "pg_isready", "-d", "stategraph", "-U", "stategraph"]
      interval: 3s
      timeout: 3s
      retries: 5
    volumes:
      - db:/var/lib/postgresql/data/
    networks:
      - stategraph

  server:
    image: ghcr.io/stategraph/stategraph-server:latest
    environment:
      # Database configuration
      DB_HOST: "db"
      DB_PORT: "5432"
      DB_USER: "stategraph"
      DB_PASS: "stategraph"
      DB_NAME: "stategraph"

      # Required: Your public URL
      STATEGRAPH_UI_BASE: "http://localhost:8080"
    ports:
      - "8080:8080"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/api/v1/health"]
      interval: 10s
      timeout: 5s
      retries: 5
    depends_on:
      db:
        condition: service_healthy
    networks:
      - stategraph

networks:
  stategraph:

volumes:
  db:

3. Start Stategraph

docker compose up -d

4. Verify the deployment

# Check service health
docker compose ps

# Check the health endpoint
curl http://localhost:8080/api/v1/health

5. Access the UI

Open http://localhost:8080 in your browser.

Authentication

Stategraph supports two authentication modes. Choose based on your use case:

Option A: Local Authentication (Default)

Local authentication is enabled by default and requires no additional configuration. On first access, you'll be guided through creating an admin account.

First-Time Setup:

1. Navigate to http://localhost:8080
2. You'll see the setup wizard prompting you to create an admin account
3. Fill in the required fields:
4. Email: your@email.com (used for login)
5. Password: Minimum 8 characters
6. Name: Your Name

7. Organization: Your Organization

8. Click Create Admin Account

9. You'll be automatically logged in

Creating Additional Users:

Once logged in as admin:

1. Navigate to Settings > Users
2. Click Create User
3. Fill in user details (email, password, name)
4. Toggle Is Admin if the user needs admin privileges
5. Click Create

See the Local Authentication guide for detailed user management instructions.

Option B: OAuth Authentication (Production)

For production deployments, configure OAuth with your identity provider.

Google OAuth:

1. Create OAuth credentials in Google Cloud Console
2. Set Authorized redirect URIs to: http://localhost:8080/oauth2/google/callback (or your production URL)
3. Add these environment variables to your docker-compose.yml:

services:
  server:
    environment:
      # ... existing config ...
      STATEGRAPH_OAUTH_TYPE: "google"
      STATEGRAPH_OAUTH_CLIENT_ID: "your-client-id.apps.googleusercontent.com"
      STATEGRAPH_OAUTH_CLIENT_SECRET: "your-client-secret"
      STATEGRAPH_OAUTH_REDIRECT_BASE: "http://localhost:8080"  # Must match your public URL
      STATEGRAPH_OAUTH_EMAIL_DOMAIN: "yourcompany.com"  # Optional: restrict to domain

Generic OIDC (Okta, Auth0, Azure AD, etc.):

1. Create an application in your OIDC provider
2. Set the callback/redirect URI to: http://localhost:8080/oauth2/oidc/callback (or your production URL)
3. Add these environment variables to your docker-compose.yml:

services:
  server:
    environment:
      # ... existing config ...
      STATEGRAPH_OAUTH_TYPE: "oidc"
      STATEGRAPH_OAUTH_CLIENT_ID: "your-client-id"
      STATEGRAPH_OAUTH_CLIENT_SECRET: "your-client-secret"
      STATEGRAPH_OAUTH_OIDC_ISSUER_URL: "https://your-provider.com"
      STATEGRAPH_OAUTH_REDIRECT_BASE: "http://localhost:8080"  # Must match your public URL
      STATEGRAPH_OAUTH_EMAIL_DOMAIN: "yourcompany.com"  # Optional

After adding OAuth configuration, apply the changes:

docker compose up -d

This recreates the server container with the new configuration.

Users can now log in via OAuth at http://localhost:8080.

See Authentication for detailed OAuth setup instructions.

Configuration

Required Environment Variables

Optional Environment Variables

Using an Environment File

For easier configuration, create a .env file:

# .env
STATEGRAPH_UI_BASE=http://localhost:8080

# OAuth (uncomment for production)
# STATEGRAPH_OAUTH_TYPE=google
# STATEGRAPH_OAUTH_CLIENT_ID=your-client-id
# STATEGRAPH_OAUTH_CLIENT_SECRET=your-client-secret
# STATEGRAPH_OAUTH_EMAIL_DOMAIN=yourcompany.com

# Database (only needed if using external PostgreSQL)
# DB_HOST=your-postgres-host
# DB_PORT=5432
# DB_USER=stategraph
# DB_PASS=your-secure-password
# DB_NAME=stategraph

Update docker-compose.yml to use the env file:

services:
  server:
    image: ghcr.io/stategraph/stategraph-server:latest
    env_file:
      - .env
    environment:
      DB_HOST: "db"
      DB_PORT: "5432"
      DB_USER: "stategraph"
      DB_PASS: "stategraph"
      DB_NAME: "stategraph"
    # ... rest of config

Production Considerations

For production deployments:

Use External PostgreSQL

For data durability and backup capabilities, use a managed PostgreSQL service or dedicated PostgreSQL server:

services:
  server:
    image: ghcr.io/stategraph/stategraph-server:latest
    environment:
      DB_HOST: "your-postgres-host.example.com"
      DB_PORT: "5432"
      DB_USER: "stategraph"
      DB_PASS: "${DB_PASSWORD}"  # Use secrets management
      DB_NAME: "stategraph"
      STATEGRAPH_UI_BASE: "https://stategraph.example.com"

Use HTTPS

Place Stategraph behind a reverse proxy with TLS termination, or use a load balancer that handles HTTPS.

Secure Database Credentials

Use Docker secrets or a secrets manager instead of plain text passwords:

services:
  server:
    environment:
      DB_PASS: "${DB_PASSWORD}"  # Set via environment or secrets

Updating

To update to a newer version:

docker compose pull
docker compose up -d

To pin to a specific version, update the image tag in your docker-compose.yml:

services:
  server:
    image: ghcr.io/stategraph/stategraph-server:1.2.3  # Pin to specific version
    # ... rest of config

Check the releases page for available versions.

Troubleshooting

Container won't start

Check the logs:

docker compose logs server
docker compose logs db

Database connection errors

Ensure the database container is healthy before the server starts:

docker compose ps

The db service should show healthy status.

Port already in use

Either stop the service using port 8080, or change the port mapping:

ports:
  - "8081:8080"  # Map to port 8081 instead

Next Steps

• Configure your first Terraform state
• Set up authentication
• Deploy to Kubernetes