From 164640ada44c07e1d3f6e985cf3f29d113bdfc4c Mon Sep 17 00:00:00 2001 From: Haitao Pan Date: Thu, 29 Jan 2026 12:23:00 +0800 Subject: [PATCH] docs: add comprehensive testing guide for unified installer - Test scenario 1: Ubuntu/Debian Gateway mode with Caddy - Test scenario 2: Ubuntu/Debian Gateway mode with Nginx - Test scenario 3: macOS Node mode - Include step-by-step verification procedures - Add troubleshooting for common issues - Provide automated testing script - Include test results template --- docs/install/testing-guide.md | 710 ++++++++++++++++++++++++++++++++++ 1 file changed, 710 insertions(+) create mode 100644 docs/install/testing-guide.md diff --git a/docs/install/testing-guide.md b/docs/install/testing-guide.md new file mode 100644 index 000000000..39f1e21d7 --- /dev/null +++ b/docs/install/testing-guide.md @@ -0,0 +1,710 @@ +--- +summary: "Step-by-step testing guide for unified installer across different platforms and modes" +read_when: + - 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**: +```bash +# 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): +```bash +/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 + +```bash +# 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 + +```bash +# 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**: +```bash +# 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**: +```bash +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**: +```bash +cat /etc/caddy/Caddyfile + +# Expected output: +# moltbot.example.com { +# reverse_proxy 127.0.0.1:18789 +# } +``` + +**Test Local Gateway**: +```bash +curl -I http://127.0.0.1:18789 + +# Expected: HTTP/1.1 200 OK or 302 redirect +``` + +**Test Public HTTPS**: +```bash +curl -I https://moltbot.example.com + +# Expected: HTTP/2 200 OK (with valid TLS certificate) +``` + +**Check TLS Certificate**: +```bash +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**: +```bash +# Open in browser +https://moltbot.example.com +``` + +**Check Logs**: +```bash +# 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**: +```bash +# 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**: +```bash +# 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 + +```bash +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**: +```bash +# Check Nginx status +sudo systemctl status nginx + +# Check Moltbot status +systemctl --user status clawdbot-gateway +``` + +**Check Nginx Configuration**: +```bash +cat /etc/nginx/sites-available/clawdbot-moltbot.example.com.conf + +# Verify it's enabled +ls -l /etc/nginx/sites-enabled/ +``` + +**Test Nginx Configuration**: +```bash +sudo nginx -t + +# Expected: syntax is ok, test is successful +``` + +**Check Certbot Certificate**: +```bash +sudo certbot certificates + +# Expected output showing certificate for moltbot.example.com +``` + +**Test HTTPS**: +```bash +curl -I https://moltbot.example.com + +# Expected: HTTP/1.1 200 OK (or 302) +``` + +**Test HTTP to HTTPS Redirect**: +```bash +curl -I http://moltbot.example.com + +# Expected: HTTP/1.1 301 Moved Permanently +# Location: https://moltbot.example.com/ +``` + +#### Step 5: Test Certificate Auto-Renewal + +```bash +# 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**: +```bash +# 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**: +```bash +# 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 + +```bash +# 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 + +```bash +# 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**: +```bash +node --version + +# Expected: v24.x.x +``` + +**Check pnpm**: +```bash +pnpm --version + +# Expected: 9.x.x or later +``` + +**Check Moltbot Installation**: +```bash +which clawdbot + +# Expected: /usr/local/bin/clawdbot or similar +``` + +**Check Moltbot Version**: +```bash +clawdbot --version + +# Expected: version number +``` + +**Test Local Gateway**: +```bash +curl -I http://127.0.0.1:18789 + +# Expected: HTTP/1.1 200 OK or 302 +``` + +**Check Moltbot Process**: +```bash +ps aux | grep clawdbot + +# Expected: clawdbot-gateway process running +``` + +#### Step 5: Test Moltbot Functionality + +**Access Web Interface**: +```bash +# Open in browser +open http://127.0.0.1:18789 +``` + +**Check Logs**: +```bash +tail -f /tmp/clawdbot/clawdbot-gateway.log +``` + +**Test Configuration**: +```bash +# View all config +clawdbot config get + +# View specific config +clawdbot config get gateway +``` + +**Test Restart**: +```bash +# 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**: +```bash +# 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**: +```bash +# Check what's using the port +lsof -i :18789 + +# Kill the process if needed +kill -9 + +# Or configure Moltbot to use a different port +clawdbot config set gateway.port 18790 +clawdbot restart +``` + +**Issue**: Permission denied errors + +**Solution**: +```bash +# 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: + +```bash +#!/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**: +```bash +# 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: + +```markdown +## 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)