title	Docker Compose Setup
description	Deploy DeployStack using Docker Compose for a quick and reliable self-hosted installation.

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

Docker containers are for production hosting or self-hosting. For development contributions, check the [Local Setup](/general/local-setup) guide. **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.

Overview

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

**Satellites are required**: DeployStack cannot manage MCP servers without at least one satellite. After completing the Docker Compose setup, you must deploy a satellite separately (instructions included below).

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 2GB of available disk space for images and persistent data.

Beggining the setup for Docker Compose

Follow these steps for a setup with docker compsoe

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

**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, set a strong password via the `POSTGRES_PASSWORD` environment variable in your `.env` file.

Step 2: Generate Encryption Secret

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

```bash Linux/macOS # Using OpenSSL (recommended) openssl rand -hex 16

Alternative using Node.js

node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"


```powershell Windows
# 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'))"

**Important:** Keep this secret secure and do not share it. Store it safely as you'll need it for upgrades.

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 (frontend and backend)
Create necessary volumes for persistent data
Start frontend and backend services
Set up networking between services

**Note**: This deploys the backend and frontend only. The satellite service must be deployed separately after completing the setup wizard (see Step 7 below).

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

Step 7: Deploy Satellite Service (Required)

**Satellites are required** - Without at least one satellite, DeployStack cannot manage MCP servers. Complete this step to make your deployment functional.

The satellite must be deployed separately after completing the setup wizard:

Complete Setup Wizard First:
- Access http://localhost:8080/setup
- Create your admin account
- Complete basic platform configuration
Generate Registration Token:
- Log in to DeployStack as admin
- Navigate to Admin → Satellites → Pairing
- Click "Generate Token" and copy the full token
- Token format: deploystack_satellite_global_eyJhbGc...
Find your Docker network name:

The satellite must join the same network as the backend. Find your network name:
```
docker network ls | grep deploystack
```
You'll see something like docker-compose_deploystack-network or similar. Use this name in the next step.
Deploy Satellite with Docker:
The satellite requires a running backend. If the backend is not reachable, the satellite will exit immediately. Make sure `docker-compose ps` shows the backend as healthy before proceeding. **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.
For local development (connecting from same machine):
```
docker run -d \
  --network <your-network-name> \
  -p 3001:3001 \
  -e DEPLOYSTACK_BACKEND_URL="http://deploystack-backend:3000" \
  -e DEPLOYSTACK_SATELLITE_NAME="docker-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 step 3.

For remote access (connecting from MCP clients via domain/IP):
```
docker run -d \
  --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="docker-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`:** - 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

Verify Satellite Registration:

docker logs <container-id>
# Should show: ✅ Satellite registered successfully: docker-satellite-001

Get the container ID from docker ps.

**Note**: After initial registration, the satellite saves its API key to persistent storage. The registration token is only needed for the first startup. Container restarts will use the saved API key automatically.

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

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

Restart the services:

docker-compose down
docker-compose up -d

SSL/HTTPS Setup

HTTPS is recommended for production deployments to ensure secure communication and enable all browser features.

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
deploystack_satellite_persistent: Satellite credentials and process data (created when satellite is deployed separately)

Backup Your Data

Regularly backup your persistent data:

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

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

# Backup satellite volume (if satellite is deployed)
docker run --rm -v deploystack_satellite_persistent:/data -v $(pwd)/backups/$(date +%Y%m%d):/backup alpine tar czf /backup/satellite_persistent.tar.gz -C /data .

Environment Variables Reference

Required Variables

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

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`
`FRONTEND_PORT`	Frontend port mapping	`8080`	`80`
`BACKEND_PORT`	Backend port mapping	`3000`	`3001`

Satellite Variables

Satellite services are deployed separately using docker run commands (not via docker-compose). See Step 7: Deploy Satellite Service for deployment instructions.

Required Satellite Environment Variables:

Variable	Description	Example
`DEPLOYSTACK_BACKEND_URL`	Backend URL for satellite to connect to	`http://deploystack-backend:3000`
`DEPLOYSTACK_SATELLITE_NAME`	Unique satellite name (10-32 chars, lowercase only)	`docker-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`

Troubleshooting

Common Issues

Services Won't Start

# Check logs
docker-compose logs

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

Getting Help

If you encounter issues not covered here:

Search existing GitHub Issues
Join our Discord community
Create a new issue with detailed logs and system information

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Overview

System Requirements

Beggining the setup for Docker Compose

Step 1: Download Docker Compose File

Step 2: Generate Encryption Secret

Alternative using Node.js

Step 3: Set Environment Variables

Step 4: Launch DeployStack

Step 5: Verify Installation

Step 6: Access DeployStack

Step 7: Deploy Satellite Service (Required)

Configuration

External Access

Understanding URLs

Configuring for External Access

SSL/HTTPS Setup

Data Persistence

Backup Your Data

Environment Variables Reference

Required Variables

Optional Variables

Satellite Variables

Troubleshooting

Common Issues

Services Won't Start

Getting Help

FilesExpand file tree

docker-compose.mdx

Latest commit

History

docker-compose.mdx

File metadata and controls

Overview

System Requirements

Beggining the setup for Docker Compose

Step 1: Download Docker Compose File

Step 2: Generate Encryption Secret

Alternative using Node.js

Step 3: Set Environment Variables

Step 4: Launch DeployStack

Step 5: Verify Installation

Step 6: Access DeployStack

Step 7: Deploy Satellite Service (Required)

Configuration

External Access

Understanding URLs

Configuring for External Access

SSL/HTTPS Setup

Data Persistence

Backup Your Data

Environment Variables Reference

Required Variables

Optional Variables

Satellite Variables

Troubleshooting

Common Issues

Services Won't Start

Getting Help