Skip to main content

​
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.
Important: Satellites are required for DeployStack to function. The platform alone cannot manage MCP servers - you must deploy at least one satellite.

​
Prerequisites

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

Download and Start

Run these two commands to get DeployStack running:
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
2

Access DeployStack

Open your browser and navigate to:
3

Complete Setup

Follow the on-screen setup wizard to:
  • Create your admin account
  • Configure basic settings
  • Set up your first MCP Server

​
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"
Save this secret! You’ll need it for upgrades and configuration changes.

​
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

​
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

Satellites are required - DeployStack cannot manage MCP servers without satellites. You must deploy at least one satellite for the platform to function.

​
Adding a Satellite to Your Deployment

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

Generate Registration Token

After setting up your admin account, generate a registration token:
  1. Log in to your DeployStack instance as admin
  2. Navigate to Admin → Satellites → Pairing
  3. Click “Generate Token” and copy the full token
The token format will be: deploystack_satellite_global_eyJhbGciOi...
2

Start Satellite Service

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
Satellite Name Requirements:
  • 10-32 characters
  • Only lowercase letters, numbers, hyphens, and underscores
  • No spaces or special characters
3

Verify Satellite Registration

Check the satellite logs to confirm successful registration:
docker logs deploystack-satellite
You should see:
✅ 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

VariableDescriptionExample
DEPLOYSTACK_ENCRYPTION_SECRET32-character secret for encrypting sensitive dataa1b2c3d4e5f6789...

​
Optional Variables

VariableDescriptionDefaultExample
DEPLOYSTACK_FRONTEND_URLURL where frontend is accessiblehttp://localhost:8080https://deploystack.company.com
VITE_DEPLOYSTACK_BACKEND_URLBackend API URL for frontendhttp://localhost:3000https://api.deploystack.company.com
VITE_APP_TITLECustom application titleDeployStackCompany DeployStack

​
Satellite Variables (Required)

VariableDescriptionExample
DEPLOYSTACK_BACKEND_URLBackend URL for satellite to connect tohttp://localhost:3000
DEPLOYSTACK_SATELLITE_NAMEUnique satellite name (10-32 chars, lowercase only)my-satellite-001
DEPLOYSTACK_REGISTRATION_TOKENJWT registration token from admin (required for initial pairing)deploystack_satellite_global_eyJhbGc...

​
Next Steps

Once DeployStack is running with at least one satellite:
1

Complete Initial Setup

  • Create your admin account
  • Configure global settings (email, authentication)
  • Set up user roles and permissions
2

Deploy Satellite Service

  • Generate registration token from admin panel
  • Deploy satellite with the token
  • Verify satellite registration and activation
  • See Satellite Service section above
3

Deploy Your First MCP Server

  • Browse the MCP server catalog
  • Configure credentials and settings
  • Deploy to your satellite
4

Explore Advanced Features

  • Set up team collaboration
  • Create private MCP server catalogs
  • Configure CI/CD integrations

​
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

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