Quick Start

Get DeployStack up and running in minutes. This guide covers deploying the core platform (frontend + backend) and the required satellite service for MCP server management.

Prerequisites

• Docker: Install Docker
• Docker Compose: Install Docker Compose
• System Requirements: 4GB RAM, 20GB disk space

Method 1: Docker Compose (Recommended)

The fastest way to get DeployStack running with proper networking and persistence.

curl -o docker-compose.yml https://raw.githubusercontent.com/deploystackio/deploystack/main/docker-compose.yml
DEPLOYSTACK_ENCRYPTION_SECRET=$(openssl rand -hex 16) docker-compose up -d

Managing Your Installation

# View running services
docker-compose ps

# View logs
docker-compose logs

# Stop services
docker-compose down

# Start services
docker-compose up -d

# Update to latest version
docker-compose pull && docker-compose up -d

Method 2: Individual Docker Containers

For more control over the deployment, run frontend and backend containers separately.

Step 1: Generate Encryption Secret

# Generate a secure secret
export DEPLOYSTACK_ENCRYPTION_SECRET=$(openssl rand -hex 16)
echo "Your encryption secret: $DEPLOYSTACK_ENCRYPTION_SECRET"

# Generate a secure secret
$env:DEPLOYSTACK_ENCRYPTION_SECRET = -join ((1..32) | ForEach {'{0:X}' -f (Get-Random -Max 16)})
Write-Host "Your encryption secret: $env:DEPLOYSTACK_ENCRYPTION_SECRET"

Step 2: Start Backend Service

docker run -d \
  --name deploystack-backend \
  -p 3000:3000 \
  -e DEPLOYSTACK_FRONTEND_URL="http://localhost:8080" \
  -e DEPLOYSTACK_ENCRYPTION_SECRET="$DEPLOYSTACK_ENCRYPTION_SECRET" \
  -v deploystack_backend_persistent:/app/persistent_data \
  deploystack/backend:latest

Step 3: Start Frontend Service

docker run -d \
  --name deploystack-frontend \
  -p 8080:80 \
  -e VITE_DEPLOYSTACK_BACKEND_URL="http://localhost:3000" \
  -e VITE_APP_TITLE="DeployStack" \
  deploystack/frontend:latest

Step 4: Verify Installation

# Check if containers are running
docker ps

# Check backend health
curl http://localhost:3000/

# Access the interface
open http://localhost:8080  # macOS
# or visit http://localhost:8080 in your browser

Production Deployment

For production deployments on a server or VPS:

Update Environment Variables

Replace localhost with your server's IP address or domain:

# .env file
DEPLOYSTACK_ENCRYPTION_SECRET=your-generated-secret-here
DEPLOYSTACK_FRONTEND_URL=http://YOUR_SERVER_IP:8080
VITE_DEPLOYSTACK_BACKEND_URL=http://YOUR_SERVER_IP:3000

docker-compose up -d

# Backend
docker run -d \
  --name deploystack-backend \
  -p 3000:3000 \
  -e DEPLOYSTACK_FRONTEND_URL="http://YOUR_SERVER_IP:8080" \
  -e DEPLOYSTACK_ENCRYPTION_SECRET="your-secret-here" \
  -v deploystack_backend_persistent:/app/persistent_data \
  deploystack/backend:latest

# Frontend
docker run -d \
  --name deploystack-frontend \
  -p 8080:80 \
  -e VITE_DEPLOYSTACK_BACKEND_URL="http://YOUR_SERVER_IP:3000" \
  -e VITE_APP_TITLE="DeployStack Production" \
  deploystack/frontend:latest

Firewall Configuration

Ensure your firewall allows traffic on the required ports:

# Ubuntu/Debian
sudo ufw allow 3000  # Backend API
sudo ufw allow 8080  # Frontend

# CentOS/RHEL
sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload

Satellite Service

Adding a Satellite to Your Deployment

After completing the basic backend and frontend setup, deploy at least one satellite:

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

docker logs deploystack-satellite

✅ Satellite registered successfully: my-satellite-001
🔑 API key received and ready for authenticated communication

Satellite Persistence

After initial registration, satellites save their API key to persistent storage. This means:

• First startup: Uses registration token → Registers → Saves API key
• Subsequent startups: Uses saved API key → No token needed
• Container restarts: Automatic recovery without re-registration

The registration token is only required once during initial pairing.

Environment Variables Reference

Required Variables

Optional Variables

Satellite Variables (Required)

Next Steps

Once DeployStack is running with at least one satellite:

Troubleshooting

Common Issues

Port Conflicts

If ports 3000 or 8080 are already in use:

# Check what's using the ports
lsof -i :3000
lsof -i :8080

# Use different ports
docker run -p 3001:3000 ...  # Backend on port 3001
docker run -p 8081:80 ...    # Frontend on port 8081

Services Won't Start

# Check container logs
docker logs deploystack-backend
docker logs deploystack-frontend

# Check system resources
docker stats
df -h  # Check disk space
free -h  # Check memory

Can't Access the Interface

1. Check if services are running:

   docker ps
   curl http://localhost:3000/

2. Check firewall settings:

   # Test local connectivity
   telnet localhost 8080
   telnet localhost 3000

3. Check environment variables:

   docker inspect deploystack-frontend | grep -A 10 Env
   docker inspect deploystack-backend | grep -A 10 Env

Getting Help

If you need assistance:

• Community: Join our Discord
• Issues: Report problems on GitHub
• Support: Contact us for enterprise support options

What's Next?

Learn More

• Self-Hosted Documentation: Comprehensive deployment guides
• Local Development: Set up development environment
• Global Settings: Configure email, auth, and more
• User Roles: Manage team permissions

🎉 Congratulations! You now have DeployStack running. Start deploying MCP servers and streamline your AI agent infrastructure!