### Local Development Setup - Bash

Source: https://github.com/deploystackio/documentation/blob/main/development/satellite/backend-communication.mdx

Steps to clone the Deploystack repository, install dependencies, configure environment variables, and start the local development server.

```bash
# Clone and setup
git clone https://github.com/deploystackio/deploystack.git
cd deploystack/services/satellite
npm install

# Configure environment
cp .env.example .env
# Edit DEPLOYSTACK_BACKEND_URL and add DEPLOYSTACK_REGISTRATION_TOKEN
# Obtain registration token from backend admin interface first

# Start development server
npm run dev
# Server runs on http://localhost:3001
```

--------------------------------

### Development Setup Example

Source: https://github.com/deploystackio/documentation/blob/main/development/frontend/environment-variables.mdx

A command-line example demonstrating the setup for local development. It includes navigating to the frontend directory, copying the base environment file, adding local overrides, and starting the development server.

```bash
# Navigate to frontend directory
cd services/frontend

# Create your local environment file
cp .env .env.local

# Edit .env.local with your local settings
echo "VITE_APP_TITLE=DeployStack (My Local Dev)" >> .env.local

# Start development server
npm run dev
```

--------------------------------

### Local Development Setup (Bash)

Source: https://github.com/deploystackio/documentation/blob/main/development/backend/satellite/communication.mdx

Provides commands to set up the backend and satellite services for local development. It includes installing dependencies and starting the development servers for both components.

```bash
# Backend setup
cd services/backend
npm install
npm run dev  # Starts on http://localhost:3000

# Satellite setup (separate terminal)
cd services/satellite  
npm install
npm run dev  # Starts on http://localhost:3001
```

--------------------------------

### Local Development Setup for Satellite

Source: https://github.com/deploystackio/documentation/blob/main/development/satellite/oauth-authentication.mdx

Guides through cloning the Deploystack repository, installing dependencies, and configuring environment variables for local satellite development. It also outlines the necessary steps to start the backend service before the satellite.

```bash
git clone https://github.com/deploystackio/deploystack.git
cd deploystack/services/satellite
npm install
cp .env.example .env
# Edit DEPLOYSTACK_SATELLITE_NAME and DEPLOYSTACK_BACKEND_URL
npm run dev
```

--------------------------------

### Install Dependencies and Start Development Server (Bash)

Source: https://github.com/deploystackio/documentation/blob/main/development/frontend/index.mdx

Commands to navigate to the frontend directory, install project dependencies using npm, and start the Vite development server. This setup enables hot module replacement for a faster development cycle.

```bash
cd services/frontend
npm install
npm run dev
```

--------------------------------

### Satellite Development Setup (Bash)

Source: https://context7.com/deploystackio/documentation/llms.txt

Guides on setting up a local development environment for satellite services, including cloning the repository, installing dependencies, configuring environment variables, and starting the development server with hot reload. It also lists available npm scripts and provides a cURL command for testing MCP connection.

```bash
# Clone and setup
cd services/satellite
npm install

# Configure environment
cp .env.example .env
# Edit: LOG_LEVEL=debug, PORT=3001

# Start development server with hot reload
npm run dev
# Server: http://localhost:3001
# API docs: http://localhost:3001/documentation

# Available scripts
npm run dev      # Development server with hot reload
npm run build    # Production build
npm run start    # Start production server
npm run lint     # ESLint with auto-fix
npm run release  # Release management

# Test MCP connection
curl -X POST "http://localhost:3001/mcp" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{}}'

```

--------------------------------

### DeployStack MCP Server Setup Steps

Source: https://github.com/deploystackio/documentation/blob/main/general/architecture.mdx

Describes the simplified setup process using DeployStack, which requires no installation. Users register, create OAuth credentials, and add a URL to VS Code settings for immediate access to authorized tools.

```bash
# Zero installation setup for entire team
1. Register at cloud.deploystack.io
2. Create OAuth client credentials
3. Add URL to VS Code configuration
4. # Done! All authorized tools available immediately
```

--------------------------------

### Install and Run Mintlify CLI for Local Development

Source: https://github.com/deploystackio/documentation/blob/main/README.md

