openclaw/docs/install/testing-guide.md

summary	read_when
Step-by-step testing guide for unified installer across different platforms and modes	You want to validate the unified installer You need to test deployment scenarios You're preparing for production deployment

Unified Installer Testing Guide

This guide provides detailed test scenarios for validating the unified installer (scripts/init.sh) across different platforms and deployment modes.

Test Environment Requirements

Ubuntu/Debian Test Environment

Recommended Setup:

• Fresh Ubuntu 22.04 LTS or Debian 12 VM/container
• Minimum 2GB RAM, 2 vCPU
• Root/sudo access
• Public IP or domain name (for gateway mode with real TLS)

Quick VM Setup Options:

# Option 1: Multipass (macOS/Linux/Windows)
multipass launch --name moltbot-test --cpus 2 --memory 2G --disk 10G 22.04
multipass shell moltbot-test

# Option 2: Docker (for testing, not production)
docker run -it --rm -p 80:80 -p 443:443 -p 18789:18789 ubuntu:22.04 bash
apt-get update && apt-get install -y sudo curl

# Option 3: Cloud provider (DigitalOcean, Linode, etc.)
# Create a $5/month droplet with Ubuntu 22.04

macOS Test Environment

Requirements:

• macOS 12+ (Monterey or later)
• Homebrew installed
• Terminal access

Homebrew Installation (if needed):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Test Scenario 1: Ubuntu/Debian Gateway Mode (Caddy)

Prerequisites

1. Fresh Ubuntu/Debian system
2. Domain name pointing to the server's IP
3. Ports 80/443 accessible from the internet

Test Steps

Step 1: Download the Installer

# SSH into your Ubuntu/Debian server
ssh user@your-server-ip

# Clone the repository (or download the script)
git clone https://github.com/cloud-neutral-toolkit/clawdbot.svc.plus.git
cd clawdbot.svc.plus

# Or download the script directly
# curl -fsSL https://raw.githubusercontent.com/cloud-neutral-toolkit/clawdbot.svc.plus/main/scripts/init.sh -o init.sh
# chmod +x init.sh

Step 2: Run the Installer

# Replace with your actual domain
DOMAIN="moltbot.example.com"

# Run installer in gateway mode with Caddy (default)
sudo ./scripts/init.sh "$DOMAIN"

Step 3: Monitor Installation

Expected Output:

==> Moltbot Installer
    Mode: gateway
    Domain: moltbot.example.com
    OS: linux (ubuntu)
    Proxy: caddy

[Installing packages...]
[Installing Node.js 24...]
[Installing pnpm...]
[Configuring firewall...]
[Installing Moltbot...]
[Configuring Moltbot...]
[Configuring Caddy...]
[Running health checks...]

✅ Done.

Gateway is listening on http://127.0.0.1:18789 and proxied via https://moltbot.example.com.
Access control and TLS are handled by CADDY.

Step 4: Verify Installation

Check Services:

# Check Caddy status
sudo systemctl status caddy

# Check Moltbot status
systemctl --user status clawdbot-gateway

# Check Node.js version
node --version  # Should be v24.x.x

Check Firewall:

sudo ufw status verbose

# Expected output:
# Status: active
# To                         Action      From
# --                         ------      ----
# 22/tcp                     ALLOW       Anywhere
# 80/tcp                     ALLOW       Anywhere
# 443/tcp                    ALLOW       Anywhere
# 18789/tcp                  ALLOW       Anywhere

Check Caddy Configuration:

cat /etc/caddy/Caddyfile

# Expected output:
# moltbot.example.com {
#   reverse_proxy 127.0.0.1:18789
# }

Test Local Gateway:

curl -I http://127.0.0.1:18789

# Expected: HTTP/1.1 200 OK or 302 redirect

Test Public HTTPS:

curl -I https://moltbot.example.com

# Expected: HTTP/2 200 OK (with valid TLS certificate)

Check TLS Certificate:

echo | openssl s_client -connect moltbot.example.com:443 -servername moltbot.example.com 2>/dev/null | openssl x509 -noout -dates

# Expected output showing valid certificate dates

Step 5: Test Moltbot Functionality

Access Web Interface:

# Open in browser
https://moltbot.example.com

Check Logs:

# Moltbot logs
journalctl --user -u clawdbot-gateway -n 50 --no-pager

# Caddy logs
sudo journalctl -u caddy -n 50 --no-pager

Expected Results

✅ Success Criteria:

• Caddy service running and enabled
• Moltbot gateway service running
• Node.js 24+ installed
• UFW firewall configured with correct rules
• TLS certificate obtained automatically
• HTTPS endpoint accessible from public internet
• HTTP redirects to HTTPS
• Moltbot web interface loads successfully

Troubleshooting

Issue: TLS certificate not obtained

Solution:

# Check Caddy logs for ACME errors
sudo journalctl -u caddy -f

# Verify DNS is correct
dig +short moltbot.example.com

# Manually trigger certificate
sudo systemctl restart caddy

Issue: Firewall blocking access

Solution:

# Check UFW status
sudo ufw status verbose

# Manually allow ports if needed
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw reload

