Sliplane API Management Guide

Generated: 2025-01-12 UTC
Purpose: Guide for managing Sasha deployments on Sliplane - optimized for Claude CLI usage

---

Decision Matrix for Claude

When user requests deployment operations, use this decision tree:

Deployment Request Decision Tree

User wants to deploy/manage Sliplane
├── New client deployment
│   ├── Check: clients/{NAME}/config.json exists?
│   ├── Action: ./scripts/deploy-with-api.sh {NAME}
│   └── Verify: ./scripts/check-status.sh {NAME}
├── Update existing client
│   ├── Only env vars → ./scripts/update-config.sh {NAME}
│   └── Include volumes → ./scripts/update-config.sh {NAME} --volumes
├── Check status
│   └── Action: ./scripts/check-status.sh {NAME}
└── Debug/Test
    ├── Test API → ./scripts/test-api.sh
    └── Check all services → See "Debugging Commands" section

---

Pre-execution Checklist for Claude

ALWAYS run these checks before any deployment command:

# 1. Verify location
pwd  # Must be in /Users/lindsaysmith/Documents/lambda1.nosync/sasha/client-management/
# If not there: cd /Users/lindsaysmith/Documents/lambda1.nosync/sasha/client-management/

# 2. Check credentials exist
[ -f .env ] && echo "✓ .env exists" || echo "✗ Run ./setup-api.sh first"

# 3. For specific client operations, validate config
[ -f clients/{CLIENT_NAME}/config.json ] && \
  jq '.' clients/{CLIENT_NAME}/config.json >/dev/null 2>&1 && \
  echo "✓ Valid config" || echo "✗ Invalid or missing config"

# 4. Test API connection (optional but recommended)
./scripts/test-api.sh  # Should return service list or connection success

---

State Detection Patterns

Check if Service Exists

# Method 1: Direct check
./scripts/check-status.sh CLIENT_NAME
# Exit code 0 = exists, non-zero = doesn't exist
# Look for "Service ID: service_" in output to confirm

# Method 2: Parse for specific info
./scripts/check-status.sh CLIENT_NAME 2>/dev/null | grep -q "Service ID:" && \
  echo "Service exists" || echo "Service not found"

Get Current Configuration

# Extract current environment and volumes
./scripts/check-status.sh CLIENT_NAME | grep -E "(📁 Volumes:|PORT|COMPANY_NAME|Status:)"

# Check if volumes are already configured
./scripts/check-status.sh CLIENT_NAME | grep -A5 "📁 Volumes:" | grep -E "(nodejs-home|sasha-data)"

---

Command Reference with Context

Deploy New Client

When to use: User asks to "deploy", "create", "set up", or "launch" a new client
When NOT to use: Service already exists (always check first)
Prerequisites: Valid clients/{CLIENT_NAME}/config.json file

# ALWAYS start with dry-run
./scripts/deploy-with-api.sh CLIENT_NAME --dry-run

# Expected dry-run output includes:
# "🔍 DRY-RUN MODE - No changes will be made"
# "[DRY-RUN] Would create service: CLIENT_NAME"
# "[DRY-RUN] Would configure 2 volumes"

# If dry-run successful, proceed with actual deployment
./scripts/deploy-with-api.sh CLIENT_NAME

# Expected success output:
# "✓ Created service: service_xxxxx" OR "✓ Found existing service"
# "✓ nodejs-home (5Gi)" and "✓ sasha-data (10Mi)" 
# "✓ Environment variables configured"
# "✅ Deployment started!"

# Always verify after deployment
./scripts/check-status.sh CLIENT_NAME

Common errors and fixes:

• "❌ Client 'X' not found" → Create clients/X/config.json first
• "❌ Authentication failed" → Run ./setup-api.sh to update credentials
• "❌ Missing required environment variables" → Check .env file exists

Update Existing Client

When to use: User wants to change configuration, update environment variables
When NOT to use: For new deployments (use deploy-with-api.sh instead)

# Update environment variables only (SAFE - recommended)
./scripts/update-config.sh CLIENT_NAME --dry-run  # Preview first
./scripts/update-config.sh CLIENT_NAME             # Apply changes

# Update including volumes (CAUTION - rarely needed)
./scripts/update-config.sh CLIENT_NAME --volumes --dry-run  # Preview first
./scripts/update-config.sh CLIENT_NAME --volumes            # Apply if safe

# Expected output:
# "✓ Found service: service_xxxxx"
# "✓ Environment variables updated"
# "✅ Configuration updated!"

Check Status

When to use: Verify deployment, check service health, get current configuration

./scripts/check-status.sh CLIENT_NAME

# Expected output includes:
# "⚠️ Status: live" (or other status)
# "📦 Service ID: service_xxxxx"
# "🌐 URL: https://xxxxx.sliplane.app"
# "📁 Volumes:" (lists mounted volumes)

---

Common Operation Patterns

Pattern: Complete New Client Deployment

# 1. Create client directory and config
mkdir -p clients/newclient
cat > clients/newclient/config.json <<'EOF'
{
  "client_id": "newclient",
  "client_name": "New Client Company",
  "deployment": {
    "docker_hub": {
      "repository": "linzoid/sasha-studio"
    }
  },
  "environment": {
    "NODE_ENV": "production",
    "PORT": "3005",
    "SESSION_SECRET": "GENERATE_ON_DEPLOY",
    "JWT_SECRET": "GENERATE_ON_DEPLOY",
    "COMPANY_NAME": "New Client Company"
  }
}
EOF

# 2. Validate JSON syntax
jq '.' clients/newclient/config.json

# 3. Dry-run deployment
./scripts/deploy-with-api.sh newclient --dry-run

# 4. Deploy if dry-run successful
./scripts/deploy-with-api.sh newclient

