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,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
+```