Skip to content

ContainerLabels.md

Jump to bottom
Chris edited this page Jun 22, 2025 · 9 revisions

Container Labels

Docker labels are the primary mechanism for instructing DockFlare which containers to expose and how to configure them. By reading these labels, DockFlare automates the creation of DNS records, Cloudflare Tunnel ingress rules, and Zero Trust Access policies.

Label Prefix

DockFlare looks for labels starting with a specific prefix.

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

In the examples below, the default prefix dockflare. is used. If you set a custom prefix (e.g., LABEL_PREFIX=cf.ingress), replace dockflare. with cf.ingress. in your labels. Note that the trailing dot is handled automatically.

Ingress Configuration Labels

These labels define the public endpoint and how Cloudflare connects to your internal service.

Label Description Required Example
{prefix}.enable Must be set to "true" for DockFlare to manage this container. Yes dockflare.enable="true"
{prefix}.hostname The public hostname you want to use. Must be within a zone managed by your Cloudflare account. Yes dockflare.hostname="app.example.com"
{prefix}.service The internal network address of the service. Format: protocol://host:port. Valid protocols: http, httpss, tcp, ssh, rdp, http_status. Yes dockflare.service="http://my-app:80"
{prefix}.path A URL path for this rule. If set, only requests to {hostname}/{path} will match this rule. No dockflare.path="/api"
{prefix}.zonename Specifies the Cloudflare zone (e.g., example.com) for the hostname, overriding the global CF_ZONE_ID. No dockflare.zonename="other-domain.org"
{prefix}.no_tls_verify If "true", Cloudflare will not verify the TLS certificate of an HTTPS origin. Useful for self-signed certificates. No dockflare.no_tls_verify="true"
{prefix}.originsrvname The Server Name Indication (SNI) Cloudflare should use for the TLS handshake with an HTTPS origin. No dockflare.originsrvname="internal.local"

Basic Ingress Example:

services:
  my-app:
    image: nginx
    labels:
      - "dockflare.enable=true"
      - "dockflare.hostname=my-app.example.com"
      - "dockflare.service=http://my-app:80"

Access Policy Labels (Zero Trust)

These labels define the initial Cloudflare Access Policy for the endpoint. Note: These can be overridden by changes made in the DockFlare Web UI.

Label Description Default Example
{prefix}.access.policy Sets the policy type. Common values: bypass (public), authenticate (login required), default_tld (inherits from a *.yourdomain.com policy). If unset, no Access App is created. (None) dockflare.access.policy="authenticate"
{prefix}.access.name A custom name for the Cloudflare Access Application. DockFlare-{hostname} dockflare.access.name="My Web App"
{prefix}.access.session_duration The session duration for the Access Application (e.g., 24h, 30m). 24h dockflare.access.session_duration="8h"
{prefix}.access.app_launcher_visible If "true", the app appears in the Cloudflare App Launcher. false dockflare.access.app_launcher_visible="true"
{prefix}.access.allowed_idps A comma-separated list of allowed Identity Provider (IdP) UUIDs. (All) dockflare.access.allowed_idps="<IdP_UUID>"
{prefix}.access.custom_rules A JSON string representing an array of Access Policy rules. Overrides the access.policy setting. (None) dockflare.access.custom_rules='[{"email":{"email":"[email protected]"},"action":"allow"}]'

Example with an Access Policy:

services:
  secure-app:
    image: some-private-app
    labels:
      - "dockflare.enable=true"
      - "dockflare.hostname=secure.example.com"
      - "dockflare.service=http://secure-app:8080"
      # Secure this service with Cloudflare Access
      - "dockflare.access.policy=authenticate"
      - "dockflare.access.session_duration=1h"

Indexed Labels for Multiple Rules

To define multiple, distinct rules from a single container, use indexed labels. Each index (0, 1, 2, etc.) creates a completely separate rule.

  • An indexed setting (e.g., {prefix}.0.path) always overrides a default, non-indexed setting ({prefix}.path) for that specific rule.
  • If an indexed rule omits a setting (e.g., {prefix}.0.path is not set), it will fall back to the default non-indexed version if it exists.

Example of Indexed Labels:

services:
  multi-service-gateway:
    image: nginx
    labels:
      - "dockflare.enable=true"

      # --- Rule 0: The API ---
      - "dockflare.0.hostname=api.example.com"
      - "dockflare.0.service=http://multi-service-gateway:80"
      - "dockflare.0.access.policy=authenticate" # API is secure

      # --- Rule 1: The Public Website ---
      - "dockflare.1.hostname=www.example.com"
      - "dockflare.1.service=http://multi-service-gateway:80"
      # No access.policy label, so this rule will be public.
Clone this wiki locally