Environment Variables

Relevant source files

• .env.sample
• .gitignore
• README.md

This document explains the environment variables used by the Docker MQTT Mosquitto Cloudflare Tunnel system, how to configure them, and their role in service authentication and operation.

Environment variables provide configuration values to the Docker containers at runtime. In this system, the primary use of environment variables is to supply the Cloudflare tunnel authentication token to the cloudflared service without hardcoding credentials in version-controlled files.

For information about obtaining the Cloudflare tunnel token from the Zero Trust dashboard, see Cloudflare Tunnel Configuration. For information about version control practices that protect secrets, see Version Control Practices.

Sources : .env.sample1 README.md51

Environment Variables Overview

The system uses a single environment variable that must be configured before deployment:

Sources : .env.sample1 README.md51

Configuration File Structure

The environment variable configuration follows a template-based approach to separate public documentation from private secrets:

Diagram: Environment Variable Configuration Flow

graph LR
    Sample[".env.sample\n(Version Controlled)"]
Env[".env\n(Not Version Controlled)"]
GitIgnore[".gitignore"]
ComposeYML["docker-compose.yml"]
CFService["cloudflared service"]
Sample -->|Developer copies| Env
 
   GitIgnore -->|Excludes| Env
 
   Env -->|Provides environment variables| ComposeYML
 
   ComposeYML -->|Injects CLOUDFLARE_TUNNEL_TOKEN| CFService
    
 
   Sample -.->|Committed to Git| Repo["GitHub Repository"]
Env -.->|Never committed| Repo

The .env.sample file serves as a template showing the required structure, while the actual .env file contains the real credentials and is excluded from version control by .gitignore.

Sources : .env.sample1 .gitignore1 README.md51

Setting Up the .env File

Step 1: Locate the Template

The repository contains a template file at .env.sample:1-2 with the following structure:

CLOUDFLARE_TUNNEL_TOKEN=your_token

Step 2: Create the .env File

Copy the template to create your local environment configuration:

Step 3: Populate the Token Value

Replace your_token with the actual tunnel token obtained from the Cloudflare Zero Trust dashboard. The token is a long alphanumeric string provided when creating a Cloudflare Tunnel.

Example .env file structure:

CLOUDFLARE_TUNNEL_TOKEN=eyJhIjoiYWJjMTIzZGVmNDU2IiwidCI6IjEyMzQ1Njc4LWFiY2QtZWZnaC1pamtsLW1ub3BxcnN0dXZ3eCIsInMiOiJhYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ejEyMzQ1Njc4OTAifQ==

Note : The actual token will be significantly longer than the example shown.

Step 4: Verify .gitignore Protection

Confirm that .env is listed in .gitignore1 to prevent accidental commits of credentials to version control:

.env

Sources : .env.sample:1-2 README.md51 .gitignore1

Environment Variable Injection Process

Diagram: Environment Variable Injection at Runtime

When docker compose up is executed, Docker Compose reads the .env file from the current directory and makes its variables available to service definitions. The cloudflared service accesses CLOUDFLARE_TUNNEL_TOKEN and passes it to the tunnel client command.

Sources : .env.sample1 README.md51

Variable Reference

CLOUDFLARE_TUNNEL_TOKEN

Purpose : Authenticates the cloudflared container with Cloudflare's tunnel infrastructure, establishing a secure, encrypted connection between the local Docker environment and Cloudflare's edge network.

Format : Base64-encoded JSON string containing:

• Account identifier
• Tunnel identifier
• Secret key

How to Obtain : Generated by Cloudflare Zero Trust dashboard when creating a new tunnel. See README.md:47-51 for detailed instructions.

Usage in docker-compose.yml : Referenced in the cloudflared service definition as ${CLOUDFLARE_TUNNEL_TOKEN} and passed to the container's command line arguments.

Security Implications :

• Grants full access to the specified Cloudflare tunnel
• Should be treated as a sensitive credential with the same protection as passwords
• Compromise of this token allows unauthorized access to route traffic through your tunnel
• Token rotation requires creating a new tunnel in the Cloudflare dashboard

Sources : .env.sample1 README.md:47-51

Security Considerations

Protection from Version Control

The .env file is explicitly excluded from version control via .gitignore1 to prevent accidental exposure of the tunnel token. The .env.sample template is committed instead, providing documentation without exposing credentials.

Diagram: Version Control Protection Mechanism

graph TB
    subgraph "Version Controlled (Public)"
        Sample[".env.sample\nTemplate with placeholder"]
GitIgnore[".gitignore\nExcludes .env"]
end
    
    subgraph "Local Only (Private)"
        Env[".env\nContains real CLOUDFLARE_TUNNEL_TOKEN"]
end
    
    subgraph "Git Operations"
        Commit["git commit"]
Push["git push"]
end
    
 
   Sample -.->|Can be committed| Commit
 
   GitIgnore -.->|Can be committed| Commit
 
   Env -.->|Blocked by .gitignore| Commit
 
   Commit --> Push

Sources : .gitignore1 .env.sample1

Token Scope

The CLOUDFLARE_TUNNEL_TOKEN grants access only to the specific tunnel for which it was generated. Each tunnel has its own unique token, and tokens cannot be used interchangeably between tunnels.

Environment Variable Storage

Environment variables in Docker containers are:

• Visible in container inspection commands (docker inspect)
• Visible in process listings within the container
• Not persisted to Docker images
• Not logged by Docker daemon (unless explicitly configured)

For enhanced security in production environments, consider using Docker secrets or external secret management systems rather than .env files.

Sources : .env.sample1 .gitignore1

Troubleshooting

Missing .env File

Symptom : docker compose up fails with an error about undefined variables or the cloudflared service fails to start.

Solution : Ensure the .env file exists in the same directory as docker-compose.yml and contains the CLOUDFLARE_TUNNEL_TOKEN variable.

Invalid Token Format

Symptom : The cloudflared service starts but immediately fails with authentication errors.

Solution : Verify that:

1. The token was copied completely from the Cloudflare dashboard (no truncation)
2. No extra spaces or newlines were added
3. The token corresponds to an active tunnel in your Cloudflare account

Token Not Being Read

Symptom : Environment variable appears empty in the container despite being set in .env.

Solution :

1. Verify .env is in the same directory where docker compose up is executed
2. Restart services: docker compose down then docker compose up
3. Check that the variable name matches exactly (case-sensitive): CLOUDFLARE_TUNNEL_TOKEN

Sources : .env.sample1 README.md51