← Back to Index

Systemd Services Installation Guide

Permanent webhook + Cloudflare tunnel setup (20 min)

Prerequisites

Part 1: Cloudflare Named Tunnel (10 min)

Step 1: Kill the temporary quick tunnel (if running)

pkill cloudflared

Step 2: Create named tunnel

cloudflared tunnel create minnie-webhook

Output will show:

Created tunnel minnie-webhook with id XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Copy that tunnel ID - you'll need it in Step 4

Step 3: Create config directory

mkdir -p ~/.cloudflared

Step 4: Create tunnel config file

# Replace TUNNEL_ID with the ID from Step 2
cat > ~/.cloudflared/config.yml << 'EOF'
tunnel: TUNNEL_ID
credentials-file: /home/linuxuser/.cloudflared/TUNNEL_ID.json

ingress:
  - hostname: minnie-webhook.cfargotunnel.com
    service: http://localhost:8080
  - service: http_status:404
EOF

IMPORTANT: Replace both instances of TUNNEL_ID with your actual tunnel ID

Step 5: Route the tunnel

cloudflared tunnel route dns minnie-webhook minnie-webhook.cfargotunnel.com

This gives you: https://minnie-webhook.cfargotunnel.com (permanent URL)

Step 6: Test the tunnel manually

cloudflared tunnel run minnie-webhook

Should see: "Connection established" and tunnel info

Press Ctrl+C to stop (we'll run it via systemd next)

Part 2: Install Systemd Services (10 min)

Step 7: Copy webhook service file

sudo cp /home/linuxuser/.openclaw/workspace/systemd/minnie-webhook.service /etc/systemd/system/

Step 8: Copy tunnel service file

sudo cp /home/linuxuser/.openclaw/workspace/systemd/cloudflare-tunnel.service /etc/systemd/system/

Step 9: Reload systemd

sudo systemctl daemon-reload

Step 10: Enable services (auto-start on boot)

sudo systemctl enable minnie-webhook.service
sudo systemctl enable cloudflare-tunnel.service

Step 11: Start services

sudo systemctl start minnie-webhook.service
sudo systemctl start cloudflare-tunnel.service

Step 12: Verify both running

sudo systemctl status minnie-webhook.service
sudo systemctl status cloudflare-tunnel.service

Should see: Active: active (running)

Part 3: Test End-to-End (5 min)

Step 13: Test webhook endpoint

curl https://minnie-webhook.cfargotunnel.com/health

Should return: {"status":"healthy","service":"pubsub-webhook"}

Step 14: Create Gmail Pub/Sub push subscription

Go to: console.cloud.google.com → Pub/Sub → Subscriptions

  1. Click "CREATE SUBSCRIPTION"
  2. Subscription ID: openclaw-gmail-push
  3. Topic: openclaw-events
  4. Delivery type: Push
  5. Endpoint URL: https://minnie-webhook.cfargotunnel.com/webhooks/gmail/quan@ztag.com
  6. Click "CREATE"

Step 15: Send test email

Send an email to quan@ztag.com from any account

Step 16: Check webhook logs

sudo journalctl -u minnie-webhook.service -f

Should see: "📧 Gmail event for quan@ztag.com: [historyId]"

If you see this, you're DONE! Gmail Pub/Sub is fully operational.

Troubleshooting

Webhook service won't start:

# Check if container is running
docker ps | grep openclaw

# Check logs
sudo journalctl -u minnie-webhook.service -n 50

Tunnel service won't start:

# Check credentials file exists
ls ~/.cloudflared/*.json

# Check config is valid
cloudflared tunnel info minnie-webhook

# Check logs
sudo journalctl -u cloudflare-tunnel.service -n 50

Webhook not receiving events:

# Verify tunnel is reachable
curl https://minnie-webhook.cfargotunnel.com/health

# Check Gmail watch is active (should expire in ~7 days)
# If expired, re-run: python3 tools/gmail-watch-setup.py quan@ztag.com minniebot openclaw-events

Service Management Commands

Check status:

sudo systemctl status minnie-webhook.service
sudo systemctl status cloudflare-tunnel.service

View logs:

sudo journalctl -u minnie-webhook.service -f
sudo journalctl -u cloudflare-tunnel.service -f

Restart services:

sudo systemctl restart minnie-webhook.service
sudo systemctl restart cloudflare-tunnel.service

Stop services:

sudo systemctl stop minnie-webhook.service
sudo systemctl stop cloudflare-tunnel.service

What This Gives You

Permanent infrastructure:

Gmail Pub/Sub flow:

Gmail → Google Pub/Sub → Cloudflare Tunnel (HTTPS) → Webhook Server (container) → Event processing

Result: Real-time email notifications, permanent, secure, auto-recovering.

Services will survive container restarts, VPS reboots, and crashes. This is production-ready infrastructure.