Docker Compose Setup

​

Overview

​

System Requirements

• RAM: Ensure your environment has at least 4GB of RAM. Insufficient memory can cause processes to crash.
• Docker & Docker Compose: Make sure both are installed and up-to-date.
• Storage: At least 2GB of available disk space for images and persistent data.

​

Beggining the setup for Docker Compose

​

Step 1: Download Docker Compose File

curl -o docker-compose.yml https://raw.githubusercontent.com/deploystackio/deploystack/main/docker-compose.yml

​

Step 2: Generate Encryption Secret

# Using OpenSSL (recommended)
openssl rand -hex 16

# Alternative using Node.js
node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"

​

Step 3: Set Environment Variables

# Create .env file
cat > .env << EOF
# DeployStack Configuration
DEPLOYSTACK_ENCRYPTION_SECRET=your-generated-secret-here

# Optional: Customize ports (default: frontend=8080, backend=3000)
# FRONTEND_PORT=8080
# BACKEND_PORT=3000

# Optional: Custom app title
# VITE_APP_TITLE=My DeployStack Instance
EOF

​

Step 4: Launch DeployStack

docker-compose up -d

• Pull the latest DeployStack images (frontend and backend)
• Create necessary volumes for persistent data
• Start frontend and backend services
• Set up networking between services

​

Step 5: Verify Installation

docker-compose ps

​

Step 6: Access DeployStack

• Frontend: http://localhost:8080
• Backend API: http://localhost:3000

​

Step 7: Deploy Satellite Service (Required)

1. Complete Setup Wizard First:
   • Access http://localhost:8080/setup
   • Create your admin account
   • Complete basic platform configuration
2. Generate Registration Token:
   • Log in to DeployStack as admin
   • Navigate to Admin → Satellites → Pairing
   • Click “Generate Token” and copy the full token
   • Token format: deploystack_satellite_global_eyJhbGc...
3. Deploy Satellite with Docker: For local development (connecting from same machine):
   Copy

   docker run -d \
     --name deploystack-satellite \
     --network deploystack-network \
     -p 3001:3001 \
     -e DEPLOYSTACK_BACKEND_URL="http://deploystack-backend:3000" \
     -e DEPLOYSTACK_SATELLITE_NAME="docker-satellite-001" \
     -e DEPLOYSTACK_REGISTRATION_TOKEN="your-token-here" \
     -v deploystack_satellite_persistent:/app/persistent_data \
     deploystack/satellite:latest
   

   For remote access (connecting from MCP clients via domain/IP):
   Copy

   docker run -d \
     --name deploystack-satellite \
     --network deploystack-network \
     -p 3001:3001 \
     -e DEPLOYSTACK_BACKEND_URL="http://deploystack-backend:3000" \
     -e DEPLOYSTACK_SATELLITE_URL="https://satellite.example.com" \
     -e DEPLOYSTACK_SATELLITE_NAME="docker-satellite-001" \
     -e DEPLOYSTACK_REGISTRATION_TOKEN="your-token-here" \
     -v deploystack_satellite_persistent:/app/persistent_data \
     deploystack/satellite:latest
   

   When to set DEPLOYSTACK_SATELLITE_URL:

   • Required when MCP clients (Claude Code, VS Code, etc.) connect via a domain or IP address
   • Not needed for local development on localhost
   • Use base URL only (e.g., https://satellite.example.com) - no /mcp or /sse paths
   • Required for OAuth authentication to work with remote MCP clients
4. Verify Satellite Registration:
   Copy

   docker logs deploystack-satellite
   # Should show: ✅ Satellite registered successfully: docker-satellite-001
   

​

Configuration

​

External Access

​

Understanding URLs

• Protocol: Use http or https depending on your setup
• Domain/IP: The domain name or IP address where your application is accessible
• Port: Include the port number if not using standard ports (80 for http, 443 for https)

​

Configuring for External Access

1. Update your .env file:

# For direct access without reverse proxy
DEPLOYSTACK_FRONTEND_URL=http://your-domain-or-ip:8080
VITE_DEPLOYSTACK_BACKEND_URL=http://your-domain-or-ip:3000

# For access via reverse proxy with SSL
DEPLOYSTACK_FRONTEND_URL=https://your-domain
VITE_DEPLOYSTACK_BACKEND_URL=https://your-domain/api

2. Restart the services:

docker-compose down
docker-compose up -d

​

SSL/HTTPS Setup

# Example Nginx configuration
server {
    listen 443 ssl;
    server_name your-domain.com;
    
    # SSL configuration
    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;
    
    # Frontend
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    
    # Backend API
    location /api/ {
        proxy_pass http://localhost:3000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

​

Data Persistence

• deploystack_backend_persistent: Application database, configuration, and user uploads
• deploystack_satellite_persistent: Satellite credentials and process data (created when satellite is deployed separately)

​

Backup Your Data

# Create backup directory
mkdir -p backups/$(date +%Y%m%d)

# Backup backend volume
docker run --rm -v deploystack_backend_persistent:/data -v $(pwd)/backups/$(date +%Y%m%d):/backup alpine tar czf /backup/backend_persistent.tar.gz -C /data .

# Backup satellite volume (if satellite is deployed)
docker run --rm -v deploystack_satellite_persistent:/data -v $(pwd)/backups/$(date +%Y%m%d):/backup alpine tar czf /backup/satellite_persistent.tar.gz -C /data .

​

Environment Variables Reference

​

Required Variables

​

Optional Variables

​

Satellite Variables

​

Troubleshooting

​

Common Issues

​

Services Won’t Start

# Check logs
docker-compose logs

# Check specific service
docker-compose logs backend
docker-compose logs frontend

​

Getting Help

1. Search existing GitHub Issues
2. Join our Discord community
3. Create a new issue with detailed logs and system information