---

Test Scenario 2: Ubuntu/Debian Gateway Mode (Nginx)

Prerequisites

Same as Scenario 1, plus:

• Email address for Certbot notifications

Test Steps

Step 1: Download the Installer

Same as Scenario 1.

Step 2: Run the Installer with Nginx

DOMAIN="moltbot.example.com"
EMAIL="admin@example.com"

# Run installer with Nginx proxy
PROXY=nginx CERTBOT_EMAIL="$EMAIL" sudo ./scripts/init.sh "$DOMAIN"

Step 3: Monitor Installation

Expected Output:

==> Moltbot Installer
    Mode: gateway
    Domain: moltbot.example.com
    OS: linux (ubuntu)
    Proxy: nginx

[Installing packages including nginx, certbot...]
[Installing Node.js 24...]
[Installing pnpm...]
[Configuring firewall...]
[Installing Moltbot...]
[Configuring Moltbot...]
[Configuring Nginx...]
[Running Certbot...]

Saving debug log to /var/log/letsencrypt/letsencrypt.log
Requesting a certificate for moltbot.example.com
Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/moltbot.example.com/fullchain.pem
Key is saved at:         /etc/letsencrypt/live/moltbot.example.com/privkey.pem

✅ Done.

Gateway is listening on http://127.0.0.1:18789 and proxied via https://moltbot.example.com.
Access control and TLS are handled by NGINX.

Step 4: Verify Installation

Check Services:

# Check Nginx status
sudo systemctl status nginx

# Check Moltbot status
systemctl --user status clawdbot-gateway

Check Nginx Configuration:

cat /etc/nginx/sites-available/clawdbot-moltbot.example.com.conf

# Verify it's enabled
ls -l /etc/nginx/sites-enabled/

Test Nginx Configuration:

sudo nginx -t

# Expected: syntax is ok, test is successful

Check Certbot Certificate:

sudo certbot certificates

# Expected output showing certificate for moltbot.example.com

Test HTTPS:

curl -I https://moltbot.example.com

# Expected: HTTP/1.1 200 OK (or 302)

Test HTTP to HTTPS Redirect:

curl -I http://moltbot.example.com

# Expected: HTTP/1.1 301 Moved Permanently
# Location: https://moltbot.example.com/

Step 5: Test Certificate Auto-Renewal

# Dry-run renewal
sudo certbot renew --dry-run

# Expected: Congratulations, all simulated renewals succeeded

Expected Results

✅ Success Criteria:

• Nginx service running and enabled
• Moltbot gateway service running
• Certbot certificate obtained successfully
• HTTP to HTTPS redirect working
• Certificate auto-renewal configured
• Nginx configuration valid
• Public HTTPS endpoint accessible

Troubleshooting

Issue: Certbot fails with "Connection refused"

Solution:

# Ensure Nginx is serving HTTP first
curl -I http://moltbot.example.com

# Check Nginx error logs
sudo tail -f /var/log/nginx/error.log

# Manually run Certbot with verbose output
sudo certbot --nginx -d moltbot.example.com --email admin@example.com --agree-tos -v

Issue: Nginx configuration error

Solution:

# Test configuration
sudo nginx -t

# Check syntax errors in config file
sudo cat /etc/nginx/sites-available/clawdbot-moltbot.example.com.conf

# Reload Nginx
sudo systemctl reload nginx

---

Test Scenario 3: macOS Node Mode

Prerequisites

• macOS 12+ (Monterey or later)
• Homebrew installed
• Terminal access
• No domain required (local deployment)

Test Steps

Step 1: Download the Installer

# Clone the repository
git clone https://github.com/cloud-neutral-toolkit/clawdbot.svc.plus.git
cd clawdbot.svc.plus

# Or download the script
# curl -fsSL https://raw.githubusercontent.com/cloud-neutral-toolkit/clawdbot.svc.plus/main/scripts/init.sh -o init.sh
# chmod +x init.sh

Step 2: Run the Installer in Node Mode

# Run installer in node mode (no proxy)
MODE=node ./scripts/init.sh localhost

Step 3: Monitor Installation

Expected Output:

==> Moltbot Installer
    Mode: node
    Domain: localhost
    OS: darwin (N/A)

[Installing packages: git, curl...]
[Installing Node.js 24...]
[Installing pnpm...]
[Installing Moltbot...]
[Configuring Moltbot...]
[Running health checks...]

✅ Done.

Moltbot is running in node mode (no proxy).
Gateway is listening on http://127.0.0.1:18789.

Configuration:
  - View config: `clawdbot config get gateway.trustedProxies`
  - View logs: `tail -f /tmp/clawdbot/clawdbot-gateway.log`

Step 4: Verify Installation

Check Node.js Version:

node --version

# Expected: v24.x.x

Check pnpm:

pnpm --version

# Expected: 9.x.x or later

Check Moltbot Installation:

which clawdbot

# Expected: /usr/local/bin/clawdbot or similar

Check Moltbot Version:

clawdbot --version

# Expected: version number

Test Local Gateway:

curl -I http://127.0.0.1:18789

