> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deploystack.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker Compose Setup

> 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.

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

<Info>
  **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](/self-hosted/production-satellite) which includes nsjail process isolation for security and team separation.
</Info>

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

<Warning>
  **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).
</Warning>

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

```bash theme={null}
curl -o docker-compose.yml https://raw.githubusercontent.com/deploystackio/deploystack/main/docker-compose.yml
```

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

### Step 2: Generate Encryption Secret

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

<CodeGroup>
  ```bash Linux/macOS theme={null}
  # Using OpenSSL (recommended)
  openssl rand -hex 16

  # Alternative using Node.js
  node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"
  ```

  ```powershell Windows theme={null}
  # 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'))"
  ```
</CodeGroup>

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

### Step 3: Set Environment Variables

Create a `.env` file in the same directory as your `docker-compose.yml`:

```bash theme={null}
# 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:

```bash theme={null}
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

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

### Step 5: Verify Installation

Check that all services are running:

```bash theme={null}
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](http://localhost:8080)
* **Backend API**: [http://localhost:3000](http://localhost:3000)

### Step 7: Deploy Satellite Service (Required)

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

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

1. **Complete Setup Wizard First**:
   * Access [http://localhost:8080/setup](http://localhost:8080/setup)
   * Create your admin account
   * Complete basic platform configuration

2. **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...`

3. **Find your Docker network name**:

   The satellite must join the same network as the backend. Find your network name:

   ```bash theme={null}
   docker network ls | grep deploystack
   ```

   You'll see something like `docker-compose_deploystack-network` or similar. Use this name in the next step.

4. **Deploy Satellite with Docker**:

   <Warning>
     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.
   </Warning>

   <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 theme={null}
   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):**

   ```bash theme={null}
   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
   ```

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

5. **Verify Satellite Registration**:

   ```bash theme={null}
   docker logs <container-id>
   # Should show: ✅ Satellite registered successfully: docker-satellite-001
   ```

   Get the container ID from `docker ps`.

<Info>
  **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.
</Info>

## 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

1. **Update your `.env` file**:

```bash theme={null}
# 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
```

2. **Restart the services**:

```bash theme={null}
docker-compose down
docker-compose up -d
```

### SSL/HTTPS Setup

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

For HTTPS setup, we recommend using a reverse proxy like Nginx or Traefik:

```nginx theme={null}
# 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:

```bash theme={null}
# 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](#step-7-deploy-satellite-service-required) 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

```bash theme={null}
# 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:

1. Search existing [GitHub Issues](https://github.com/deploystackio/deploystack/issues)
2. Join our [Discord community](https://discord.gg/42Ce3S7b3b)
3. Create a new issue with detailed logs and system information

***

**Need to upgrade?** Check our [Upgrade Guide](/self-hosted/upgrade-guide) for step-by-step instructions.