UsingWildcardDomains.md

Using Wildcard Domains

DockFlare supports the use of wildcard hostnames (e.g., *.example.com) in your container labels. This allows you to route all traffic for any subdomain of a given domain through the Cloudflare Tunnel to a specific service, unless a more specific subdomain rule exists.

Labeling Strategy

You use the standard cloudflare.tunnel.hostname label (or indexed versions like cloudflare.tunnel.0.hostname) but provide a wildcard hostname.

Example docker-compose.yml

This example configures a wildcard route for *.apps.example.com pointing to a single backend service.

version: '3.8'

services:
  # Your DockFlare service definition...
  dockflare:
    # ... (Configuration from Quick Start) ...
    networks:
      - cloudflare-net

  # A service that will handle all requests to *.apps.example.com
  wildcard-handler:
    image: traefik/whoami # Example service
    container_name: wildcard-service
    restart: unless-stopped
    networks:
      - cloudflare-net
    labels:
      # --- DockFlare Labels ---
      - "cloudflare.tunnel.enable=true"

      # Define the wildcard hostname
      # This will match anything.apps.example.com, test.apps.example.com, etc.
      - "cloudflare.tunnel.hostname=*.apps.example.com"

      # Define the target service for all matching subdomains
      - "cloudflare.tunnel.service=http://wildcard-handler:80"

      # Optional: Specify the zone if 'apps.example.com' or 'example.com' isn't the default
      # - "cloudflare.tunnel.zonename=example.com"

      # Optional: Disable TLS verification if needed
      # - "cloudflare.tunnel.no_tls_verify=true"

volumes:
  dockflare_data:

networks:
  cloudflare-net:

Explanation

• cloudflare.tunnel.hostname="*.apps.example.com": This tells DockFlare to configure the Cloudflare Tunnel to route requests for any subdomain directly under apps.example.com (e.g., test.apps.example.com, user1.apps.example.com, but not www.test.apps.example.com) to the specified service.
• cloudflare.tunnel.service="http://wildcard-handler:80": All traffic matching the wildcard hostname will be forwarded to port 80 of the wildcard-handler container.

Use Cases

• Multi-tenant Applications: Where each tenant might get a unique subdomain (tenant1.apps.example.com, tenant2.apps.example.com), all potentially handled by the same backend application instance (which then internally routes based on the hostname).
• Development Environments: Quickly expose dynamically generated preview environments under different subdomains.
• Catch-all Routing: Provide a default backend for any subdomain under a specific domain that doesn't have a more specific rule defined.

Precedence

Cloudflare Tunnel rules follow specificity. If you have both a wildcard rule and a specific subdomain rule defined (either via DockFlare labels on the same or different containers, or manually in Cloudflare):

• Rule for *.example.com -> service A
• Rule for specific.example.com -> service B

Requests to specific.example.com will be routed to service B. Requests to another.example.com (or any other subdomain) will be routed to service A.

DockFlare will manage the DNS record creation (CNAME for *.apps.example.com) and the tunnel ingress configuration accordingly.