ManagingDNSZones.md

Managing DNS Zones

DockFlare needs to know which Cloudflare DNS Zone (essentially, your domain name registered with Cloudflare, like example.com) a given hostname belongs to, so it can create the necessary CNAME records in the correct place.

There are two ways DockFlare determines the zone for a hostname:

1. Default Zone via Environment Variable (CF_ZONE_ID)

• You provide the Zone ID of your primary or most commonly used domain via the CF_ZONE_ID environment variable when starting DockFlare.
• How it's used: If a container label specifies a hostname without also specifying a zonename label, DockFlare assumes the hostname belongs to the zone identified by CF_ZONE_ID.
• Requirement: This environment variable is required unless you guarantee that every single hostname label you use across all your containers also includes a corresponding zonename label.

2. Specific Zone via Container Label (zonename)

• You can explicitly tell DockFlare which zone a specific hostname belongs to by adding the {prefix}.zonename label (or {prefix}.<index>.zonename for indexed labels) to the container.
• How it's used: When this label is present for a given hostname (or hostname index), DockFlare ignores the default CF_ZONE_ID for that specific rule. It uses the provided zonename (e.g., "otherdomain.org") to look up the correct Zone ID via the Cloudflare API and creates the DNS record within that specific zone.
• Requirement: The value of the zonename label must be a domain name (e.g., "example.com", "mydomain.org") that is registered as an active zone within the Cloudflare account associated with your CF_API_TOKEN and CF_ACCOUNT_ID.

Multi-Domain Strategies

If you manage multiple domains (zones) in Cloudflare and want to expose services under hostnames across them using DockFlare, you have two main strategies:

• Option 1 (Recommended for Simplicity):

  • Set CF_ZONE_ID to the Zone ID of your primary or most frequently used domain.
  • For any containers exposing hostnames under that primary domain, you only need the hostname label.
  • For containers exposing hostnames under other domains, add both the hostname label and the corresponding zonename label.

• Option 2 (Explicit Everywhere):

  • Always include the zonename label alongside the hostname label for every rule you define on your containers.
  • In this case, the CF_ZONE_ID environment variable technically becomes optional, as it will never be used as a fallback. This can be less error-prone if you frequently work with many zones.

Example with zonename Label

This snippet shows using the zonename label within an indexed configuration:

services:
  my-service:
    image: nginx:latest
    container_name: my-app-service
    networks:
      - cloudflare-net
    labels:
      - "cloudflare.tunnel.enable=true"

      # Hostname 1: Uses the default zone from CF_ZONE_ID
      - "cloudflare.tunnel.0.hostname=app.primarydomain.com"
      - "cloudflare.tunnel.0.service=http://my-service:80"

      # Hostname 2: Explicitly belongs to 'secondarydomain.net' zone
      - "cloudflare.tunnel.1.hostname=api.secondarydomain.net"
      - "cloudflare.tunnel.1.service=http://my-service:80"
      - "cloudflare.tunnel.1.zonename=secondarydomain.net" # Tells DockFlare which zone to use

In this example, DockFlare will:

1. Create a CNAME for app.primarydomain.com in the zone specified by CF_ZONE_ID.
2. Look up the Zone ID for secondarydomain.net using the Cloudflare API.
3. Create a CNAME for api.secondarydomain.net in the secondarydomain.net zone.