Installs the Mintlify CLI globally and starts a local development server for previewing documentation changes. This enables hot reloading, navigation preview, component rendering, and dark/light mode testing.

```bash
# Install Mintlify CLI globally (one-time setup)
npm install -g mintlify

# Start local development server
mintlify dev

# The documentation will be available at http://localhost:3000
```

--------------------------------

### Clone and Setup Deploystack Satellite Service

Source: https://github.com/deploystackio/documentation/blob/main/development/satellite/architecture.mdx

Instructions to clone the Deploystack repository, navigate to the satellite service directory, install dependencies, set up environment variables, and start the development server.

```bash
git clone https://github.com/deploystackio/deploystack.git
cd deploystack/services/satellite
npm install
cp .env.example .env
npm run dev
```

--------------------------------

### Backend Development Setup

Source: https://github.com/deploystackio/documentation/blob/main/development/satellite/oauth-authentication.mdx

Instructions for starting the Deploystack backend service locally, which is a prerequisite for the satellite's operation. The backend typically runs on http://localhost:3000.

```bash
# Start backend first (required for satellite operation)
cd services/backend
npm run dev
# Backend runs on http://localhost:3000
```

--------------------------------

### Environment Configuration Examples (Bash)

Source: https://github.com/deploystackio/documentation/blob/main/development/frontend/index.mdx

Example `.env` and `.env.local` files for configuring environment variables in the frontend application. These files are used to set base URLs and application titles, with local overrides for development.

```bash
# .env (base configuration)
VITE_DEPLOYSTACK_BACKEND_URL=http://localhost:3000
VITE_APP_TITLE=DeployStack

# .env.local (local overrides, gitignored)
VITE_DEPLOYSTACK_BACKEND_URL=http://localhost:3000
VITE_APP_TITLE=DeployStack (Development)
```

--------------------------------

### Install Backend Dependencies

Source: https://github.com/deploystackio/documentation/blob/main/development/backend/test.mdx

Installs all necessary Node.js dependencies for the backend service, including testing libraries like Jest and Supertest. This command should be run from the 'services/backend' directory.

```bash
cd services/backend
npm install
```

--------------------------------

### Example Component Directory Structure - MCP Server

Source: https://github.com/deploystackio/documentation/blob/main/development/frontend/architecture.mdx

Provides a concrete example of organizing feature-specific components, demonstrating nested structures for installation and catalog features within the 'mcp-server' module.

```tree
components/
├── mcp-server/
│   ├── installation/
│   │   ├── InstallationInfo.vue
│   │   ├── InstallationTabs.vue
│   │   ├── McpToolsTab.vue
│   │   ├── TeamConfiguration.vue
│   │   ├── UserConfiguration.vue
│   │   ├── DangerZone.vue
│   │   └── index.ts
│   └── catalog/
│       ├── ServerCard.vue
│       ├── ServerFilters.vue
│       └── index.ts
```

--------------------------------

### Setup Database via API or Frontend Wizard

Source: https://github.com/deploystackio/documentation/blob/main/development/backend/database/postgresql.mdx

Describes two methods for setting up the database within the Deploystack application: via a POST request to the `/api/db/setup` endpoint or through a frontend wizard accessible at `http://localhost:5173/setup`. Both methods initiate the database setup process, typically involving schema creation and initial seeding.

```bash
# Via API
curl -X POST http://localhost:3000/api/db/setup \
  -H "Content-Type: application/json" \
  -d '{"type": "postgresql"}'

# Or use frontend wizard at http://localhost:5173/setup
```

--------------------------------

### Start Backend and Frontend Servers (Background Processes)

Source: https://github.com/deploystackio/documentation/blob/main/general/local-setup.mdx

This approach allows running both backend and frontend development servers from a single terminal. The backend is typically started in the background using '&' on Linux/macOS, while the frontend runs in the foreground. For Windows, 'Start-Process' is used to launch the backend in a new PowerShell window. Instructions for stopping background processes are also provided.

```bash
# Start backend in background
npm run dev:backend &

# Start frontend
npm run dev:frontend

# To stop background processes later:
# pkill -f "npm run dev:backend"
```

