ManagingDNSZones.md

Managing DNS Zones

To create the necessary DNS records for your services, DockFlare needs to know which Cloudflare Zone (i.e., your domain name like example.com) a given hostname belongs to.

DockFlare uses a two-level approach to determine the correct zone.

1. The Default Zone (via Environment Variable)

This is the primary method and covers most use cases.

• You provide the Zone ID of your main domain in the CF_ZONE_ID environment variable.
• How it's used: If a container's labels define a hostname but do not include a zonename label, DockFlare assumes the hostname belongs to this default zone.
• Requirement: This environment variable is required unless you plan to specify a zonename label for every single rule across all your containers.

2. A Specific Zone (via Container Label)

You can override the default for any specific rule by adding the zonename label.

• How it's used: Add the {prefix}.zonename label (or {prefix}.<index>.zonename for indexed rules) to a container. The value should be the domain name itself (e.g., "other-domain.org").
• When this label is present, DockFlare ignores the default CF_ZONE_ID for that rule and looks up the Zone ID for the specified domain name.
• Requirement: The domain name you provide must be an active zone within your Cloudflare account.

Multi-Domain Strategy

If you manage multiple domains in Cloudflare, the recommended strategy is:

1. Set CF_ZONE_ID to the Zone ID of your most frequently used domain.
2. For services on your primary domain, you only need the hostname label.
3. For services on any other domain, add both the hostname and the corresponding zonename label.

Example with the zonename Label

This example shows how to manage hostnames across two different domains from a single container.

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

      # --- Rule 0: Uses the default zone from CF_ZONE_ID ---
      - "dockflare.0.hostname=app.primary-domain.com"
      - "dockflare.0.service=http://my-service:80"

      # --- Rule 1: Uses a different, specified zone ---
      - "dockflare.1.hostname=api.secondary-domain.net"
      - "dockflare.1.service=http://my-service:80"
      - "dockflare.1.zonename=secondary-domain.net" # Tells DockFlare which zone to use for this rule

In this scenario, DockFlare will:

1. Create a CNAME record for app.primary-domain.com in the zone specified by your CF_ZONE_ID.
2. Look up the Zone ID for secondary-domain.net via the Cloudflare API.
3. Create a CNAME record for api.secondary-domain.net within the secondary-domain.net zone.