Skip to content

quick-start.mdx

Latest commit

 

History

History
435 lines (327 loc) · 13.9 KB

quick-start.mdx

File metadata and controls

435 lines (327 loc) · 13.9 KB
Raw
title Quick Start
description Get DeployStack running in minutes with Docker Compose or individual Docker containers.

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

Method 1: Docker Compose (Recommended)

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

Run these two commands to get DeployStack backend and frontend running: 
```bash
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
```

<Info>
**Note**: This deploys the backend and frontend only. The satellite service must be deployed separately after completing the setup wizard (see [Satellite Service](#satellite-service) section below).
</Info>

<Info>
**Default Database Password**: The Docker Compose file uses a default PostgreSQL password (`deploystack`) for quick demos and local testing. For production or internet-exposed deployments, add `POSTGRES_PASSWORD=your_secure_password` before the command.
</Info>
Open your browser and navigate to: - **DeployStack Interface**: [http://localhost:8080](http://localhost:8080) - **Backend API**: [http://localhost:3000](http://localhost:3000) When opening the frontend, you will be redirected to `http://localhost:8080/login` - Go to "Create Account" to set up your admin user ([read more about user types](/general/roles)) - Login with your new admin account After creating your admin account, proceed to the [Satellite Service](#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

```bash Linux/macOS # 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"
**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:

```bash Docker Compose # .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 ``` 
# 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

**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:

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...`
The satellite must join the same Docker network as the backend. Find your network name: 
```bash
docker network ls | grep deploystack
```

You'll see something like `docker-compose_deploystack-network` or similar. Use this name in the next step.
The satellite requires a running backend. If the backend is not reachable, the satellite will exit immediately. Make sure the backend is running before proceeding. 
<Info>
**Automatic Permission Handling**: The satellite container automatically fixes Docker volume permissions on startup. This ensures credentials can be saved even when volumes have root ownership. You may notice a brief delay (~5 seconds) during first startup while permissions are being fixed.
</Info>

**For local development (connecting from same machine):**
```bash
docker run \
  --network <your-network-name> \
  -p 3001:3001 \
  -e DEPLOYSTACK_BACKEND_URL="http://deploystack-backend: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
```

Replace `<your-network-name>` with the network from the previous step (e.g., `docker-compose_deploystack-network`).

The logs will be displayed directly in your terminal. You should see the satellite connect to the backend and register successfully.

**For remote access (connecting from MCP clients via domain/IP):**
```bash
docker run \
  --network <your-network-name> \
  -p 3001:3001 \
  -e DEPLOYSTACK_BACKEND_URL="http://deploystack-backend: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
```

<Info>
**When to set `DEPLOYSTACK_SATELLITE_URL`:**
- The Docker image defaults to `http://localhost:3001` which works for local development
- Override with `-e DEPLOYSTACK_SATELLITE_URL="https://satellite.example.com"` when MCP clients connect via a domain or IP address
- Use base URL only — no `/mcp` or `/sse` paths
- Required for OAuth authentication to work with remote MCP clients
</Info>

<Warning>
**Satellite Name Requirements:**
- 10-32 characters
- Only lowercase letters, numbers, hyphens, and underscores
- No spaces or special characters
</Warning>
In the terminal output, you should see: ``` ✅ Satellite registered successfully: my-satellite-001 🔑 API key received and ready for authenticated communication ``` 
Once verified, you can stop the container with `Ctrl+C` and restart it in detached mode by adding `-d` flag to the command.

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

Variable Description Example
DEPLOYSTACK_ENCRYPTION_SECRET 32-character secret for encrypting sensitive data a1b2c3d4e5f6789...

Optional Variables

Variable Description Default Example
DEPLOYSTACK_FRONTEND_URL URL where frontend is accessible http://localhost:8080 https://deploystack.company.com
VITE_DEPLOYSTACK_BACKEND_URL Backend API URL for frontend http://localhost:3000 https://api.deploystack.company.com
VITE_APP_TITLE Custom application title DeployStack Company DeployStack

Satellite Variables

Required:

Variable Description Example
DEPLOYSTACK_BACKEND_URL Backend URL for satellite to connect to http://localhost:3000
DEPLOYSTACK_SATELLITE_NAME Unique satellite name (10-32 chars, lowercase only) my-satellite-001
DEPLOYSTACK_REGISTRATION_TOKEN JWT registration token from admin (required for initial pairing) deploystack_satellite_global_eyJhbGc...

Optional (Required for Remote Access):

Variable Description Default Example
DEPLOYSTACK_SATELLITE_URL Public URL of satellite for OAuth metadata (required when MCP clients connect remotely) http://localhost:PORT https://satellite.example.com

Next Steps

Once DeployStack is running with at least one satellite:

- Create your admin account - Configure global settings (email, authentication) - Set up user roles and permissions - Generate registration token from admin panel - Deploy satellite with the token - Verify satellite registration and activation - See [Satellite Service](#satellite-service) section above - Browse the MCP server catalog - Configure credentials and settings - Deploy to your satellite - 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!