```powershell
# Start backend in new window
Start-Process powershell -ArgumentList "-NoExit", "-Command", "npm run dev:backend"

# Start frontend in current window
npm run dev:frontend
```

--------------------------------

### Mintlify Code Group Component for Cross-Platform Examples

Source: https://github.com/deploystackio/documentation/blob/main/README.md

Illustrates the use of the Mintlify CodeGroup component to display code snippets for different operating systems or environments. This example shows how to present `npm install` commands for macOS/Linux and Windows.

```mdx
<CodeGroup>
```bash macOS/Linux
npm install
```

```powershell Windows
npm install
```
</CodeGroup>
```

--------------------------------

### Verify Development Prerequisites (Bash)

Source: https://github.com/deploystackio/documentation/blob/main/general/local-setup.mdx

Verifies the installation of essential development tools like Git, Node.js, npm, and Docker. Ensures that the correct versions are installed and accessible in the system's PATH.

```bash
# Before you can install and use DeployStack locally, make sure you have:
# - Git: Version control system
# - Node.js v18+: JavaScript runtime (v18 or higher required)
# - npm v8+: Package manager (comes with Node.js)
# - Docker: For running PostgreSQL database

# Verify Installation
git --version
node --version  # Should be v18 or higher
npm --version   # Should be v8 or higher
docker --version
```

--------------------------------

### Example Startup Output Log

Source: https://github.com/deploystackio/documentation/blob/main/development/backend/global-settings.mdx

Illustrates the console output during the global settings initialization process. It shows the discovery of setting files, loading of modules, creation of groups, initialization of settings, and any skipped or missing required settings.

```text
🔄 Loading global settings definitions...
📁 Found 2 setting files: smtp, github-oauth
✅ Loaded settings module: smtp (7 settings)
✅ Loaded settings module: github-oauth (5 settings)
🎉 Loaded 2 settings modules with 12 total settings
🔄 Creating 2 setting groups...
✅ Created group: smtp (SMTP Mail Settings)
✅ Created group: github-oauth (GitHub OAuth Configuration)
🔄 Initializing 12 global settings...
✅ Created setting: smtp.host
✅ Created setting: smtp.port
✅ Created setting: smtp.username
✅ Created setting: smtp.password
⏭️  Skipped existing setting: smtp.secure
✅ Created setting: github.oauth.client_id
✅ Created setting: github.oauth.client_secret
🎉 Global settings initialization complete: 6 created, 1 skipped
⚠️  Missing required settings: smtp.host, smtp.username, smtp.password
```

--------------------------------

### Frontend Installation Initiation

Source: https://github.com/deploystackio/documentation/blob/main/development/backend/mcp-server-oauth.mdx

The frontend initiates the OAuth installation process by calling the `/api/teams/:teamId/mcp/installations/authorize` endpoint, then handles the authorization URL and listens for completion messages.

```APIDOC
## POST /api/teams/:teamId/mcp/installations/authorize

### Description
Initiates the OAuth installation flow for a specific team and MCP server. The frontend sends installation details and receives an authorization URL to redirect the user.

### Method
POST

### Endpoint
`/api/teams/:teamId/mcp/installations/authorize`

### Parameters
#### Path Parameters
- **teamId** (string) - Required - The ID of the team initiating the installation.

#### Request Body
- **server_id** (string) - Required - The ID of the MCP server to install.
- **installation_name** (string) - Required - A user-friendly name for the installation.
- **installation_type** (string) - Required - The type of installation (e.g., 'global').
- **team_config** (object) - Optional - Configuration details for the team:
  - **team_args** (array) - Array of team arguments.
  - **team_env** (object) - Environment variables for the team.
  - **team_headers** (object) - Custom headers for the team.
  - **team_url_query_params** (object) - Query parameters for the team URL.

### Request Example
```json
{
  "server_id": "notion_mcp_server",
  "installation_name": "My Notion Workspace",
  "installation_type": "global",
  "team_config": {
    "team_args": [],
    "team_env": {},
    "team_headers": {},
    "team_url_query_params": {}
  }
}
```

### Response
#### Success Response (200)
- **authorization_url** (string) - The URL to redirect the user to for OAuth authorization.
- **flow_id** (string) - An identifier for the authorization flow.

#### Response Example
```json
{
  "authorization_url": "https://oauth.example.com/auth?client_id=...",
  "flow_id": "flow_abc123"
}
```

### Frontend Handling
1. Open the `authorization_url` in a popup window.
2. Listen for `message` events from the popup.
3. Handle `oauth_success` (with `installation_id`) or `oauth_error` events.
```

