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

# Quick Start

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

<Warning>
  **Important**: Satellites are required for DeployStack to function. The platform alone cannot manage MCP servers - you must deploy at least one satellite.
</Warning>

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

## Prerequisites

* **Docker**: [Install Docker](https://docs.docker.com/get-docker/)
* **Docker Compose**: [Install Docker Compose](https://docs.docker.com/compose/install/)
* **System Requirements**: 4GB RAM, 20GB disk space

## Method 1: Docker Compose (Recommended)

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

<Steps>
  <Step title="Download and Start">
    Run these two commands to get DeployStack backend and frontend running:

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

  <Step title="Access DeployStack">
    Open your browser and navigate to:

    * **DeployStack Interface**: [http://localhost:8080](http://localhost:8080)
    * **Backend API**: [http://localhost:3000](http://localhost:3000)
  </Step>

  <Step title="Create Admin Account">
    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
  </Step>

  <Step title="Deploy Satellite">
    After creating your admin account, proceed to the [Satellite Service](#satellite-service) section below to deploy your first satellite and start managing MCP servers.
  </Step>
</Steps>

### Managing Your Installation

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

<CodeGroup>
  ```bash Linux/macOS theme={null}
  # Generate a secure secret
  export DEPLOYSTACK_ENCRYPTION_SECRET=$(openssl rand -hex 16)
  echo "Your encryption secret: $DEPLOYSTACK_ENCRYPTION_SECRET"
  ```

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

<Warning>
  **Save this secret!** You'll need it for upgrades and configuration changes.
</Warning>

### Step 2: Start Backend Service

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

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

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

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

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

### Firewall Configuration

Ensure your firewall allows traffic on the required ports:

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

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

### Adding a Satellite to Your Deployment

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

<Steps>
  <Step title="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...`
  </Step>

  <Step title="Find Docker Network">
    The satellite must join the same Docker 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.
  </Step>

  <Step title="Start Satellite Service">
    <Warning>
      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.
    </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 \
      --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 theme={null}
    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>
  </Step>

  <Step title="Verify Satellite Registration">
    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.
  </Step>
</Steps>

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

<Steps>
  <Step title="Complete Initial Setup">
    * Create your admin account
    * Configure global settings (email, authentication)
    * Set up user roles and permissions
  </Step>

  <Step title="Deploy Satellite Service">
    * Generate registration token from admin panel
    * Deploy satellite with the token
    * Verify satellite registration and activation
    * See [Satellite Service](#satellite-service) section above
  </Step>

  <Step title="Deploy Your First MCP Server">
    * Browse the MCP server catalog
    * Configure credentials and settings
    * Deploy to your satellite
  </Step>

  <Step title="Explore Advanced Features">
    * Set up team collaboration
    * Create private MCP server catalogs
    * Configure CI/CD integrations
  </Step>
</Steps>

## Troubleshooting

### Common Issues

#### Port Conflicts

If ports 3000 or 8080 are already in use:

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

```bash theme={null}
# 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**:
   ```bash theme={null}
   docker ps
   curl http://localhost:3000/
   ```

2. **Check firewall settings**:
   ```bash theme={null}
   # Test local connectivity
   telnet localhost 8080
   telnet localhost 3000
   ```

3. **Check environment variables**:
   ```bash theme={null}
   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](https://discord.gg/UjFWwByB)
* **Issues**: Report problems on [GitHub](https://github.com/deploystackio/deploystack/issues)
* **Support**: Contact us for enterprise support options

## What's Next?

### Learn More

* **[Self-Hosted Documentation](/self-hosted)**: Comprehensive deployment guides
* **[Local Development](/general/local-setup)**: Set up development environment
* **[Global Settings](/general/global-settings)**: Configure email, auth, and more
* **[User Roles](/general/roles)**: Manage team permissions

***

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