Labelgate

A simple tool for managing Cloudflare DNS, Tunnels, and Zero Trust Access using Docker labels.

Documentation

Full documentation is available at labelgate-docs.pages.dev.

Quick Start

Create a .env file:

LABELGATE_CLOUDFLARE_API_TOKEN=your-api-token
LABELGATE_CLOUDFLARE_ACCOUNT_ID=your-account-id
LABELGATE_CLOUDFLARE_TUNNEL_ID=your-tunnel-id
# Authenticate cloudflared (not for labelgate)
TUNNEL_TOKEN=your-tunnel-token

Create compose.yaml:

services:
  labelgate:
    image: ghcr.io/channinghe/labelgate:v0
    container_name: labelgate
    restart: unless-stopped
    # use command "stat -c '%g' /var/run/docker.sock" to get the group id of the docker socket
    group_add:
      - "REPLACE_WITH_GROUP_ID"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      # Run the command "sudo chown -R 65532:65532 ./labelgate-data" to ensure the mount path has the correct ownership.
      - ./labelgate-data:/app/config
    environment:
      - LABELGATE_CLOUDFLARE_API_TOKEN
      - LABELGATE_CLOUDFLARE_ACCOUNT_ID
      - LABELGATE_CLOUDFLARE_TUNNEL_ID
    ports:
      - "28111:8080"
    # labelgate no need to connect to the network "cloudflared-network"
    # Because Labelgate simply uses the Cloudflare API to create tunnel ingress rules or DNS records.
    network_mode: bridge

  cloudflared:
    image: cloudflare/cloudflared:latest
    restart: unless-stopped
    command: tunnel run --token ${TUNNEL_TOKEN}
    networks:
      - cloudflared-network

  webapp:
    image: nginx:alpine
    container_name: webapp
    labels:
      labelgate.tunnel.web.hostname: "app.example.com"
      labelgate.tunnel.web.service: "http://webapp:80"
      # or dns 
      labelgate.dns.web-dns.hostname: "app.example.com"
      labelgate.dns.web-dns.target: "xxx.xxx.xxx.xxx"
    networks:
      - cloudflared-network

# Create a network for the services you want to connect to cloudflared.
# This allows your Cloudflare tunnel to connect to services via their container_name within the "cloudflared-network" bridge, eliminating the need for port mapping.
# Consolidating all public services into a single network ensures they remain isolated from private services.
networks:
  cloudflared-network:

docker compose up -d

That's it. Labelgate watches your containers and syncs labels to Cloudflare automatically.

Note: We do not publish a latest tag. Use explicit version tags for strict version control:

Tag	Description
v0.1.0	Exact version
v0.1	Latest patch in 0.1.x
v0	Latest minor in 0.x.x
v0.1.0-full	debug variant includes busybox shell

Features

• DNS Management — Create and sync Cloudflare DNS records via Docker labels
• Tunnel Ingress — Expose services through Cloudflare Tunnels without port forwarding
• Zero Trust Access — Configure Cloudflare Access policies declaratively
• Multi-host Agents — Manage containers across multiple Docker hosts
• Web Dashboard — Built-in UI for monitoring
• Secure & Lightweight — Rootless, distroless Docker images by default, with sizes typically under 30 MiB

License

MIT