--------------------------------

### Install PostgreSQL Locally (Bash)

Source: https://github.com/deploystackio/documentation/blob/main/development/backend/database/postgresql.mdx

Provides commands for installing PostgreSQL 16 on macOS using Homebrew, Ubuntu/Debian using apt, and via Docker. It also includes instructions for starting the PostgreSQL service. This is a prerequisite for local development.

```bash
# macOS (Homebrew)
brew install postgresql@16
brew services start postgresql@16

# Ubuntu/Debian
sudo apt-get install postgresql-16

# Docker
docker run -d --name postgres \
  -e POSTGRES_PASSWORD=password \
  -p 5432:5432 \
  postgres:16-alpine
```

--------------------------------

### Setup and Run Satellite Development Server

Source: https://github.com/deploystackio/documentation/blob/main/development/satellite/index.mdx

This snippet shows the bash commands to clone the satellite service repository, install dependencies, configure environment variables, and start the development server with hot reloading. It assumes you are in the 'services/satellite' directory.

```bash
cd services/satellite
npm install

cp .env.example .env
# Edit LOG_LEVEL, PORT as needed

npm run dev
# Server runs on http://localhost:3001
# API docs: http://localhost:3001/documentation
```

--------------------------------

### Frontend OAuth Installation Initiation

Source: https://github.com/deploystackio/documentation/blob/main/development/backend/mcp-server-oauth.mdx

The frontend initiates the OAuth installation process by making a POST request to the authorization endpoint. It then opens a popup window for the user to complete the OAuth flow and listens for success or error messages.

```typescript
// Frontend calls authorization endpoint
const response = await fetch('/api/teams/:teamId/mcp/installations/authorize', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    server_id: 'notion_mcp_server',
    installation_name: 'My Notion Workspace',
    installation_type: 'global',
    team_config: {
      team_args: [],
      team_env: {},
      team_headers: {},
      team_url_query_params: {}
    }
  })
});

const { authorization_url, flow_id } = await response.json();

// Frontend opens popup window
const popup = window.open(authorization_url, 'oauth', 'width=600,height=700');

// Frontend listens for completion message
window.addEventListener('message', (event) => {
  if (event.data.type === 'oauth_success') {
    console.log('Installation ID:', event.data.installation_id);
    // Refresh installations list
  } else if (event.data.type === 'oauth_error') {
    console.error('OAuth error:', event.data.error);
  }
});
```

--------------------------------

### Setup Local Satellite Development Environment (Bash)

Source: https://github.com/deploystackio/documentation/blob/main/development/satellite/registration.mdx

Shell commands to set up a local development environment for a Deploystack satellite. This includes cloning the repository, installing dependencies, configuring environment variables for identity and backend URL, and starting the satellite service.

```bash
# Clone and setup
git clone https://github.com/deploystackio/deploystack.git
cd deploystack/services/satellite
npm install

# Configure satellite identity and registration token
cp .env.example .env
echo "DEPLOYSTACK_SATELLITE_NAME=dev-satellite-001" >> .env
echo "DEPLOYSTACK_BACKEND_URL=http://localhost:3000" >> .env
echo "DEPLOYSTACK_REGISTRATION_TOKEN=your-token-here" >> .env

# Start satellite (will auto-register)
npm run dev
```

--------------------------------

### Mintlify Card Group Component for Linking Content

Source: https://github.com/deploystackio/documentation/blob/main/README.md

Demonstrates the Mintlify CardGroup component, which allows for creating visually appealing cards to link to different sections of the documentation. This example shows two cards: 'Getting Started' and 'API Reference', each with an icon and a link.

