# 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. ## CLI Route (Recommended) If you installed Substrate with the `aether-substrate` CLI, use the CLI flow first: ```bash # 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](https://dash.cloudflare.com/sign-up) (free tier works) - A domain added to Cloudflare (even a free one works) - Docker and Docker Compose running your Substrate ## Setup ### 1. Install cloudflared ```bash # 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 ```bash cloudflared tunnel login # Opens browser — select the domain you want to use ``` ### 3. Create a Tunnel ```bash cloudflared tunnel create aether-substrate # Note the tunnel ID (e.g., a1b2c3d4-e5f6-...) ``` ### 4. Configure DNS ```bash # 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: ```yaml tunnel: 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: ```bash docker compose -f docker-compose.yml -f docker-compose.cloudflared.yml up -d ``` Or add the cloudflared service manually to your compose file: ```yaml 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: ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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: ```bash # Check substrate health docker compose logs substrate | tail -20 # Wait for health check to pass docker compose ps ``` ### DNS not resolving ```bash # 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 ```bash # 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.