Skip to main content
Get DeployStack up and running in minutes. This guide covers deploying the core platform (frontend + backend). After completing the initial setup, you’ll deploy a 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.
Deployment Type: This guide covers development and single-team deployments. The satellite runs without process isolation, suitable for local development or when serving only your own team.For production deployments with multiple teams or external users, see Production Satellite Setup which includes nsjail process isolation for security and team separation.

​
Prerequisites

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

Download and Start

Run these two commands to get DeployStack backend and frontend 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
Note: This deploys the backend and frontend only. The satellite service must be deployed separately after completing the setup wizard (see Satellite Service section below).
2

Access DeployStack

Open your browser and navigate to:
3

Complete Setup Wizard

Follow the on-screen setup wizard to:
  • Create your admin account
  • Configure basic settings
4

Deploy Satellite

After completing the setup wizard, proceed to the Satellite Service section below to deploy your first satellite and start managing MCP servers.

​
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

For local development (connecting from same machine):
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
For remote access (connecting from MCP clients via domain/IP):
docker run -d \
  --name deploystack-satellite \
  -p 3001:3001 \
  -e DEPLOYSTACK_BACKEND_URL="http://YOUR_SERVER_IP:3000" \
  -e DEPLOYSTACK_SATELLITE_URL="https://satellite.example.com" \
  -e DEPLOYSTACK_SATELLITE_NAME="my-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
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...
Optional (Required for Remote Access):
VariableDescriptionDefaultExample
DEPLOYSTACK_SATELLITE_URLPublic URL of satellite for OAuth metadata (required when MCP clients connect remotely)http://localhost:PORThttps://satellite.example.com

​
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!