```mdx
<CardGroup cols={2}>
  <Card title="Getting Started" icon="rocket" href="/general/quick-start">
    Begin your DeployStack journey
  </Card>
  <Card title="API Reference" icon="code" href="/development/backend/api">
    Explore the API documentation
  </Card>
</CardGroup>
```

--------------------------------

### Install Project Dependencies (Bash)

Source: https://github.com/deploystackio/documentation/blob/main/general/local-setup.mdx

Installs all project dependencies for DeployStack using npm workspaces. This command ensures that all frontend and backend services have their required packages installed.

```bash
# Install dependencies for all services
npm install
```

--------------------------------

### Job Event Logging Examples (JSON)

Source: https://github.com/deploystackio/documentation/blob/main/development/satellite/background-jobs.mdx

Provides examples of structured log data for various job lifecycle events, including job start, execution start, successful completion, and errors. This format facilitates easier parsing and analysis of job activities.

```json
// Job started
{
  "operation": "job_start",
  "job_name": "process-health",
  "interval_ms": 120000,
  "interval_seconds": 120
}

// Job executing
{
  "operation": "job_execute_start",
  "job_name": "process-health",
  "execution_number": 5
}

// Job completed
{
  "operation": "job_execute_success",
  "job_name": "process-health",
  "execution_number": 5,
  "execution_time_ms": 234
}

// Job error
{
  "operation": "job_execute_error",
  "job_name": "process-health",
  "execution_number": 5,
  "error_count": 2,
  "error": "Connection timeout"
}
```

--------------------------------

### Mintlify Steps Component for Sequential Instructions

Source: https://github.com/deploystackio/documentation/blob/main/README.md

Shows how to use the Mintlify Steps component to present a sequence of instructions or a process. Each step is clearly defined with a title and descriptive text, suitable for guides and tutorials.

```mdx
<Steps>
  <Step title="Install Dependencies">
    Run `npm install` to install required packages
  </Step>
  <Step title="Configure Environment">
    Set up your environment variables
  </Step>
  <Step title="Start Development">
    Run `npm run dev` to start the development server
  </Step>
</Steps>
```

--------------------------------

### Install Python 3 and UV

Source: https://github.com/deploystackio/documentation/blob/main/self-hosted/production-satellite.mdx

Installs Python 3 and pip, followed by the UV package runner, which is used by DeployStack Satellite for Python MCP servers. The installation script for UV is downloaded and executed.

```bash
# Install Python 3
sudo apt-get install -y python3 python3-pip

# Install UV (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify installation
python3 --version  # Should show Python 3.x
uvx --version      # Should show uvx version
```

--------------------------------

### Connect and Call Tool with Python MCP Client

Source: https://github.com/deploystackio/documentation/blob/main/development/satellite/instance-router.mdx

Shows how to establish a connection to an MCP instance and invoke a tool using the Python SDK. This example includes initializing the client, setting up the transport, listing tools, and executing the 'create_issue' tool. It uses asyncio for asynchronous operations.

```python
from mcp import Client, StreamableHTTPClientTransport
import asyncio

async def main():
    # Create client
    client = Client(
        {
            "name": "python-automation",
            "version": "1.0.0"
        },
        {
            "capabilities": {}
        }
    )

    # Connect to instance
    transport = StreamableHTTPClientTransport(
        url="https://satellite.example.com/i/bold-penguin-42a3/mcp?token=ds_inst_abc123..."
    )

    await client.connect(transport)

    # List tools
    tools_response = await client.list_tools()
    print(f"Instance has {len(tools_response['tools'])} tools")

    # Call tool
    result = await client.call_tool(
        "create_issue",
        {
            "repo": "deploystackio/deploystack",
            "title": "Issue from Python",
            "body": "Created via Python script"
        }
    )

    print("Result:", result)

    # Cleanup
    await client.close()

asyncio.run(main())
```

--------------------------------

### Install Node.js 24

Source: https://github.com/deploystackio/documentation/blob/main/self-hosted/production-satellite.mdx

Installs Node.js version 24, which is required for DeployStack Satellite compatibility with the latest MCP protocol features. This involves adding the NodeSource repository and then installing Node.js using apt-get.

