Docker Compose Setup

Deploy DeployStack using Docker Compose for a production-ready, self-hosted installation. This method is recommended for most users as it provides a reliable, scalable setup with minimal configuration.

Overview

This guide provides step-by-step instructions to install and configure DeployStack using Docker Compose. The setup includes both frontend and backend services with persistent data storage and proper networking.

Important: Only modify settings explicitly mentioned in this guide. Altering other configurations may lead to issues.

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 20GB of available disk space for images and persistent data.
• Network: Stable internet connection for pulling Docker images.

Option 1: One-line Setup

Deploy DeployStack with a single command:

curl -sSL https://raw.githubusercontent.com/deploystackio/deploystack/main/scripts/install.sh | bash

This script will:

1. Download the docker-compose.yml file
2. Generate a secure encryption secret
3. Start all services
4. Display access information

Option 2: Manual Setup

Follow these steps for a manual setup with full control.

Step 1: Download Docker Compose File

Download the docker-compose.yml file to your working directory:

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

Step 2: Generate Encryption Secret

DeployStack requires a secure encryption secret for protecting sensitive data like API keys and credentials.

# Using OpenSSL (recommended)
openssl rand -hex 16

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

# Using PowerShell
-join ((1..32) | ForEach {'{0:X}' -f (Get-Random -Max 16)})

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

Step 3: Set Environment Variables

Create a .env file in the same directory as your docker-compose.yml:

# 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

Replace your-generated-secret-here with the secret you generated in Step 2.

Step 4: Launch DeployStack

Start the Docker containers:

docker-compose up -d

This command will:

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

Step 5: Verify Installation

Check that all services are running:

docker-compose ps

You should see both deploystack-frontend and deploystack-backend containers in "Up" status.

Step 6: Access DeployStack

Open your browser and navigate to:

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

Configuration

External Access

By default, DeployStack runs on localhost. To access it via an external domain or IP address, you need to configure the environment variables.

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

For HTTPS setup, we recommend using a reverse proxy like Nginx or Traefik:

# 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 uses Docker volumes to persist data:

• deploystack_backend_persistent: Application database, configuration, and user uploads

Backup Your Data

Regularly backup your persistent data:

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

# Backup 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 .

Environment Variables Reference

Required Variables

Optional Variables

Troubleshooting

Common Issues

Services Won't Start

# Check logs
docker-compose logs

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

Port Conflicts

If ports 3000 or 8080 are already in use:

# Update .env file
FRONTEND_PORT=8081
BACKEND_PORT=3001

# Restart services
docker-compose down
docker-compose up -d

Permission Issues

# Fix volume permissions
sudo chown -R $USER:$USER $(docker volume inspect deploystack_backend_persistent --format '{{ .Mountpoint }}')

Memory Issues

# Check available memory
free -h

# Monitor container resource usage
docker stats

Getting Help

If you encounter issues not covered here:

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

Next Steps

Once DeployStack is running:

1. Create your first workspace through the web interface
2. Configure global settings for email and authentication
3. Set up user roles and team permissions
4. Deploy your first MCP server from the catalog

Need to upgrade? Check our Upgrade Guide for step-by-step instructions.