# 5. Verify deployment
./scripts/check-status.sh newclient

Pattern: Safe Configuration Update

# 1. Check current state
./scripts/check-status.sh CLIENT_NAME

# 2. Edit configuration
vi clients/CLIENT_NAME/config.json  # Or use preferred editor

# 3. Preview changes
./scripts/update-config.sh CLIENT_NAME --dry-run

# 4. Apply changes
./scripts/update-config.sh CLIENT_NAME

# 5. Trigger redeployment
./scripts/deploy-with-api.sh CLIENT_NAME

---

Error Recovery Patterns

Deployment Failed

# Step 1: Diagnose the issue
./scripts/check-status.sh CLIENT_NAME
./scripts/test-api.sh  # Verify API connectivity

# Step 2: If service exists but deployment failed
./scripts/update-config.sh CLIENT_NAME      # Update configuration
./scripts/deploy-with-api.sh CLIENT_NAME    # Retry deployment

# Step 3: If volumes are causing issues (rare)
./scripts/update-config.sh CLIENT_NAME --volumes --dry-run  # Preview
# Only proceed if dry-run shows expected changes

Service Not Responding

# 1. Check service status
./scripts/check-status.sh CLIENT_NAME | grep "Status:"

# 2. Verify URL is accessible
URL=$(./scripts/check-status.sh CLIENT_NAME | grep "🌐 URL:" | awk '{print $3}')
curl -I "$URL" 2>/dev/null | head -1

# 3. Trigger fresh deployment
./scripts/deploy-with-api.sh CLIENT_NAME

---

CRITICAL WARNINGS - Never Do These

1. NEVER delete or modify volumes without explicit user confirmation
2. NEVER run --volumes flag on existing production services without dry-run
3. NEVER modify .env credentials during active deployments
4. NEVER assume service name matches client name (always verify)
5. NEVER skip dry-run for first-time operations

---

🗄️ Volume Architecture

IMPORTANT: Volumes are SHARED across all clients on the same server

Volume	Mount Path	Size	Contents
nodejs-home	/home/nodejs	5Gi	ALL user data, configs, workspaces
sasha-data	/app/data	10Mi	SQLite database

Path Mappings Set by Deployment

HOME=/home/nodejs
DOCS_PATH=/home/nodejs/workspace/docs
UPLOAD_FOLDER=/home/nodejs/uploads
WORKSPACES_PATH=/home/nodejs/workspaces
CLAUDE_PROJECTS_PATH=/home/nodejs/claude-projects
CLAUDE_CONFIG_PATH=/home/nodejs/.claude-config.json
CONFIG_PATH=/home/nodejs/config

---

Available Scripts Reference

Script	Purpose	Key Options
setup-api.sh	Initial credential setup	Interactive only
scripts/deploy-with-api.sh	Deploy/update service	--dry-run
scripts/update-config.sh	Update configuration	--dry-run, --volumes
scripts/check-status.sh	Check service status	None
scripts/test-api.sh	Test API connection	None

---

Debugging Commands

# List all services in project
source .env && \
curl -s -X GET "https://ctrl.sliplane.io/v0/projects/$SLIPLANE_PROJECT_ID/services" \
  -H "Authorization: Bearer $SLIPLANE_API_TOKEN" \
  -H "X-Organization-ID: $SLIPLANE_ORG_ID" | jq '.[] | {name, status, id}'

# Get detailed service info
source .env && \
curl -s -X GET "https://ctrl.sliplane.io/v0/projects/$SLIPLANE_PROJECT_ID/services" \
  -H "Authorization: Bearer $SLIPLANE_API_TOKEN" \
  -H "X-Organization-ID: $SLIPLANE_ORG_ID" | \
  jq '.[] | select(.name=="CLIENT_NAME")'

# Check environment variables for a service
./scripts/check-status.sh CLIENT_NAME | sed -n '/env:/,/healthcheck:/p'

---

File Structure Reference

client-management/
├── .env                        # REQUIRED: API credentials (never commit)
├── .env.example               # Template for credentials
├── setup-api.sh               # Run first to configure credentials
├── README-SLIPLANE-API.md    # Quick command reference
├── lib/
│   └── sliplane-api.sh       # Core functions (don't run directly)
├── scripts/
│   ├── deploy-with-api.sh    # Main deployment tool
│   ├── update-config.sh      # Configuration updater
│   ├── check-status.sh       # Status checker
│   └── test-api.sh           # Connection tester
└── clients/                   # Client configurations
    ├── template/              # Copy for new clients
    │   └── config.json
    └── {CLIENT_NAME}/         # Per-client directory
        └── config.json        # REQUIRED: Client configuration

---

Related Documentation

• Sliplane Volume Configuration - Detailed volume architecture
• Sliplane Deployment Strategy - Overall deployment approach
• README-SLIPLANE-API.md - Quick reference

---

Client Config Template

When creating a new clients/{NAME}/config.json:

{
  "client_id": "unique_identifier",
  "client_name": "Human Readable Name",
  "deployment": {
    "docker_hub": {
      "repository": "linzoid/sasha-studio"
    }
  },
  "environment": {
    "NODE_ENV": "production",
    "PORT": "3005",
    "SESSION_SECRET": "GENERATE_ON_DEPLOY",
    "JWT_SECRET": "GENERATE_ON_DEPLOY",
    "COMPANY_NAME": "Human Readable Name",
    "CUSTOM_VAR": "optional_custom_value"
  }
}

Notes:

• SESSION_SECRET and JWT_SECRET with value "GENERATE_ON_DEPLOY" auto-generate secure values
• Additional environment variables can be added as needed
• All values must be strings (quote numbers like "3005")

---

This guide is optimized for Claude CLI to effectively manage Sliplane deployments. Always verify state before operations and use dry-run for safety.