```bash
# Add NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo bash -

# Install Node.js
sudo apt-get install -y nodejs

# Verify installation
node --version  # Should show v24.x.x
npm --version
```

--------------------------------

### MCP Server Configuration Assembly Example

Source: https://github.com/deploystackio/documentation/blob/main/general/mcp-user-configuration.mdx

Illustrates how system, team, and personal settings are combined to create the final runtime configuration for an MCP server. It shows the precedence of personal settings over team settings and the resulting environment variables.

```text
Final Configuration = Template + Team + Your Personal Settings

Template (System):
├─ Command: "npx"
├─ Package: "@brightdata/mcp-server-web-search"
└─ System flags: "-y"

+ Team (Shared - Available to All Team Members):
├─ Team API Key: "team_shared_key_abc123"
├─ Search quota: "1000 queries/day"
└─ Content filters: "enabled"

+ Your Personal Settings (Private - Not Shared):
├─ Personal API Key: "your_private_key_xyz789" (OVERRIDES team key)
├─ Personal Rate Limit: "5000 queries/day" (OVERRIDES team quota)
├─ Default search engine: "google"
├─ Results per page: 10
└─ Cache duration: "1 hour"

= Final Runtime Configuration FOR YOU:
Command: npx -y @brightdata/mcp-server-web-search
Environment: {
  "API_KEY": "your_private_key_xyz789",  ← YOUR private key used
  "SEARCH_QUOTA": "5000",                 ← YOUR personal limit used
  "CONTENT_FILTERS": "enabled",          ← Team setting inherited
  "DEFAULT_ENGINE": "google",            ← Your preference
  "RESULTS_PER_PAGE": "10",              ← Your preference
  "CACHE_DURATION": "3600"               ← Your preference
}

= Other Team Members See DIFFERENT Configuration:
Environment: {
  "API_KEY": "team_shared_key_abc123",   ← Team key (you're using yours)
  "SEARCH_QUOTA": "1000",                 ← Team limit (you're using yours)
  "CONTENT_FILTERS": "enabled",          ← Same team setting
  ... (their own preferences)
}
```

--------------------------------

### TypeScript: Usage Example for removeServerCompletely

Source: https://github.com/deploystackio/documentation/blob/main/development/satellite/process-management.mdx

This TypeScript example demonstrates how to use the `removeServerCompletely` method to uninstall a server identified by its installation name. It shows the expected result object indicating the outcome of the cleanup operation.

```typescript
// Called when server removed from configuration
const result = await processManager.removeServerCompletely(
  'sequential-thinking-team-name-abc123'
);

// Result: { active: true, dormant: false }
// - Active process was terminated
// - No dormant config existed
```

--------------------------------

### Install Development Tools in WSL (Bash)

Source: https://github.com/deploystackio/documentation/blob/main/general/local-setup.mdx

Installs necessary development tools for Linux environments, specifically within Windows Subsystem for Linux (WSL). This includes updating package lists, installing Git, Node.js v18 via NodeSource, and Docker.

```bash
# Update package list
sudo apt update

# Install Git
sudo apt install git

# Install Node.js v18 via NodeSource
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# Verify Installation
git --version
node --version  # Should be v18 or higher
npm --version   # Should be v8 or higher
docker --version
```

--------------------------------

### Manual MCP Server Configuration Steps

Source: https://github.com/deploystackio/documentation/blob/main/general/architecture.mdx

Outlines the manual process for configuring an MCP server, involving finding documentation, installing the server, obtaining API credentials, configuring JSON settings, and debugging. This method is repeated for each team member.

```text
1. Find MCP server documentation
2. Install server individually (npm install @github/mcp)
3. Obtain API credentials from various sources
4. Configure complex JSON in VS Code settings
5. Debug configuration issues
6. Repeat for each team member
```

--------------------------------

### Install nsjail

Source: https://github.com/deploystackio/documentation/blob/main/self-hosted/production-satellite.mdx

Installs nsjail, a tool providing process isolation via Linux namespaces and cgroups, essential for secure multi-team satellite operation. This involves installing build dependencies, cloning the nsjail repository, building it, and copying the executable to the system path.

