Cloudflare Tunnel - HAPI

Cloudflare Tunnel creates a secure, outbound-only connection from your server to Cloudflare’s network, eliminating the need for public IP addresses or port forwarding.

Why Cloudflare Tunnel?

No port forwarding

Works without opening firewall ports or configuring NAT

DDoS protection

Cloudflare’s network protects against DDoS attacks

Free HTTPS

Automatic SSL/TLS certificates with no configuration

Custom domain

Use your own domain for professional access

Important: Do not use Cloudflare Quick Tunnels (TryCloudflare). They do not support Server-Sent Events (SSE), which HAPI requires for real-time updates. Use a Named Tunnel instead.

Prerequisites

Cloudflare account (free tier works)
Domain managed by Cloudflare DNS
cloudflared CLI installed

Setup

1

Install cloudflared

Download from Cloudflare downloads page:

# macOS
brew install cloudflared

# Linux (Debian/Ubuntu)
wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared-linux-amd64.deb

# Other platforms: see Cloudflare docs

2

Authenticate with Cloudflare

cloudflared tunnel login

This opens a browser to authenticate with your Cloudflare account.

3

Create a named tunnel

cloudflared tunnel create hapi

Save the tunnel ID displayed (needed for configuration).

4

Configure DNS

Route a subdomain to your tunnel:

cloudflared tunnel route dns hapi hapi.yourdomain.com

5

Create tunnel configuration

Create ~/.cloudflared/config.yml:

tunnel: <your-tunnel-id>
credentials-file: /home/username/.cloudflared/<your-tunnel-id>.json

ingress:
  - hostname: hapi.yourdomain.com
    service: http://localhost:3006
  - service: http_status:404

Replace <your-tunnel-id> with the ID from step 3.

6

Start HAPI hub

export HAPI_PUBLIC_URL="https://hapi.yourdomain.com"
hapi hub

The hub starts on http://localhost:3006.

7

Start Cloudflare Tunnel

cloudflared tunnel --protocol http2 run hapi

Use --protocol http2 instead of QUIC (the default) to avoid timeout issues with long-lived SSE connections.

8

Access your hub

Open https://hapi.yourdomain.com in your browser.

Configuration

HAPI environment variables

export HAPI_PUBLIC_URL="https://hapi.yourdomain.com"
export HAPI_LISTEN_HOST=127.0.0.1  # Keep localhost for security
export HAPI_LISTEN_PORT=3006
hapi hub

Cloudflare Tunnel config.yml

Advanced example with multiple services:

tunnel: <your-tunnel-id>
credentials-file: /home/username/.cloudflared/<your-tunnel-id>.json

ingress:
  # HAPI hub
  - hostname: hapi.yourdomain.com
    service: http://localhost:3006
    originRequest:
      noTLSVerify: false
      connectTimeout: 30s
      keepAliveTimeout: 90s

  # Catch-all rule (required)
  - service: http_status:404

The catch-all rule (http_status:404) is required as the last entry.

Run as background service

Using systemd (Linux)

Create /etc/systemd/system/cloudflared.service:

[Unit]
Description=Cloudflare Tunnel
After=network.target

[Service]
Type=simple
User=username
ExecStart=/usr/local/bin/cloudflared tunnel --protocol http2 run hapi
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable cloudflared
sudo systemctl start cloudflared
sudo systemctl status cloudflared

Using pm2

pm2 start "cloudflared tunnel --protocol http2 run hapi" --name cloudflared
pm2 start "hapi hub" --name hapi-hub
pm2 save
pm2 startup

Using macOS launchd

Create ~/Library/LaunchAgents/com.cloudflare.tunnel.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.cloudflare.tunnel</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/cloudflared</string>
        <string>tunnel</string>
        <string>--protocol</string>
        <string>http2</string>
        <string>run</string>
        <string>hapi</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

Load the service:

launchctl load ~/Library/LaunchAgents/com.cloudflare.tunnel.plist

Telegram integration

With Cloudflare Tunnel providing HTTPS, you can enable Telegram Mini App:

export TELEGRAM_BOT_TOKEN="your-bot-token"
export HAPI_PUBLIC_URL="https://hapi.yourdomain.com"
hapi hub

See Telegram Setup for details.

Troubleshooting

Tunnel connects but web app doesn’t load

Verify HAPI_PUBLIC_URL matches your tunnel hostname exactly
Check tunnel is using --protocol http2 (not QUIC)
Ensure HAPI hub is running on port 3006
Test locally: curl http://localhost:3006/api/health

SSE not working / Real-time updates failing

Confirm you’re using a Named Tunnel, not Quick Tunnel (TryCloudflare)

Add to config.yml under originRequest:

keepAliveTimeout: 90s
noHappyEyeballs: true

Use --protocol http2 when starting tunnel

DNS not resolving

Verify DNS record created: cloudflared tunnel route dns hapi hapi.yourdomain.com
Check Cloudflare dashboard → DNS → Records
DNS propagation can take a few minutes

Connection timeouts

Increase timeout in config.yml:

originRequest:
  connectTimeout: 60s
  keepAliveTimeout: 120s

Ensure no firewall blocking localhost:3006

Comparison with relay

Feature	Relay	Cloudflare Tunnel
Setup complexity	One command	Initial setup required
Custom domain	No	Yes
Encryption	WireGuard + TLS	TLS via Cloudflare
Latency	Direct peer-to-peer	Through Cloudflare network
Cost	Free	Free (Cloudflare Free tier)
DDoS protection	No	Yes
Configuration	Zero	Tunnel config + DNS

When to use Cloudflare Tunnel

Ideal when you:

Want a custom domain (e.g., hapi.yourcompany.com)
Need DDoS protection and Cloudflare features
Have a Cloudflare account and domain
Prefer managed infrastructure over relay
Want team access with consistent URL

Next steps

Telegram Setup

Enable Telegram Mini App (now that you have HTTPS)

Runner Setup

Configure background runner for remote sessions

Resources

Self-Hosted Deployment

⌘I