Add OpenClaw setup documentation and utilities

- SETUP.md: Complete deployment guide with WebSocket configuration - portainer-setup.sh: Automated Portainer stack creation script - fix-permissions.sh: Storage directory permission fixer - .gitignore: Ensure .credentials file is not committed Note: WebSocket support must be enabled in nginx-proxy-manager for OpenClaw to work.
2026-02-08 21:45:31 +00:00
parent d66fc86287
commit 68e3f673e8
4 changed files with 271 additions and 0 deletions
@@ -0,0 +1 @@
+.credentials
@@ -0,0 +1,122 @@
+# OpenClaw Setup Guide
+
+## Prerequisites
+
+1. **Create storage directories:**
+   ```bash
+   sudo mkdir -p /srv/openclaw/config /srv/openclaw/workspace
+   sudo chown -R 1000:1000 /srv/openclaw
+   ```
+
+2. **Create .env file on host:**
+
+   The `.env` file is already created locally at `openclaw/.env` with a generated token. You need to copy it to the deployment location:
+
+   ```bash
+   # Copy .env to the openclaw directory where Portainer will use it
+   # Option 1: If running locally
+   cp openclaw/.env /path/to/portainer/stack/openclaw/.env
+
+   # Option 2: Add environment variables directly in Portainer stack
+   # (see Portainer setup below)
+   ```
+
+## Portainer Stack Setup
+
+### Method 1: Via Portainer Web UI
+
+1. Go to Portainer → Stacks → Add Stack
+2. Choose "Git Repository"
+3. Fill in:
+   - **Name:** openclaw
+   - **Repository URL:** `https://gitea.kolpacksoftware.com/homelab/docker-infrastructure.git`
+   - **Reference:** `refs/heads/main`
+   - **Compose path:** `openclaw/docker-compose.yml`
+   - **Auto update:** Enabled (5m interval recommended)
+4. Add environment variables:
+   - `OPENCLAW_GATEWAY_TOKEN`: `27d4e63adce6c8f7c5396e8ca3f9ec5e6ff590077247fb11da03a8684ee3c711`
+5. Deploy the stack
+
+### Method 2: Via Portainer API
+
+```bash
+# Set your Portainer API token
+export PORTAINER_TOKEN="your-token-here"
+
+# Create the stack (Docker Compose mode)
+curl -k -X POST "https://localhost:9443/api/stacks/create/standalone/repository" \
+  -H "X-API-Key: $PORTAINER_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "openclaw",
+    "endpointId": 2,
+    "repositoryURL": "https://gitea.kolpacksoftware.com/homelab/docker-infrastructure.git",
+    "repositoryReferenceName": "refs/heads/main",
+    "composeFile": "openclaw/docker-compose.yml",
+    "repositoryAuthentication": false,
+    "autoUpdate": {
+      "interval": "5m"
+    },
+    "env": [
+      {
+        "name": "OPENCLAW_GATEWAY_TOKEN",
+        "value": "27d4e63adce6c8f7c5396e8ca3f9ec5e6ff590077247fb11da03a8684ee3c711"
+      }
+    ]
+  }'
+```
+
+## Nginx Proxy Manager Configuration
+
+Set up a proxy host for:
+- **Domain:** openclaw.kolpacksoftware.com
+- **Forward Hostname / IP:** openclaw (container name)
+- **Forward Port:** 18789
+- **⚠️ WebSocket Support:** Enable "WebSocket Support" toggle (REQUIRED - OpenClaw uses WebSocket protocol)
+- **SSL:** Request Let's Encrypt certificate
+- **Access List:** Create/use "Private Network Only" to restrict to 192.168.1.0/24
+
+## Ollama Integration
+
+Make sure Ollama is running and has models pulled:
+
+```bash
+# Check Ollama status
+docker ps | grep ollama
+
+# Pull a model if needed (from ollama directory)
+docker exec -it ollama ollama pull llama3
+# or
+docker exec -it ollama ollama pull mistral
+```
+
+## Running the Onboarding Wizard
+
+After the stack is deployed, run the onboarding wizard:
+
+```bash
+docker exec -it openclaw npx openclaw onboard
+```
+
+During onboarding:
+1. Select **Ollama** as your model provider
+2. Enter Ollama base URL: `http://ollama:11434` (since they're on the same Docker network)
+3. Select which model to use (e.g., llama3, mistral)
+4. Configure any messaging channels you want (optional)
+
+## Accessing OpenClaw
+
+- **Control UI:** https://openclaw.kolpacksoftware.com
+- **Gateway Token:** `27d4e63adce6c8f7c5396e8ca3f9ec5e6ff590077247fb11da03a8684ee3c711`
+
+## Troubleshooting
+
+Check logs:
+```bash
+docker logs openclaw -f
+```
+
+Check if OpenClaw can reach Ollama:
+```bash
+docker exec -it openclaw curl http://ollama:11434
+```
@@ -0,0 +1,12 @@
+#!/bin/bash
+# Fix OpenClaw storage permissions
+
+echo "Creating OpenClaw storage directories..."
+sudo mkdir -p /srv/openclaw/config /srv/openclaw/workspace
+sudo chown -R 1000:1000 /srv/openclaw
+sudo chmod -R 755 /srv/openclaw
+
+echo "Restarting OpenClaw container..."
+docker restart openclaw
+
+echo "Done! Check logs with: docker logs openclaw -f"
@@ -0,0 +1,136 @@
+#!/bin/bash
+set -e
+
+# Portainer Stack Setup Script for OpenClaw
+# Following the git-linked migration plan
+
+# Load credentials if available
+if [ -f "../.credentials" ]; then
+    source ../.credentials
+    echo "Loaded credentials from .credentials file"
+fi
+
+# Configuration
+SERVICE_NAME="openclaw"
+COMPOSE_FILE="openclaw/docker-compose.yml"
+REPO_URL="${GITEA_REPO_URL:-https://gitea.kolpacksoftware.com/homelab/docker-infrastructure.git}"
+ENDPOINT_ID="${PORTAINER_ENDPOINT_ID:-2}"
+
+# Check required environment variables
+if [ -z "$PORTAINER_API_TOKEN" ]; then
+    echo "Error: PORTAINER_API_TOKEN not set"
+    echo "Get token from: Portainer UI → User Settings → Access Tokens"
+    echo "Then run: export PORTAINER_API_TOKEN='ptr_...'"
+    exit 1
+fi
+
+if [ -z "$GITEA_TOKEN" ]; then
+    echo "Error: GITEA_TOKEN not set"
+    echo "Get token from: Gitea → Settings → Applications → Generate New Token"
+    echo "Then run: export GITEA_TOKEN='...'"
+    exit 1
+fi
+
+if [ -z "$GITEA_USER" ]; then
+    echo "Error: GITEA_USER not set"
+    echo "Then run: export GITEA_USER='your-username'"
+    exit 1
+fi
+
+# Gateway token from .env file
+OPENCLAW_TOKEN=$(grep OPENCLAW_GATEWAY_TOKEN .env | cut -d'=' -f2)
+if [ -z "$OPENCLAW_TOKEN" ]; then
+    echo "Error: OPENCLAW_GATEWAY_TOKEN not found in .env file"
+    exit 1
+fi
+
+echo "=== Portainer Stack Setup for $SERVICE_NAME ==="
+echo ""
+
+# Step 1: Check for existing stack
+echo "Step 1: Checking for existing stack..."
+EXISTING_STACK=$(curl -s "https://localhost:9443/api/stacks" \
+  -H "X-API-Key: $PORTAINER_API_TOKEN" \
+  --insecure | grep -o "\"Id\":[0-9]*,\"Name\":\"$SERVICE_NAME\"" || true)
+
+if [ -n "$EXISTING_STACK" ]; then
+    STACK_ID=$(echo "$EXISTING_STACK" | grep -o "[0-9]*")
+    echo "Found existing stack with ID: $STACK_ID"
+
+    read -p "Delete existing stack and recreate? (y/n) " -n 1 -r
+    echo
+    if [[ $REPLY =~ ^[Yy]$ ]]; then
+        echo "Deleting stack $STACK_ID..."
+        curl -X DELETE "https://localhost:9443/api/stacks/$STACK_ID?endpointId=$ENDPOINT_ID" \
+          -H "X-API-Key: $PORTAINER_API_TOKEN" \
+          --insecure
+        echo "Stack deleted"
+        sleep 2
+    else
+        echo "Aborted"
+        exit 0
+    fi
+else
+    echo "No existing stack found"
+fi
+
+# Step 2: Create git-linked stack
+echo ""
+echo "Step 2: Creating git-linked stack..."
+RESPONSE=$(curl -X POST "https://localhost:9443/api/stacks/create/standalone/repository?endpointId=$ENDPOINT_ID" \
+  -H "X-API-Key: $PORTAINER_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  --insecure \
+  -d '{
+    "name": "'"$SERVICE_NAME"'",
+    "repositoryURL": "'"$REPO_URL"'",
+    "repositoryReferenceName": "refs/heads/main",
+    "composeFile": "'"$COMPOSE_FILE"'",
+    "repositoryAuthentication": true,
+    "repositoryUsername": "'"$GITEA_USER"'",
+    "repositoryPassword": "'"$GITEA_TOKEN"'",
+    "autoUpdate": {
+      "interval": "5m"
+    },
+    "env": [
+      {
+        "name": "OPENCLAW_GATEWAY_TOKEN",
+        "value": "'"$OPENCLAW_TOKEN"'"
+      }
+    ]
+  }')
+
+if echo "$RESPONSE" | grep -q '"Id"'; then
+    NEW_STACK_ID=$(echo "$RESPONSE" | grep -o '"Id":[0-9]*' | head -1 | cut -d':' -f2)
+    echo "✓ Stack created successfully with ID: $NEW_STACK_ID"
+else
+    echo "✗ Failed to create stack"
+    echo "Response: $RESPONSE"
+    exit 1
+fi
+
+# Step 3: Verify
+echo ""
+echo "Step 3: Verifying deployment..."
+sleep 5
+
+if docker ps | grep -q "$SERVICE_NAME"; then
+    echo "✓ Container is running"
+else
+    echo "⚠ Container not found yet, check Portainer UI"
+fi
+
+echo ""
+echo "=== Setup Complete ==="
+echo "Next steps:"
+echo "1. Configure nginx-proxy-manager:"
+echo "   - Domain: openclaw.kolpacksoftware.com"
+echo "   - Forward to: openclaw:18789"
+echo "   - Add SSL certificate"
+echo "   - Set access list to private network"
+echo ""
+echo "2. Run onboarding wizard:"
+echo "   docker exec -it openclaw npx openclaw onboard"
+echo ""
+echo "3. Access UI at: https://openclaw.kolpacksoftware.com"
+echo "   Gateway token: $OPENCLAW_TOKEN"