```bash
# Install build dependencies
sudo apt-get update
sudo apt-get install -y \
  autoconf \
  bison \
  flex \
  gcc \
  g++ \
  git \
  libprotobuf-dev \
  libnl-route-3-dev \
  libtool \
  make \
  pkg-config \
  protobuf-compiler

# Clone and build nsjail
cd /tmp
git clone --depth 1 https://github.com/google/nsjail.git
cd nsjail
make

# Install to system
sudo cp nsjail /usr/local/bin/
sudo chmod +x /usr/local/bin/nsjail

# Verify installation
nsjail --version

# Cleanup
cd /
rm -rf /tmp/nsjail
```

--------------------------------

### Troubleshoot Service Startup with Docker Logs and System Stats

Source: https://github.com/deploystackio/documentation/blob/main/self-hosted/quick-start.mdx

This section provides commands to diagnose why services might not be starting correctly. It includes checking container logs using `docker logs` and monitoring system resources like disk space and memory with `df -h` and `free -h`.

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

--------------------------------

### Docker Compose PostgreSQL Integration

Source: https://github.com/deploystackio/documentation/blob/main/self-hosted/database-setup.mdx

This command starts the Docker Compose environment, which includes a pre-configured PostgreSQL instance for DeployStack. No manual database setup is required when using this option.

```bash
# PostgreSQL is automatically included
docker-compose up -d
```

--------------------------------

### Configuration Assembly Example

Source: https://github.com/deploystackio/documentation/blob/main/general/mcp-configuration.mdx

Illustrates the merging of global, team, and user configurations into a final runtime configuration. It shows how arguments and environment variables from different tiers are combined, with secrets automatically decrypted for runtime.

```json
{
  "args": ["-y", "@modelcontextprotocol/server-filesystem"],
  "env": {"PROTOCOL_VERSION": "1.0"}
}
```

```json
{
  "args": [],
  "env": {"SHARED_API_KEY": "••••• (encrypted secret)"}
}
```

```json
{
  "args": ["/Users/alice/Development", "/Users/alice/Projects"],
  "env": {"DEBUG": "true"}
}
```

```json
{
  "command": "npx",
  "args": [
    "-y", 
    "@modelcontextprotocol/server-filesystem",
    "/Users/alice/Development", 
    "/Users/alice/Projects"
  ],
  "env": {
    "PROTOCOL_VERSION": "1.0",
    "SHARED_API_KEY": "decrypted-secret-for-runtime", 
    "DEBUG": "true"
  }
}
```

--------------------------------

### Create Backend Environment File (Bash)

Source: https://github.com/deploystackio/documentation/blob/main/general/local-setup.mdx

Copies the example backend environment file to a new file named `.env`. This file will be used to configure backend-specific settings, including encryption secrets and database credentials.

```bash
# Create backend .env file
cp services/backend/.env.example services/backend/.env
```

--------------------------------

### Call list_mcp_resources Tool (JSON Example)

Source: https://github.com/deploystackio/documentation/blob/main/development/satellite/hierarchical-router.mdx

An example JSON request to call the `list_mcp_resources` tool using the `tools/call` method. This demonstrates the structure for invoking a tool with no specific arguments.

```json
{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "tools/call",
  "params": {
    "name": "list_mcp_resources",
    "arguments": {}
  }
}
```

--------------------------------

### Start Backend and Frontend Servers (Separate Terminals)

Source: https://github.com/deploystackio/documentation/blob/main/general/local-setup.mdx

This method involves running the backend and frontend development servers in two distinct terminal windows. It is recommended for better visibility of logs from each service. It uses npm scripts to initiate the development servers.

```bash
# Terminal 1: Start backend server
npm run dev:backend

# Terminal 2: Start frontend server (in a new terminal)
npm run dev:frontend
```

--------------------------------

### GET /api/items

Source: https://github.com/deploystackio/documentation/blob/main/development/backend/api/pagination.mdx

Retrieve a list of items with support for filtering by category and status, along with standard pagination.

