diff --git a/development/backend/database/index.mdx b/development/backend/database/index.mdx index f50f6a0..50439e8 100644 --- a/development/backend/database/index.mdx +++ b/development/backend/database/index.mdx @@ -397,7 +397,7 @@ POSTGRES_SSL=true ```yaml services: postgres: - image: postgres:16-alpine + image: postgres:18-alpine environment: POSTGRES_DB: deploystack POSTGRES_USER: deploystack diff --git a/development/backend/database/postgresql.mdx b/development/backend/database/postgresql.mdx index 8c76f2a..305b5b4 100644 --- a/development/backend/database/postgresql.mdx +++ b/development/backend/database/postgresql.mdx @@ -265,7 +265,7 @@ This enables SSL with `rejectUnauthorized: false` for self-signed certificates. ```yaml services: postgres: - image: postgres:16-alpine + image: postgres:18-alpine environment: POSTGRES_DB: deploystack POSTGRES_USER: deploystack diff --git a/development/satellite/process-management.mdx b/development/satellite/process-management.mdx index 2cd077a..34c974e 100644 --- a/development/satellite/process-management.mdx +++ b/development/satellite/process-management.mdx @@ -116,6 +116,10 @@ All communication uses newline-delimited JSON following JSON-RPC 2.0 specificati **Idle Process Management**: Processes that remain inactive for extended periods are automatically terminated and respawned on-demand to optimize memory usage. See [Idle Process Management](/development/satellite/idle-process-management) for details on automatic termination, dormant state tracking, and respawning. + +**Configuration Updates**: When a user updates their MCP server configuration (args, env) via the dashboard, the backend sends a configure command to the satellite. For stdio servers, the satellite automatically restarts the process with the new configuration. See [Backend Communication](/development/satellite/backend-communication) for the command flow. + + ### Lifecycle States **starting:** @@ -161,7 +165,7 @@ Process termination follows a two-phase graceful shutdown approach to ensure cle #### Termination Types -The system handles three types of intentional terminations differently: +The system handles four types of intentional terminations differently: **1. Manual Termination** - Triggered by explicit restart or stop commands @@ -184,6 +188,19 @@ The system handles three types of intentional terminations differently: - No auto-restart triggered (intentional removal) - Invoked via `removeServerCompletely()` method +**4. Configuration Update Restart** +- Triggered when stdio server configuration is modified (e.g., user args change) +- Detected via `DynamicConfigManager` comparing old vs new configuration +- Existing process terminated with graceful shutdown +- Tools cleared from cache via `stdioToolDiscoveryManager.clearServerTools()` +- New process spawned with updated configuration (new args, env) +- Tool discovery runs automatically on the new process +- Enables real-time configuration updates without satellite restart + + +**HTTP/SSE Servers**: Unlike stdio servers, HTTP/SSE servers don't require restart on config changes. Their configuration (headers, query params, URL) is read fresh on each request, so updates are immediate. + + #### Crash Detection vs Intentional Shutdown The system distinguishes between crashes and intentional shutdowns: diff --git a/self-hosted/docker-compose.mdx b/self-hosted/docker-compose.mdx index 5790e00..7cdbf34 100644 --- a/self-hosted/docker-compose.mdx +++ b/self-hosted/docker-compose.mdx @@ -44,6 +44,10 @@ 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. @@ -144,13 +148,25 @@ The satellite must be deployed separately after completing the setup wizard: - Click "Generate Token" and copy the full token - Token format: `deploystack_satellite_global_eyJhbGc...` -3. **Deploy Satellite with Docker**: +3. **Find your Docker network name**: + + The satellite must join the same 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. + +4. **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. + **For local development (connecting from same machine):** ```bash docker run -d \ - --name deploystack-satellite \ - --network deploystack-network \ + --network \ -p 3001:3001 \ -e DEPLOYSTACK_BACKEND_URL="http://deploystack-backend:3000" \ -e DEPLOYSTACK_SATELLITE_NAME="docker-satellite-001" \ @@ -159,11 +175,12 @@ The satellite must be deployed separately after completing the setup wizard: deploystack/satellite:latest ``` + Replace `` with the network from step 3 (e.g., `docker-compose_deploystack-network`). + **For remote access (connecting from MCP clients via domain/IP):** ```bash docker run -d \ - --name deploystack-satellite \ - --network deploystack-network \ + --network \ -p 3001:3001 \ -e DEPLOYSTACK_BACKEND_URL="http://deploystack-backend:3000" \ -e DEPLOYSTACK_SATELLITE_URL="https://satellite.example.com" \ @@ -181,12 +198,14 @@ The satellite must be deployed separately after completing the setup wizard: - Required for OAuth authentication to work with remote MCP clients -4. **Verify Satellite Registration**: +5. **Verify Satellite Registration**: ```bash - docker logs deploystack-satellite + docker logs # 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. diff --git a/self-hosted/quick-start.mdx b/self-hosted/quick-start.mdx index 05eef64..d618651 100644 --- a/self-hosted/quick-start.mdx +++ b/self-hosted/quick-start.mdx @@ -38,6 +38,10 @@ The fastest way to get DeployStack backend and frontend running with proper netw **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). + + + **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. + @@ -46,14 +50,14 @@ The fastest way to get DeployStack backend and frontend running with proper netw - **Backend API**: [http://localhost:3000](http://localhost:3000) - - Follow the on-screen setup wizard to: - - Create your admin account - - Configure basic settings + + 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](/roles)) + - Login with your new admin account - After completing the setup wizard, proceed to the [Satellite Service](#satellite-service) section below to deploy your first satellite and start managing MCP servers. + After creating your admin account, proceed to the [Satellite Service](#satellite-service) section below to deploy your first satellite and start managing MCP servers. @@ -209,25 +213,43 @@ After completing the basic backend and frontend setup, deploy at least one satel 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. + + **For local development (connecting from same machine):** ```bash - docker run -d \ - --name deploystack-satellite \ + docker run \ + --network \ -p 3001:3001 \ - -e DEPLOYSTACK_BACKEND_URL="http://localhost:3000" \ + -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 `` 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 -d \ - --name deploystack-satellite \ + docker run \ + --network \ -p 3001:3001 \ - -e DEPLOYSTACK_BACKEND_URL="http://YOUR_SERVER_IP:3000" \ + -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" \ @@ -242,7 +264,7 @@ After completing the basic backend and frontend setup, deploy at least one satel - 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 - + **Satellite Name Requirements:** - 10-32 characters @@ -250,19 +272,15 @@ After completing the basic backend and frontend setup, deploy at least one satel - No spaces or special characters - + - Check the satellite logs to confirm successful registration: - - ```bash - docker logs deploystack-satellite - ``` - - You should see: + 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.