Environment Variables Reference

Relevant source files

• .env.sample
• docker-compose.yml

This document provides a complete technical reference for all environment variables used in the Docker MQTT Mosquitto Cloudflare Tunnel system. It describes each variable's purpose, format, where it is used, and its security implications.

For instructions on creating and configuring your .env file, see Environment Variables. For obtaining the Cloudflare tunnel token value, see Cloudflare Tunnel Configuration. For security considerations regarding environment variable management, see Security Model.

Environment Variable Loading

The system uses environment variables to inject sensitive configuration data into containers at runtime without storing credentials in version-controlled files. Environment variables are loaded from a .env file in the repository root and made available to Docker Compose services.

graph LR
    EnvSample[".env.sample\n(Version Controlled)"]
EnvFile[".env\n(Not Version Controlled)"]
GitIgnore[".gitignore"]
ComposeFile["docker-compose.yml"]
CloudflaredService["cloudflared container"]
EnvSample -->|Template for| EnvFile
 
   GitIgnore -->|Excludes| EnvFile
 
   EnvFile -->|Read by| ComposeFile
 
   ComposeFile -->|Passes to| CloudflaredService

Variable Loading Flow

Sources: docker-compose.yml:1-18 .env.sample:1-3

Docker Compose Integration

The docker-compose.yml file references environment variables using the ${VARIABLE_NAME} syntax and explicitly declares them in the environment section of services that require them.

Sources: docker-compose.yml:14-17 .env.sample1

graph TB
    subgraph "Repository"
        EnvSample[".env.sample\nLine 1: CLOUDFLARE_TUNNEL_TOKEN"]
EnvActual[".env\nContains actual token"]
end
    
    subgraph "docker-compose.yml"
        CommandLine["Line 14: command with ${CLOUDFLARE_TUNNEL_TOKEN}"]
EnvSection["Line 16-17: environment section"]
end
    
    subgraph "Runtime"
        CloudflaredCmd["cloudflared process\ntunnel run --token <value>"]
end
    
 
   EnvSample -.->|Developer copies| EnvActual
 
   EnvActual -->|Docker Compose reads| CommandLine
 
   EnvActual -->|Docker Compose reads| EnvSection
 
   CommandLine -->|Substituted in| CloudflaredCmd
 
   EnvSection -->|Available as env var| CloudflaredCmd

Environment Variables Reference Table

Variable Details

CLOUDFLARE_TUNNEL_TOKEN

Type: String (Base64-encoded JSON)
Required: Yes
Used By: cloudflared container
Defined In: docker-compose.yml14 docker-compose.yml17

Purpose

The CLOUDFLARE_TUNNEL_TOKEN is a cryptographic credential that authenticates the cloudflared container with Cloudflare's edge network. This token establishes trust and authorization for the tunnel to connect, enabling secure traffic routing from Cloudflare's infrastructure to the local mosquitto broker.

Usage Locations

The variable is used in two locations within docker-compose.yml:

1. Command Line Substitution (docker-compose.yml14): The token is interpolated directly into the cloudflared command:

   command: tunnel --no-autoupdate run --token ${CLOUDFLARE_TUNNEL_TOKEN}
   

2. Environment Variable Declaration (docker-compose.yml:16-17): The variable is also declared in the service's environment section, making it available to the container's environment:

Format and Structure

The token is a long string that encodes tunnel configuration and authentication credentials. It typically:

• Contains base64-encoded JSON data
• Includes tunnel ID, account credentials, and routing information
• Length varies but typically exceeds 200 characters
• Does not contain spaces or newlines

Example template from .env.sample1:

CLOUDFLARE_TUNNEL_TOKEN=your_token

How to Obtain

The token is generated by Cloudflare when creating a tunnel through the Zero Trust dashboard. See Cloudflare Tunnel Configuration for detailed instructions on obtaining this value.

Sources: .env.sample1 docker-compose.yml:14-17

Security Considerations

The CLOUDFLARE_TUNNEL_TOKEN is a sensitive credential that must be protected:

• Never commit to version control : The .env file containing actual tokens is excluded by .gitignore
• Access control : Only authorized users should have access to the .env file on the Docker host
• Rotation : If compromised, regenerate the tunnel and token through the Cloudflare dashboard
• Scope : The token grants access to route traffic through the tunnel; protect it with the same rigor as API keys

Validation

The system does not perform local validation of the token format. Validation occurs when the cloudflared container attempts to connect to Cloudflare's network:

• Valid token : Container establishes tunnel connection and enters running state
• Invalid token : Container fails to authenticate and may restart repeatedly (depending on restart policy)
• Missing token : Docker Compose will pass an empty string, causing immediate authentication failure

Check container logs for authentication errors:

Troubleshooting

Common issues related to CLOUDFLARE_TUNNEL_TOKEN:

Sources: docker-compose.yml:14-17 .env.sample1

Environment Variable Lifecycle

Sources: docker-compose.yml:1-18 .env.sample:1-3

Loading Mechanism Details

Docker Compose Variable Resolution

Docker Compose resolves environment variables through a precedence hierarchy:

1. Shell environment variables (highest precedence)
2. .env file in project directory
3. environment section in docker-compose.yml
4. Default values in variable substitution syntax (not used in this project)

The system relies on the .env file method, which is automatically loaded by Docker Compose when present in the same directory as docker-compose.yml.

Variable Substitution Syntax

The ${VARIABLE_NAME} syntax in docker-compose.yml14 triggers Docker Compose to:

1. Read the .env file
2. Find the line CLOUDFLARE_TUNNEL_TOKEN=<value>
3. Extract the value after the = sign
4. Substitute it into the command string

Environment Variable Export

The environment section in docker-compose.yml:16-17 uses shorthand syntax:

This shorthand means: "Export the environment variable named CLOUDFLARE_TUNNEL_TOKEN to the container, using the value from the host environment (which Docker Compose loaded from .env)."

Sources: docker-compose.yml:14-17 .env.sample:1-3

No Other Environment Variables

This system does not use any other environment variables beyond CLOUDFLARE_TUNNEL_TOKEN. Other configuration is managed through:

• mosquitto.conf : Mosquitto broker settings (mosquitto.conf)
• docker-compose.yml : Container orchestration settings (docker-compose.yml:1-18)
• Cloudflare Dashboard : Tunnel routing and public hostname configuration

If you need to add custom environment variables for extensions or modifications, follow the same pattern:

1. Add the variable to .env.sample as a template
2. Add the actual value to .env (which remains untracked)
3. Reference it in docker-compose.yml using ${VARIABLE_NAME} syntax
4. Declare it in the service's environment section if the container needs it as an environment variable

Sources: docker-compose.yml:1-18 .env.sample:1-3

Related Documentation

• Environment Variables : Step-by-step guide for creating and populating the .env file
• Cloudflare Tunnel Configuration : How to obtain the tunnel token value
• Security Model : Security implications of credential management
• Version Control Practices : Explanation of .gitignore and secret protection

Sources: docker-compose.yml:1-18 .env.sample:1-3