```APIDOC
## GET /api/items

### Description
Retrieve items with pagination support. Supports filtering by category and status.

### Method
GET

### Endpoint
/api/items

### Parameters
#### Query Parameters
- **category** (string) - Optional - Filter by category.
- **status** (string) - Optional - Filter by status. Allowed values: 'active', 'inactive'.
- **limit** (string) - Optional - Maximum number of items to return (1-100, default: 20). Must be a positive integer.
- **offset** (string) - Optional - Number of items to skip (≥0, default: 0). Must be a non-negative integer.

### Request Example
```json
{
  "example": "GET /api/items?category=electronics&limit=10&offset=0"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the list of items and pagination details.
  - **items** (array) - An array of item objects.
    - **id** (string) - The unique identifier of the item.
    - **name** (string) - The name of the item.
    - **... other properties**
  - **pagination** (object) - Contains pagination information.
    - **total** (number) - The total number of items available.
    - **limit** (number) - The limit applied to the current request.
    - **offset** (number) - The offset applied to the current request.
    - **has_more** (boolean) - Indicates if there are more items available beyond the current response.

#### Error Response (400)
- **success** (boolean) - Always false.
- **error** (string) - A message describing the error.

#### Response Example (Success)
```json
{
  "example": {
    "success": true,
    "data": {
      "items": [
        {
          "id": "item-123",
          "name": "Example Item",
          "category": "electronics",
          "status": "active"
        }
      ],
      "pagination": {
        "total": 50,
        "limit": 10,
        "offset": 0,
        "has_more": true
      }
    }
  }
}
```

#### Response Example (Error)
```json
{
  "example": {
    "success": false,
    "error": "Invalid limit parameter"
  }
}
```
```

--------------------------------

### Global Teardown Script for Backend E2E Tests

Source: https://github.com/deploystackio/documentation/blob/main/development/backend/test.mdx

A TypeScript script executed after all E2E tests have completed. Its primary function is to stop the backend server that was started during the global setup phase, ensuring a clean exit.

```typescript
import { execSync } from 'child_process';

module.exports = async function globalTeardown() {
  // Stop the backend server (example, actual implementation might differ)
  console.log('Stopping backend server after E2E tests...');
  // Example: This would involve finding and killing the server process started in globalSetup
  // For simplicity, a placeholder is used here.
  // In a real scenario, you might use a process manager or store the server PID.
};

```

--------------------------------

### Instance Token Example

Source: https://github.com/deploystackio/documentation/blob/main/development/satellite/instance-router.mdx

Provides a concrete example of a valid instance token.

```text
ds_inst_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456
```

--------------------------------

### Manual API Specification Generation with Running Server

Source: https://github.com/deploystackio/documentation/blob/main/development/backend/api/index.mdx

Demonstrates the manual process of generating API specifications by first starting the development server and then running the commands for JSON and YAML specification generation in separate terminals.

```bash
# Terminal 1: Start the server
cd services/backend
npm run dev

# Terminal 2: Generate specifications
npm run api:spec:json
npm run api:spec:yaml
```

--------------------------------

### Example Request Log Structure (JSON)

Source: https://github.com/deploystackio/documentation/blob/main/development/satellite/log-capture.mdx

An example of the JSON structure for buffered request logs. It includes installation and team identifiers, along with a list of individual request entries, each detailing tool execution parameters, response, timing, and status.

```json
{
  "installation_id": "inst_abc123",
  "team_id": "team_xyz",
  "requests": [
    {
      "user_id": "user_xyz",
      "tool_name": "github:list-repos",
      "tool_params": {
        "owner": "deploystackio"
      },
      "tool_response": {
        "repos": ["deploystack", "mcp-server"],
        "total": 2
      },
      "response_time_ms": 234,
      "success": true,
      "timestamp": "2025-01-15T10:30:00.000Z"
    },
    {
      "user_id": "user_xyz",
      "tool_name": "slack:send-message",
      "tool_params": {
        "channel": "#general",
        "text": "Deploy complete"
      },
      "response_time_ms": 456,
      "success": false,
      "error_message": "Channel not found",
      "timestamp": "2025-01-15T10:30:05.000Z"
    }
  ]
}
```