aether-substrate docs cloudflared.md
6.3 kB · 224 lines
Markdown
at main

Cloudflare Tunnel (cloudflared) #

Connect your Substrate to the internet securely through Cloudflare's edge network — no open ports, automatic HTTPS, and custom domain support.

This solves the overnight HTTPS certificate expiry problem: Cloudflare manages TLS termination at their edge, and the tunnel connection is outbound-only from your server.

If you installed Substrate with the aether-substrate CLI, use the CLI flow first:

# During first-time bootstrap
aether-substrate init --tunnel cloudflare --hostname substrate.example.com

# Or after Substrate is already configured
aether-substrate tunnel cloudflare --hostname substrate.example.com

# If you want the cloudflared compose overlay running too
aether-substrate up --cloudflare

The manual steps below describe what the CLI is doing for you.

Once the stack is running, docker compose ps or Docker Desktop should still show the same local services: aether-substrate and aether-caddy, plus aetheros-user-workspace if workspace support is enabled.

Prerequisites #

  • A Cloudflare account (free tier works)
  • A domain added to Cloudflare (even a free one works)
  • Docker and Docker Compose running your Substrate

Setup #

1. Install cloudflared #

# macOS
brew install cloudflare/cloudflare/cloudflared

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

# Or use the Docker image (no install needed — see Docker Compose method below)

2. Authenticate #

cloudflared tunnel login
# Opens browser — select the domain you want to use

3. Create a Tunnel #

cloudflared tunnel create aether-substrate
# Note the tunnel ID (e.g., a1b2c3d4-e5f6-...)

4. Configure DNS #

# Point your subdomain at the tunnel
cloudflared tunnel route dns aether-substrate substrate.yourdomain.com

5. Create the Config File #

Create cloudflared-config.yml in your substrate directory:

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

ingress:
  # Main API + WebSocket
  - hostname: substrate.yourdomain.com
    service: http://substrate:3100
    originRequest:
      # Required for WebSocket (terminal, firehose)
      noTLSVerify: false
      connectTimeout: 30s
      # Keep WebSocket connections alive
      keepAliveTimeout: 90s
  # Catch-all (required by cloudflared)
  - service: http_status:404

6. Run with Docker Compose #

Use the provided overlay file:

docker compose -f docker-compose.yml -f docker-compose.cloudflared.yml up -d

Or add the cloudflared service manually to your compose file:

services:
  cloudflared:
    image: cloudflare/cloudflared:latest
    container_name: aether-cloudflared
    command: tunnel --config /etc/cloudflared/config.yml run
    volumes:
      - ./cloudflared-config.yml:/etc/cloudflared/config.yml:ro
      - ~/.cloudflared/credentials.json:/etc/cloudflared/credentials.json:ro
    networks:
      - internal
    depends_on:
      substrate:
        condition: service_healthy
    restart: unless-stopped

The credentials.json file is created by cloudflared tunnel login and stored in ~/.cloudflared/.

Docker Compose Overlay #

A docker-compose.cloudflared.yml overlay is included in this repo. To use it:

# Copy and edit the config
cp cloudflared-config.yml.example cloudflared-config.yml
# Edit with your tunnel ID and hostname

# Start everything
docker compose -f docker-compose.yml -f docker-compose.cloudflared.yml up -d

Verifying #

# Check tunnel status
cloudflared tunnel info aether-substrate

# Test from anywhere
curl https://substrate.yourdomain.com/health

# Test WebSocket (requires wscat: npm i -g wscat)
wscat -c "wss://substrate.yourdomain.com/ws?type=events" \
  -H "x-substrate-key: YOUR_API_KEY"

Frontend Configuration #

# In your Aether OS .env.local
NEXT_PUBLIC_SUBSTRATE_URL=https://substrate.yourdomain.com
SUBSTRATE_API_KEY=your-key-here

WebSocket Support #

Cloudflare Tunnel natively supports WebSocket connections. The Substrate uses WebSocket for:

  • Terminal sessions (/ws?type=terminal) — interactive PTY
  • Firehose events (/ws?type=events) — real-time ATProto events
  • Container terminals (/ws?type=container-terminal) — container PTY

All of these work through the tunnel without additional configuration. Cloudflare's edge handles the HTTP upgrade automatically.

Troubleshooting #

Tunnel not connecting #

# Check cloudflared logs
docker compose -f docker-compose.yml -f docker-compose.cloudflared.yml logs cloudflared

# Verify credentials
cloudflared tunnel list

WebSocket disconnects #

If terminal sessions drop frequently:

  • Increase keepAliveTimeout in your config (default 90s)
  • Check Cloudflare dashboard for rate limiting rules
  • Ensure your Cloudflare plan supports long-lived WebSocket connections (free tier does)

502 errors #

The Substrate container might not be healthy yet:

# Check substrate health
docker compose logs substrate | tail -20

# Wait for health check to pass
docker compose ps

DNS not resolving #

# Verify the CNAME was created
dig substrate.yourdomain.com

# Re-route if needed
cloudflared tunnel route dns aether-substrate substrate.yourdomain.com

Removing the Tunnel #

# Stop the service
docker compose -f docker-compose.yml -f docker-compose.cloudflared.yml down

# Delete the tunnel (also removes DNS routes)
cloudflared tunnel delete aether-substrate

Why Cloudflare Tunnel? #

The default Caddy setup uses internal (self-signed) TLS certificates. These work great for local development but have drawbacks for persistent remote access:

  • Browsers show certificate warnings
  • Certificates may need periodic trust/renewal
  • Requires open ports and firewall configuration
  • Doesn't survive IP changes

Cloudflare Tunnel solves all of these: the connection is outbound-only, TLS is handled by Cloudflare's edge with proper certificates, and it works behind any NAT/firewall without opening ports.