Git Setup Docs

This method clones the official WoWSQL repository which includes the full docker-compose.yml, Kong configuration, database init scripts, and environment template. Best when you want version-controlled infrastructure that you can customize and update via git pull.

Prerequisites

Git installed on your system
Docker Engine 20.10 or later
Docker Compose v2.0 or later (included with Docker Desktop)
At least 2 GB RAM available for containers
Ports 8080, 5432, and 3000 available on the host

Quick Start

Clone the repository

git clone https://github.com/WoWSQL/wowsql.git
cd wowsql/docker

This gives you the complete stack configuration including Kong routing, database initialization scripts, and the compose file.

Create environment file

Copy the example and set your own secrets:

cp .env.example .env

Open .env and change these two values:

# Set a strong password for PostgreSQL
POSTGRES_PASSWORD=your-strong-password-here

# Set a random string of at least 32 characters
# All API keys are derived from this secret
JWT_SECRET=your-jwt-secret-at-least-32-characters-long

Important: The JWT_SECRET is used to generate your API keys (anon and service_role). Keep it private. If you change it, all existing API keys will be invalidated.

Start the stack

docker compose up -d

This pulls all required images and starts the services. First run takes 1-2 minutes while images download.

Verify services are running

docker compose ps

All services should show running or healthy status within 30 seconds.

Open the dashboard

Visit http://localhost:3000 in your browser. On first launch, you will be prompted to create an admin account (email and password). This is your dashboard login.

Start building

After login, the dashboard provides:

Table Editor to create and manage database tables
SQL Editor for direct query execution
Auth management for user authentication
API keys and connection strings in Settings

What's in the Repository

The cloned repository includes these key files:

Path	Purpose
`docker/docker-compose.yml`	Full service orchestration (9 containers)
`docker/.env.example`	Template for environment variables
`docker/kong/kong.yml`	API gateway routing and plugin configuration
`docker/volumes/db/01-init-roles.sql`	Database roles (anon, authenticated, service_role)
`docker/volumes/db/02-init-schemas.sql`	Core schemas (auth, storage, realtime)
`docker/volumes/db/03-init-rls.sql`	Default Row Level Security policies

Updating to Latest Version

Since you have the Git repository, updating is straightforward:

# Pull latest configuration changes
git pull origin main

# Pull latest Docker images
docker compose pull

# Restart with new images
docker compose up -d

Tip: Check the CHANGELOG before updating to review breaking changes.

Customizing the Stack

Modify Kong routing

Edit docker/kong/kong.yml to add custom routes, rate limiting, or additional plugins:

# After editing kong.yml, restart Kong:
docker compose restart kong

Add custom database init scripts

Place additional .sql files in docker/volumes/db/. They execute in alphabetical order on first startup:

# Example: docker/volumes/db/04-custom-tables.sql
CREATE TABLE IF NOT EXISTS public.my_table (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  name text NOT NULL,
  created_at timestamptz DEFAULT now()
);

ALTER TABLE public.my_table ENABLE ROW LEVEL SECURITY;

Override compose settings

Create a docker-compose.override.yml for local changes without modifying the tracked file:

# docker/docker-compose.override.yml
services:
  db:
    ports:
      - "5433:5432"  # Use different host port
    environment:
      POSTGRES_SHARED_BUFFERS: "512MB"

Management Commands

Stop all services

docker compose down

Stop and remove all data

docker compose down -v

Caution: The -v flag removes all database data, storage files, and Redis data permanently.

View logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f db
docker compose logs -f backend

Restart a single service

docker compose restart backend

Reset everything (fresh start)

# Run the included reset script
bash reset.sh

Troubleshooting

Services not starting

Check the health status of all containers:

docker compose ps

If a service shows unhealthy, inspect its logs:

docker compose logs [service-name]

Database connection refused

The database takes a few seconds to initialize on first startup. Wait for the health check to pass:

docker compose logs db | grep "ready to accept connections"

Cannot access dashboard

Verify the studio container is running and check for port conflicts:

docker compose ps studio
netstat -tlnp | grep 3000

Git pull conflicts

If you've modified tracked files, stash your changes before pulling:

git stash
git pull origin main
git stash pop

Next: Connect your app using the SDK guide, or explore the architecture overview.

PreviousDocker Setup Docs