romtuck/openclaw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add comprehensive testing guide for unified installer

Browse Source 
- 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
This commit is contained in:
Haitao Pan 2026-01-29 12:23:00 +08:00
parent 2d1bbf32cc
commit 164640ada4
1 changed files with 710 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

710
docs/install/testing-guide.md Normal file
View File

@ -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 <PID>
# 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)