Cloudflare Tunnels¶

Cloudflare docs

Cloudflare Tunnel provides a secure way to connect resources to Cloudflare without a publicly routable IP address. Instead of sending traffic to an external IP, cloudflared creates outbound-only connections to Cloudflare's global network — no open ports, no exposed home IP.

This page covers the one tunnel per host design: every Docker host runs its own cloudflared container, and each public hostname is a route on that host's tunnel pointing straight at a container. Services join a shared external Docker network. No reverse proxy is involved.

Cloudflare Edge
    │
    ├─ tunnel: server1 ──── cloudflared
    │                               ├─ immich.<YOUR_DOMAIN>   → immich-server:2283
    │                               └─ ha.<YOUR_DOMAIN>       → homeassistant:8123
    │
    └─ tunnel: server2 ──── cloudflared
                                    ├─ seerr.<YOUR_DOMAIN>    → seerr:5055
                                    └─ pdf.<YOUR_DOMAIN>      → bentopdf:8080

1. Create the Tunnel¶

1. Log in to the Cloudflare Zero Trust Dashboard

2. Navigate to Networks > Connectors > Cloudflare Tunnels

3. Click Create a tunnel, choose Cloudflared as the connector type, and select Next

4. Enter a name for the tunnel — use the host name (e.g. <YOUR_HOSTNAME>)

5. Click Save tunnel

6. On the Install connector page, select Docker and copy the token from the provided command — it's the long string after --token

2. Create the Shared Tunnel Network¶

On the host, create a persistent external Docker network. This must exist before any stack tries to join it.

docker network create tunnel-net

This network persists independently of any compose stack. Only create it once per host.

3. Deploy the Connector¶

One Tunnel per Host¶

/opt/docker/cloudflared/compose.yaml

services:
  cloudflared:
    image: cloudflare/cloudflared:2026.10.3   # pinned; Renovate opens a PR for each new release
    container_name: cloudflared
    restart: unless-stopped
    command: tunnel run
    env_file:
      - .env              # TUNNEL_TOKEN lives here, never in git
    dns:
      - <YOUR_DNS_SERVER_IP>
    networks:
      - tunnel-net

networks:
  tunnel-net:
    external: true

/opt/docker/cloudflared/.env

TUNNEL_TOKEN=<YOUR_TUNNEL_TOKEN>

Start it:

cd /opt/docker/cloudflared
docker compose up -d

The connector will appear in the Zero Trust dashboard. Once running, click Next in the dashboard to proceed. The tunnel should show as Healthy under Networks > Connectors.

3a. One Tunnel Per Service¶

Instead of one tunnel per host, it is possible to run a separate cloudflared container per service — colocated in the same compose stack.

services:
  cloudflared:
    image: cloudflare/cloudflared:2026.10.3
    container_name: cloudflared
    restart: unless-stopped
    environment:
      - TUNNEL_TOKEN=${TUNNEL_TOKEN}
    command: tunnel run
    networks:
      - tunnel-net

  my-app:
    image: your-app-image:latest
    container_name: my-app
    restart: unless-stopped
    networks:
      - tunnel-net
    # No ports need to be exposed to the host!

networks:
  tunnel-net:
    name: tunnel-net

4. Expose a Service¶

For any service you want to expose externally, add it to the shared tunnel-net network. No cloudflared container needed in the service's compose file.

services:
  my-app:
    image: your-app-image:latest
    container_name: my-app
    restart: unless-stopped
    networks:
      - tunnel-net      # joins the shared tunnel network
      - internal-net    # for DB, cache, etc — isolated from tunnel

networks:
  tunnel-net:
    external: true      # must already exist on the host
  internal-net:
    internal: true      # no external access

The service URL used in Cloudflare is the container name and internal port — not the host port.

container_name: bentopdf      →  http://bentopdf:8080
container_name: immich-server →  http://immich-server:2283

5. Add a Published Application Route¶

Tell Cloudflare where to route traffic for this service. Per the official docs, this is done immediately after the connector is running — before or alongside creating the Access application.

1. Navigate to Networks > Connectors > Cloudflare Tunnels

2. Click your tunnel → Published application routes tab → Add a published application route

3. Fill in the details:

   Field	Value
   Subdomain	e.g. immich
   Domain	<YOUR_DOMAIN>
   Path	leave empty
   Service Type	HTTP
   URL	immich-server:2283 (container name + internal port)

4. Under Additional application settings, enable Protect with Access — this instructs cloudflared to validate the Access JWT on every request, rejecting anything that bypasses the Access layer.

5. Select Save. Cloudflare automatically creates the CNAME DNS record.

6. Create an Access Application¶

Per the official docs, creating an Access application is what controls who can reach the published route. All Access applications are deny-by-default — a user must match an Allow policy to be granted access.

1. Navigate to Access controls > Applications

2. Click Add an application → Self-hosted

3. Configure:

   Field	Value
   Application name	e.g. Immich
   Session Duration	30 days (recommended for personal use)
   Application domain	Match exactly what was set in the tunnel route (e.g. immich.<YOUR_DOMAIN>)

4. Click Policies tab

Create an Access Policy¶

1. Configure the policy:

   Field	Value
   Policy Name	e.g. Allow Me
   Action	Allow

2. Under Configure rules:

   • Include: Select Emails → add each allowed email address
   • Or use Email ending in for a whole domain

3. Click Next through Setup, then Add application

Sources & further reading¶

• Cloudflare Tunnel
• Create a remotely-managed tunnel
• Self-hosted public applications (Access)
• cloudflared releases