oc-ssl

name	oc-ssl
description	Set up SSL/HTTPS certificates using Let's Encrypt certbot. Use when the user says 'setup ssl', 'get certificate', 'enable https', 'certbot', 'letsencrypt', or wants to secure their ClawedBack instance with HTTPS on a public domain.
allowed-tools	Read Write Edit Bash Grep

SSL Certificate Setup

Obtain a free SSL certificate from Let's Encrypt using certbot, configure ClawedBack to use it, and set up auto-renewal.

Prerequisites

Before starting, confirm:

1. The user has a domain name pointing to this server (e.g., claude.example.com)
2. Port 80 is open and not in use (certbot needs it for verification)
3. The user is running as root (Mode B or C) — certbot requires root to bind port 80

Check these:

# Are we root?
id -u

# Is port 80 free?
ss -tlnp | grep ':80 ' || echo "Port 80 is free"

# Can the domain resolve to us?
# Ask the user for their domain first

Ask the user: "What domain name points to this server?" (e.g., claude.example.com)

Store the domain for use throughout this skill. Call it $DOMAIN.

Step 1: Install certbot

which certbot 2>/dev/null && echo "already installed" || apt install -y certbot

If not on Debian/Ubuntu:

# Fedora/RHEL
dnf install -y certbot
# Arch
pacman -S --noconfirm certbot

Step 2: Stop the ClawedBack server temporarily

Certbot standalone needs port 80. If the ClawedBack server is running on port 80 or 8080, it won't conflict (certbot uses 80, we use 8080). But if something else is on port 80, stop it:

# Check if our server is on port 80
ss -tlnp | grep ':80 '
# If something is there, note what it is and stop it temporarily

Step 3: Request the certificate

certbot certonly --standalone --non-interactive --agree-tos --email "$USER_EMAIL" -d "$DOMAIN"

Ask the user for their email address for Let's Encrypt notifications (expiry warnings, etc.).

If certbot succeeds, certificates are at:

• Certificate: /etc/letsencrypt/live/$DOMAIN/fullchain.pem
• Private key: /etc/letsencrypt/live/$DOMAIN/privkey.pem

Verify they exist:

ls -la /etc/letsencrypt/live/$DOMAIN/

Step 4: Set up auto-renewal

Certbot installs a systemd timer or cron job by default. Verify:

systemctl list-timers | grep certbot || crontab -l | grep certbot || echo "No auto-renewal found"

If no auto-renewal is set up:

# Add a cron job to renew twice daily (certbot only renews when close to expiry)
echo "0 3,15 * * * certbot renew --quiet --deploy-hook 'systemctl restart clawedback-server 2>/dev/null || true'" | crontab -

The --deploy-hook restarts the server after renewal so it picks up the new cert.

Step 5: Update the server start command

Read the current CLAUDE.md to find the server start command, then update it to use SSL with the cert paths.

Find and update the server start line in CLAUDE.md:

The commands section should include:

# Start server (HTTPS with Let's Encrypt)
cd .claude/skills/oc-poll/scripts && source ../.venv/bin/activate && python main.py --public /etc/letsencrypt/live/$DOMAIN/fullchain.pem --private /etc/letsencrypt/live/$DOMAIN/privkey.pem

For Mode C (no venv):

cd .claude/skills/oc-poll/scripts && python3 main.py --public /etc/letsencrypt/live/$DOMAIN/fullchain.pem --private /etc/letsencrypt/live/$DOMAIN/privkey.pem

Also append this to the Rules section of CLAUDE.md:

### SSL Configuration
This instance uses Let's Encrypt SSL certificates for HTTPS.
- Domain: $DOMAIN
- Certificate: /etc/letsencrypt/live/$DOMAIN/fullchain.pem
- Private key: /etc/letsencrypt/live/$DOMAIN/privkey.pem
- Auto-renewal: certbot renew runs automatically
- Always start the server with `--public` and `--private` flags pointing to the cert paths above.

Step 6: Restart the server with SSL

Kill the existing server and restart with SSL:

# Kill existing server (pkill catches the actual process, not just the nohup wrapper)
pkill -f "python3 main.py" 2>/dev/null || true
sleep 2

# Restart with SSL
cd $PROJECT_ROOT/.claude/skills/oc-poll/scripts
nohup python3 main.py --public /etc/letsencrypt/live/$DOMAIN/fullchain.pem --private /etc/letsencrypt/live/$DOMAIN/privkey.pem > $PROJECT_ROOT/data/logs/server.log 2>&1 &
sleep 1 && pgrep -f "python3 main.py" | tail -1 > $PROJECT_ROOT/data/server.pid

Verify:

sleep 2 && curl -sk https://$DOMAIN:8080/api/health

Step 7: Summary

Tell the user:

SSL is configured!

Domain: $DOMAIN
URL: https://$DOMAIN:8080
Certificate: /etc/letsencrypt/live/$DOMAIN/fullchain.pem
Auto-renewal: Active (certbot renew runs automatically)

Your ClawedBack instance is now accessible via HTTPS.
CLAUDE.md has been updated to always start with SSL.

Troubleshooting

"certbot: command not found" — install with apt install certbot or snap install certbot --classic

"Port 80 already in use" — stop whatever is on port 80 (ss -tlnp | grep :80), run certbot, then restart it. Or use certbot certonly --webroot if you have a web server you want to keep running.

"Domain does not resolve" — the DNS A record must point to this server's public IP. Check with dig $DOMAIN or nslookup $DOMAIN.

"Permission denied" — certbot needs root. Use Mode B or C.

Certificate renewal failed — check certbot renew --dry-run for errors. Common issue: port 80 blocked by firewall.