# Expected: HTTP/1.1 200 OK or 302

Check Moltbot Process:

ps aux | grep clawdbot

# Expected: clawdbot-gateway process running

Step 5: Test Moltbot Functionality

Access Web Interface:

# Open in browser
open http://127.0.0.1:18789

Check Logs:

tail -f /tmp/clawdbot/clawdbot-gateway.log

Test Configuration:

# View all config
clawdbot config get

# View specific config
clawdbot config get gateway

Test Restart:

# Restart Moltbot
clawdbot restart

# Wait a few seconds
sleep 5

# Verify it's running
curl -I http://127.0.0.1:18789

Expected Results

✅ Success Criteria:

• Node.js 24+ installed via Homebrew
• pnpm installed and configured
• Moltbot installed globally
• Gateway service running on port 18789
• Web interface accessible at http://127.0.0.1:18789
• Logs available in /tmp/clawdbot/
• No proxy configured (direct access only)

Troubleshooting

Issue: Node.js not found after installation

Solution:

# Check Homebrew installation
brew list node@24

# Link Node.js 24
brew link --overwrite --force node@24

# Verify PATH
echo $PATH | grep -o '/usr/local/bin'

# Restart terminal and try again

Issue: Port 18789 already in use

Solution:

# Check what's using the port
lsof -i :18789

# Kill the process if needed
kill -9 <PID>

# Or configure Moltbot to use a different port
clawdbot config set gateway.port 18790
clawdbot restart

Issue: Permission denied errors

Solution:

# Check file permissions
ls -la /tmp/clawdbot/

# Fix permissions if needed
chmod -R u+rw /tmp/clawdbot/

# Restart Moltbot
clawdbot restart

---

Automated Testing Script

For CI/CD or repeated testing, use this automated test script:

#!/usr/bin/env bash
set -euo pipefail

# test-installer.sh - Automated installer testing

MODE="${1:-gateway}"
PROXY="${2:-caddy}"
DOMAIN="${3:-test.local}"

echo "==> Testing Installer"
echo "    Mode: $MODE"
echo "    Proxy: $PROXY"
echo "    Domain: $DOMAIN"
echo ""

# Run installer
if [[ "$MODE" == "gateway" ]]; then
  PROXY="$PROXY" ./scripts/init.sh "$DOMAIN"
else
  MODE=node ./scripts/init.sh "$DOMAIN"
fi

# Wait for services to start
sleep 10

# Test local gateway
echo "==> Testing local gateway..."
if curl -fsS --max-time 10 http://127.0.0.1:18789 >/dev/null; then
  echo "✅ Local gateway is accessible"
else
  echo "❌ Local gateway is NOT accessible"
  exit 1
fi

# Test public endpoint (gateway mode only)
if [[ "$MODE" == "gateway" ]]; then
  echo "==> Testing public endpoint..."
  if curl -fsS --max-time 10 "https://$DOMAIN" >/dev/null; then
    echo "✅ Public HTTPS endpoint is accessible"
  else
    echo "⚠️  Public HTTPS endpoint is NOT accessible (may need time for TLS)"
  fi
fi

echo ""
echo "✅ All tests passed!"

Usage:

# Test Ubuntu/Debian Gateway + Caddy
./test-installer.sh gateway caddy moltbot.example.com

# Test Ubuntu/Debian Gateway + Nginx
./test-installer.sh gateway nginx moltbot.example.com

# Test macOS Node mode
./test-installer.sh node caddy localhost

---

Test Results Template

Use this template to document your test results:

## Test Results

**Date**: YYYY-MM-DD
**Tester**: Your Name
**Environment**: Ubuntu 22.04 / Debian 12 / macOS 13

### Scenario 1: Ubuntu/Debian Gateway (Caddy)
- [ ] Installation completed successfully
- [ ] Caddy service running
- [ ] TLS certificate obtained
- [ ] Public HTTPS accessible
- [ ] Logs available
- **Notes**: 

### Scenario 2: Ubuntu/Debian Gateway (Nginx)
- [ ] Installation completed successfully
- [ ] Nginx service running
- [ ] Certbot certificate obtained
- [ ] HTTP to HTTPS redirect working
- [ ] Auto-renewal configured
- **Notes**: 

### Scenario 3: macOS Node Mode
- [ ] Installation completed successfully
- [ ] Node.js 24 installed
- [ ] Gateway accessible locally
- [ ] No proxy configured
- [ ] Logs available
- **Notes**: 

### Issues Encountered
1. 
2. 

### Recommendations
1. 
2. 

---

Next Steps After Testing

1. Document any issues found during testing
2. Update the installer if bugs are discovered
3. Add edge case handling based on test results
4. Create automated tests for CI/CD pipeline
5. Update documentation with real-world examples

Contributing Test Results

If you encounter issues or have suggestions, please:

1. Open an issue on GitHub with test results
2. Include full logs and error messages
3. Specify OS version and environment details
4. Provide steps to reproduce

---

Last Updated: 2026-01-29 Tested Platforms: Ubuntu 22.04, Debian 12, macOS 13 Installer Version: v1.0.0 (unified)