Docker Compose Setup - StellarStack

Deploy StellarStack using Docker Compose for a containerized, production-ready setup.

Prerequisites

Docker 20.10+ (installation guide)
Docker Compose v2.0+ (included with Docker Desktop)
Domain name with DNS configured (for production)
SSL certificate (via Certbot or existing cert)

Quick Start

1. Clone Repository

git clone https://github.com/StellarStackOSS/StellarStack.git
cd StellarStack

2. Configure Environment

Copy the example environment file:

cp .env.example .env

Edit .env with your configuration. See Environment Variables for all options. Minimum required variables:

DATABASE_URL=postgresql://stellar:stellarpass@postgres:5432/stellar
BETTER_AUTH_SECRET=your-32-character-secret-here
FRONTEND_URL=https://panel.example.com
API_URL=https://api.example.com

3. Start Services

docker-compose up -d

This starts:

PostgreSQL database
Redis (for caching and sessions)
StellarStack API
StellarStack web panel

4. Verify Deployment

Check container status:

docker-compose ps

View logs:

docker-compose logs -f

5. Create Admin User

Run the database seeder:

docker exec stellarstack-api pnpm db:seed

Docker Compose Configuration

The default docker-compose.yml includes:

PostgreSQL Service

postgres:
  image: postgres:16-alpine
  container_name: stellarstack-postgres
  restart: unless-stopped
  environment:
    POSTGRES_USER: stellar
    POSTGRES_PASSWORD: stellarpass
    POSTGRES_DB: stellar
  ports:
    - "5432:5432"
  volumes:
    - postgres_data:/var/lib/postgresql/data
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U stellar -d stellar"]
    interval: 10s
    timeout: 5s
    retries: 5

Redis Service

redis:
  image: redis:7-alpine
  container_name: stellarstack-redis
  restart: unless-stopped
  ports:
    - "6379:6379"
  volumes:
    - redis_data:/data
  command: redis-server --appendonly yes
  healthcheck:
    test: ["CMD", "redis-cli", "ping"]
    interval: 10s
    timeout: 5s
    retries: 5

Persistent Volumes

Data is stored in Docker volumes:

volumes:
  postgres_data:  # PostgreSQL database
  redis_data:     # Redis cache

Network Configuration

StellarStack creates two Docker networks:

1. stellar_network

For Docker Compose services (Panel, API, Database):

docker network create stellar_network

2. stellar

For game server containers (daemon-managed):

docker network create stellar --subnet=172.18.0.0/16 --gateway=172.18.0.1

These networks are automatically created by the installer script or must be created manually.

Reverse Proxy Setup

StellarStack requires an nginx reverse proxy for:

SSL termination
Domain routing
WebSocket support

nginx Configuration Example

Panel configuration (/etc/nginx/sites-available/stellarstack-panel):

server {
    listen 80;
    server_name panel.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name panel.example.com;

    ssl_certificate /etc/letsencrypt/live/panel.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/panel.example.com/privkey.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

API configuration (/etc/nginx/sites-available/stellarstack-api):

server {
    listen 80;
    server_name api.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name api.example.com;

    ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;

    client_max_body_size 100M;

    location / {
        proxy_pass http://localhost:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable configurations:

sudo ln -s /etc/nginx/sites-available/stellarstack-panel /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/stellarstack-api /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

SSL Certificate Setup

Using Certbot (Let’s Encrypt)

# Install Certbot
sudo apt install certbot python3-certbot-nginx

# Generate certificates
sudo certbot --nginx -d panel.example.com
sudo certbot --nginx -d api.example.com

Using Existing Certificates

Update nginx configuration to point to your certificate files:

ssl_certificate /path/to/fullchain.pem;
ssl_certificate_key /path/to/privkey.pem;

Database Migrations

Run database migrations after deployment:

cd apps/api
pnpm db:push
pnpm db:generate

Or via Docker:

docker exec stellarstack-api pnpm db:push
docker exec stellarstack-api pnpm db:generate

Monitoring Stack (Optional)

The installer can deploy a monitoring stack with:

Prometheus - Metrics collection
Loki - Log aggregation
Grafana - Visualization dashboards

To enable monitoring, set during installation or add to docker-compose.yml.

Updating StellarStack

Pull Latest Images

docker-compose pull
docker-compose up -d

Rebuild from Source

git pull origin master
docker-compose build
docker-compose up -d

Run Migrations

docker exec stellarstack-api pnpm db:push

Troubleshooting

Container Won’t Start

Check logs:

docker-compose logs <service-name>

Database Connection Errors

Verify DATABASE_URL in .env matches PostgreSQL configuration.

Port Conflicts

Check if ports are already in use:

sudo netstat -tlnp | grep -E '(3000|3001|5432|6379)'

Overview

Getting Started

Core Features

User Management

Automation

Advanced

Deployment

​Prerequisites

​Quick Start

​1. Clone Repository

​2. Configure Environment

​3. Start Services

​4. Verify Deployment

​5. Create Admin User

​Docker Compose Configuration

​PostgreSQL Service

​Redis Service

​Persistent Volumes

​Network Configuration

​1. stellar_network

​2. stellar

​Reverse Proxy Setup

​nginx Configuration Example

​SSL Certificate Setup

​Using Certbot (Let’s Encrypt)

​Using Existing Certificates

​Database Migrations

​Monitoring Stack (Optional)

​Updating StellarStack

​Pull Latest Images

​Rebuild from Source

​Run Migrations

​Troubleshooting

​Container Won’t Start

​Database Connection Errors

​Port Conflicts

​Next Steps

Environment Variables

Production Checklist

Build docs developers (and LLMs) love