Flask-Cloudflared

Common errors

• FileNotFoundError: [Errno 2] No such file or directory: 'cloudflared'

  cause The `cloudflared` executable could not be found by the system. This often means it's not installed or not in the system's PATH.
  fix Install the `cloudflared` Python package (`pip install cloudflared`) which typically handles the executable download. If it persists, manually install `cloudflared` from Cloudflare's official downloads and ensure it's in your system's PATH.

• OSError: [Errno 98] Address already in use

  cause Your Flask application is trying to start on a port (e.g., 5000) that is already being used by another process on your machine.
  fix Change the port for your Flask application and the `run_cloudflared_tunnel` function to an available port, for example: `app.run(port=5001)` and `run_cloudflared_tunnel(port=5001)`.

• Cloudflared tunnel failed to start or connect.

  cause General connection issues, firewall blocking, incorrect `cloudflared` configuration, or problems with Cloudflare's network.
  fix Check the console output for any `cloudflared` specific errors. Ensure your local firewall isn't blocking outgoing connections. Verify your internet connection. Try running `cloudflared tunnel --help` in your terminal to confirm the executable works independently.

Warnings

• gotcha The `cloudflared` executable must be present and accessible in your system's PATH. Although `pip install cloudflared` helps, it doesn't always guarantee immediate accessibility in all environments, especially if relying on system-wide PATH configurations.
  Fix: Ensure the `cloudflared` Python package is installed (`pip install cloudflared`) and that the executable it provides is either in your system's PATH or directly callable. You can test by running `cloudflared --version` in your terminal.
• gotcha The `run_cloudflared_tunnel` function is non-blocking, meaning it starts the tunnel in a separate subprocess. Ensure your Flask app starts *after* calling `run_cloudflared_tunnel` (as shown in quickstart) and on the same port, otherwise the tunnel might try to connect to a non-existent or wrong service.
  Fix: Call `run_cloudflared_tunnel()` before `app.run()`, and ensure both use the identical port number. The `port` argument in `run_cloudflared_tunnel` should match the port Flask is listening on.
• gotcha As a 0.0.x version library, `flask-cloudflared`'s API is subject to change without strict adherence to semantic versioning. While stable for its current features, expect potential minor breaking changes in future `0.0.y` releases.
  Fix: Pin your dependency to an exact version (`flask-cloudflared==0.0.15`) in production. Regularly review the GitHub repository for release notes or breaking changes when upgrading.

Install

• pip install flask-cloudflared Install latest version

Imports

• run_cloudflared_tunnel

  from flask_cloudflared import run_cloudflared_tunnel

Quickstart

This quickstart demonstrates how to initialize a basic Flask application and start a Cloudflare Tunnel to expose it. The `run_cloudflared_tunnel` function handles the tunnel creation and outputs the public URL. Ensure Flask is running on the port specified for the tunnel.

import os
from flask import Flask
from flask_cloudflared import run_cloudflared_tunnel

app = Flask(__name__)

@app.route('/')
def hello_world():
    return 'Hello, World!'

if __name__ == '__main__':
    # Cloudflared will attempt to expose the specified port (default Flask port is 5000)
    # The tunnel runs in a separate process, allowing app.run() to proceed.
    tunnel_url = run_cloudflared_tunnel(port=5000)
    if tunnel_url:
        print(f"Cloudflare Tunnel is active at: {tunnel_url}")
    else:
        print("Failed to start Cloudflare Tunnel.")
    
    # Run the Flask application on the same port
    app.run(port=5000)