Merge pull request #282 from deploystackio/main

Lasim · web-flow · commit d41f0189e67b · 2025-11-04T20:58:46.000+01:00
prod-release
diff --git a/self-hosted/docker-compose.mdx b/self-hosted/docker-compose.mdx
@@ -18,10 +18,10 @@ For **production deployments with multiple teams** or external users, see [Produ
 
 ## Overview
 
-This guide provides step-by-step instructions to install and configure DeployStack using Docker Compose. The setup includes frontend, backend, and **required satellite service** with persistent data storage and proper networking.
+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. This guide includes satellite deployment as a mandatory step.
+**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.
@@ -80,13 +80,9 @@ cat > .env << EOF
 # DeployStack Configuration
 DEPLOYSTACK_ENCRYPTION_SECRET=your-generated-secret-here
 
-# Satellite Registration (required - obtain from admin panel after setup)
-DEPLOYSTACK_REGISTRATION_TOKEN=
-
-# Optional: Customize ports (default: frontend=8080, backend=3000, satellite=3001)
+# Optional: Customize ports (default: frontend=8080, backend=3000)
 # FRONTEND_PORT=8080
 # BACKEND_PORT=3000
-# SATELLITE_PORT=3001
 
 # Optional: Custom app title
 # VITE_APP_TITLE=My DeployStack Instance
@@ -95,10 +91,6 @@ EOF
 
 Replace `your-generated-secret-here` with the secret you generated in Step 2.
 
-<Warning>
-**Important**: Leave `DEPLOYSTACK_REGISTRATION_TOKEN` empty for now. You'll add it after completing the admin setup in Step 6.
-</Warning>
-
 ### Step 4: Launch DeployStack
 
 Start the Docker containers:
@@ -108,11 +100,15 @@ docker-compose up -d
 ```
 
 This command will:
-- Pull the latest DeployStack images
+- Pull the latest DeployStack images (frontend and backend)
 - Create necessary volumes for persistent data
-- Start both frontend and backend services
+- 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:
@@ -135,32 +131,65 @@ Open your browser and navigate to:
 **Satellites are required** - Without at least one satellite, DeployStack cannot manage MCP servers. Complete this step to make your deployment functional.
 </Warning>
 
-The satellite service is **already included** in the docker-compose.yml file. You just need to configure the registration token:
+The satellite must be deployed separately after completing the setup wizard:
+
+1. **Complete Setup Wizard First**:
+   - Access http://localhost:8080/setup
+   - Create your admin account
+   - Complete basic platform configuration
 
-1. **Generate Registration Token** (via admin interface after backend setup):
-   - Log in to DeployStack as admin (complete Step 6 first)
+2. **Generate Registration Token**:
+   - Log in to DeployStack as admin
    - Navigate to Admin → Satellites → Pairing
-   - Click "Generate Token" and copy it
+   - Click "Generate Token" and copy the full token
+   - Token format: `deploystack_satellite_global_eyJhbGc...`
 
-2. **Add token to your `.env` file**:
+3. **Deploy Satellite with Docker**:
+
+   **For local development (connecting from same machine):**
    ```bash
-   # Satellite Configuration (required)
-   DEPLOYSTACK_REGISTRATION_TOKEN=deploystack_satellite_global_eyJhbGc...
+   docker run -d \
+     --name deploystack-satellite \
+     --network deploystack-network \
+     -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
    ```
 
-3. **Restart services to apply token**:
+   **For remote access (connecting from MCP clients via domain/IP):**
    ```bash
-   docker-compose down
-   docker-compose up -d
+   docker run -d \
+     --name deploystack-satellite \
+     --network deploystack-network \
+     -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
    ```
 
-4. **Verify satellite registration**:
+   <Info>
+   **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
+   </Info>
+
+4. **Verify Satellite Registration**:
    ```bash
    docker logs deploystack-satellite
    # Should show: ✅ Satellite registered successfully: docker-satellite-001
    ```
 
-**Note**: After initial registration, the satellite saves its API key to persistent storage and doesn't need the registration token for subsequent starts.
+<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
 
@@ -234,6 +263,7 @@ server {
 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
 
@@ -243,8 +273,11 @@ Regularly backup your persistent data:
 # Create backup directory
 mkdir -p backups/$(date +%Y%m%d)
 
-# Backup volume
+# 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
@@ -265,15 +298,23 @@ docker run --rm -v deploystack_backend_persistent:/data -v $(pwd)/backups/$(date
 | `FRONTEND_PORT` | Frontend port mapping | `8080` | `80` |
 | `BACKEND_PORT` | Backend port mapping | `3000` | `3001` |
 
-### Satellite Variables (Required)
+### 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_REGISTRATION_TOKEN` | JWT registration token from admin (required for initial satellite pairing) | `deploystack_satellite_global_eyJhbGc...` |
+| `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...` |
 
-<Info>
-**Note**: The satellite name `docker-satellite-001` is pre-configured in docker-compose.yml. You only need to provide the registration token in your `.env` file.
-</Info>
+**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
 
diff --git a/self-hosted/production-satellite.mdx b/self-hosted/production-satellite.mdx
@@ -248,6 +248,12 @@ LOG_LEVEL=info
 DEPLOYSTACK_BACKEND_URL=https://cloud.deploystack.io
 DEPLOYSTACK_BACKEND_POLLING_INTERVAL=60
 
+# Satellite Public URL (REQUIRED for remote MCP client connections)
+# This is the publicly accessible URL where MCP clients connect
+# Used for OAuth 2.0 Protected Resource Metadata (RFC 9728)
+# Example: https://satellite.example.com (no /mcp or /sse paths)
+DEPLOYSTACK_SATELLITE_URL=https://satellite.example.com
+
 # Satellite Identity (10-32 chars, lowercase a-z0-9-_ only)
 DEPLOYSTACK_SATELLITE_NAME=prod-satellite-001
 
diff --git a/self-hosted/quick-start.mdx b/self-hosted/quick-start.mdx
@@ -4,7 +4,7 @@ description: Get DeployStack running in minutes with Docker Compose or individua
 ---
 
 
-Get DeployStack up and running in minutes. This guide covers deploying the core platform (frontend + backend) and the required satellite service for MCP server management.
+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.
@@ -24,29 +24,36 @@ For **production deployments with multiple teams** or external users, see [Produ
 
 ## Method 1: Docker Compose (Recommended)
 
-The fastest way to get DeployStack running with proper networking and persistence.
+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 running:
-    
+    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>
   </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="Complete Setup">
+
+  <Step title="Complete Setup Wizard">
     Follow the on-screen setup wizard to:
     - Create your admin account
     - Configure basic settings
-    - Set up your first MCP Server
+  </Step>
+
+  <Step title="Deploy Satellite">
+    After completing the setup wizard, proceed to the [Satellite Service](#satellite-service) section below to deploy your first satellite and start managing MCP servers.
   </Step>
 </Steps>
 
@@ -203,6 +210,7 @@ After completing the basic backend and frontend setup, deploy at least one satel
   </Step>
   
   <Step title="Start Satellite Service">
+    **For local development (connecting from same machine):**
     ```bash
     docker run -d \
       --name deploystack-satellite \
@@ -213,6 +221,27 @@ After completing the basic backend and frontend setup, deploy at least one satel
       -v deploystack_satellite_persistent:/app/persistent_data \
       deploystack/satellite:latest
     ```
+
+    **For remote access (connecting from MCP clients via domain/IP):**
+    ```bash
+    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
+    ```
+
+    <Info>
+    **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
+    </Info>
     
     <Warning>
     **Satellite Name Requirements:**
@@ -263,14 +292,22 @@ The registration token is only required once during initial pairing.
 | `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)
+### 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:
