Skip to content

ContainerLabels.md

Jump to bottom
Chris edited this page May 29, 2025 · 9 revisions

Container Labels

Docker labels are the primary mechanism for instructing DockFlare which containers to expose and how to configure their public access and Zero Trust Access policies via your Cloudflare Tunnel.

DockFlare monitors Docker events and inspects container labels. If a container has the required labels, DockFlare will automatically configure the necessary DNS records, Cloudflare Tunnel ingress rules, and potentially Cloudflare Access Applications.

Label Prefix

DockFlare looks for labels starting with a specific prefix.

  • Default Prefix: cloudflare.tunnel
  • Custom Prefix: You can change this using the LABEL_PREFIX environment variable.

In the examples below, the default prefix cloudflare.tunnel is used. If you set a custom prefix (e.g., LABEL_PREFIX=cf.ingress), replace cloudflare.tunnel with cf.ingress in your labels.

Core Ingress Labels

These labels are essential for exposing a service's network endpoint:

Label Description Required Example
{prefix}.enable Must be set to "true" for DockFlare to manage this container. Yes cloudflare.tunnel.enable="true"
{prefix}.hostname The public hostname (subdomain) you want to use. Must be within a zone managed by your Cloudflare account. Yes cloudflare.tunnel.hostname="app.example.com"
{prefix}.service The internal network address of the service. Format: protocol://hostname_or_ip:port (e.g., http://my-app:80, https://my-app:443, tcp://host:port, ssh://host:22, rdp://host:3389, http_status:404). DockFlare infers the service type from this prefix (as of v1.8.4). Yes cloudflare.tunnel.service="http://my-app-container:80"

Optional Ingress Configuration Labels

These labels allow for more specific configuration of the ingress rule itself when Cloudflare connects to your origin service:

Label Description Required Example
{prefix}.path (New in v1.8.4) A URL path prefix for this rule. If set, only requests to {hostname}/{path} will match this rule (e.g., /api). DockFlare ensures the path starts with /. See Path-Based Routing for more details and behavior. No cloudflare.tunnel.path="/api/v1"
{prefix}.zonename Specifies the Cloudflare zone (domain name, e.g., example.com) for the hostname. Overrides the default CF_ZONE_ID env var for this rule. No cloudflare.tunnel.zonename="mydomain.org"
{prefix}.no_tls_verify If set to "true", Cloudflare Tunnel will not verify the TLS certificate of an HTTPS internal service. Useful for self-signed certs or plain HTTP origins. No cloudflare.tunnel.no_tls_verify="true"
{prefix}.originsrvname (New in v1.8.5) Specify the Server Name Indication (SNI) Cloudflare should use when establishing a TLS connection to your origin service. Useful if your origin expects a specific hostname for TLS, e.g., if it's behind another proxy or hosts multiple TLS sites on one IP. Only applicable to HTTP/HTTPS services. No cloudflare.tunnel.originsrvname="internal-host.local"

Example of Ingress Labels (combining several options):

labels:
  cloudflare.tunnel.enable: "true"
  cloudflare.tunnel.hostname: "app.example.com"
  cloudflare.tunnel.service: "http://my-internal-app:8080" # Service type (http, https, tcp, etc.) inferred from prefix
  cloudflare.tunnel.path: "/webapp" # Optional path (from v1.8.4)
  cloudflare.tunnel.no_tls_verify: "true" # If internal app is HTTP or self-signed HTTPS
  cloudflare.tunnel.originsrvname: "my-internal-app.local" # SNI if needed for TLS to origin (from v1.8.5)

Access Policy Labels (Zero Trust)

These labels define the initial Cloudflare Access Policy for the exposed hostname. Note: These label-defined policies can be overridden by changes made in the DockFlare Web UI. If a UI override is active, these labels will not be re-applied unless the policy is "Reverted to Labels" via the UI.

These labels configure Cloudflare Access Applications and are distinct from the Ingress Configuration Labels above which configure the Cloudflare Tunnel rules.

Label Description Default Example
{prefix}.access.policy Defines the type of Access Policy. Common values: bypass (public app), authenticate (requires login via configured IdPs), default_tld (inherits from *.yourdomain.com policy, no app created for this specific hostname). If unset, the service is public (no Access App created by DockFlare). (None/Public) cloudflare.tunnel.access.policy="authenticate"
{prefix}.access.name Custom name for the Cloudflare Access Application. DockFlare-{hostname} cloudflare.tunnel.access.name="My Web App Access"
{prefix}.access.session_duration Session duration for the Access Application (e.g., 24h, 30m). 24h cloudflare.tunnel.access.session_duration="1h"
{prefix}.access.app_launcher_visible If "true", the application will be visible in the Cloudflare App Launcher. false cloudflare.tunnel.access.app_launcher_visible="true"
{prefix}.access.allowed_idps Comma-separated list of allowed Identity Provider (IdP) UUIDs. If access.policy="authenticate" and this is not set, it typically allows any configured IdP for the account. (Account Default) cloudflare.tunnel.access.allowed_idps="<IdP_UUID_1>,<IdP_UUID_2>"
{prefix}.access.auto_redirect_to_identity If "true", automatically redirects to the identity provider login page. false cloudflare.tunnel.access.auto_redirect_to_identity="true"
{prefix}.access.custom_rules A JSON string representing an array of Cloudflare Access Policy rules. Overrides access.policy if set to authenticate or bypass for policy decision. See Cloudflare Access Policy Docs for schema. (None) cloudflare.tunnel.access.custom_rules='[{"email":{"email":"user@example.com"},"action":"allow"}]'

Example of Access Policy Labels:

labels:
  # Assuming core ingress labels (enable, hostname, service) are also present
  cloudflare.tunnel.access.policy: "authenticate"
  cloudflare.tunnel.access.session_duration: "8h"
  # cloudflare.tunnel.access.allowed_idps: "YOUR_GITHUB_IDP_UUID_HERE" 
  # This creates an Access Application named "DockFlare-{hostname}"
  # that requires authentication with an 8-hour session.

Labeling Approaches & Precedence

DockFlare supports applying these labels in two main ways:

  1. Basic Usage (Single Domain): Use simple, non-indexed labels ({prefix}.hostname, {prefix}.path, {prefix}.originsrvname, {prefix}.access.policy, etc.) to expose and configure one hostname per container.
  2. Using Multiple Domains (Indexed Labels): Use indexed labels ({prefix}.0.hostname, {prefix}.0.path, {prefix}.0.originsrvname, {prefix}.0.access.policy, then {prefix}.1.hostname, etc.) to expose multiple hostnames from a single container. Each indexed set can have its own full configuration, including its own Ingress and Access Policy settings.
    • If an indexed configuration (e.g., {prefix}.0.access.policy) is set, it takes precedence over any default (non-indexed) {prefix}.access.policy label for that specific indexed hostname. The same applies to ingress labels like {prefix}.0.path or {prefix}.0.originsrvname vs. their default non-indexed counterparts.
    • If an indexed configuration omits a specific label (e.g., {prefix}.0.access.session_duration is not set), it will fall back to the value of the default non-indexed label for that same setting (e.g., {prefix}.access.session_duration) if present. If no default non-indexed label is found for that setting, the application's hardcoded default for that setting will be used (e.g., 24h for session duration).

See the linked pages for detailed examples. Remember that Access Policies defined by any of these labels can be interactively changed and overridden via the Web UI.

Clone this wiki locally