Best practices to avoid malformed docker-compose.yaml leading to startup issues

Introduction

When building containerized applications using Docker Compose, the docker-compose.yaml file serves as the blueprint for defining services, networks, volumes, and environments. Writing a valid and effective Compose file requires balancing two specifications: the YAML language and Docker Compose’s schema.

This article walks through the core principles for writing a proper docker-compose.yaml file, highlights common mistakes, and explains how to avoid them.

Prerequisites

• Migrating Terraform Enterprise from Replicated to FDO Docker
• Deploying FDO Docker
• Utilizing YAML

YAML Fundamentals: Structure and Syntax

YAML is indentation-sensitive and whitespace-driven. A few key rules:

• Indentation must use spaces (not tabs) — consistent 2-space indentation is recommended
• Colons (:) separate keys and values
• Lists use dashes (-) with indentation
• Use quotes to force a string (e.g., 10 → "10") where needed
• Use quotes if your value includes special characters (: { } [ ] , & * # ? | - < > = ! % @ \)
• Use single quotes ('...') to avoid interpretation of escape characters like \n

Escape Characters in YAML and Compose

Example: Correctly Structured docker-compose.yaml

Review Docker’s Compose file reference.

HashiCorp provides working configurations for different Terraform Enterprise (TFE) deployment modes: Mounted Disk, External Services, and Active-Active.

name: terraform-enterprise
# Top-level key for defining container services
services:
# Service named 'tfe'; with 2-space indentation
  tfe:
# Optional command override to keep the container running indefinitely for debugging  
  #  command: ["sleep", "infinity"]
# Replace with a valid tag — required 'v' prefix, e.g. v202507-1
    image: images.releases.hashicorp.com/hashicorp/terraform-enterprise:v202507-1
# Recommended YAML mapping-style:
    environment:
# Double quotes allow flexible parsing and are safe for colons and special characters    
      TFE_HOSTNAME: "usingdoublequotes.tfe.io"
# Use single quotes to prevent YAML or shell interpreting $, \, or ! as special characters     
      TFE_DATABASE_PASSWORD: 'MyP@ssw0rd$$2025\\Secure!' # Literal value passed: MyP@ssw0rd$2025\Secure! 

# Incorrect list-style format (commented out for reference):
      # - TFE_HOSTNAME=usingdoublequotes.tfe.io
      # - TFE_DATABASE_PASSWORD=MyP@ssw0rd$$2025\\Secure!
# This list-style is valid but treated as plain strings, not proper K:V pairs.
# Avoid this if values contain colons, special characters, or require escaping.
    
# List format
    ports:
      - "80:80"   # Host port 80 maps to container port 80
      - "443:443" 

Tip: Migrating from Replicated to FDO Docker

When migrating, the configuration you export with:

docker exec -it terraform-enterprise tfectl app-config --format docker > docker-compose.yaml

will include many defaults and verbose K:V entries.

Two practical options:

1. Copy only the required settings into a clean Compose file based on one of the HashiCorp examples above. Expand your configuration using the TFE Configuration Reference, avoiding any K:V pairs that reflect default values.
2. Use the Configuration Reference to identify and delete any exported variables that are already set to their default values.

Symptoms of a Malformed docker-compose.yaml

Potential error messages seen in logs:

terraform-enterprise: check failed: name=upgrade duration=1m30.000494959s err="timeout: context deadline exceeded"
terraform-enterprise: the following startup checks failed: checks=["database", "upgrade"]
terraform-enterprise: startup: error="startup checks failed"
INFO waiting for fluent-bit, logwatch, terraform-enterprise to die

Common issues may include:

• Using K=V syntax instead of YAML's correct K: V format
• Improper quoting or escaping of special characters like $ and \

Solutions:

• Export your current configuration: 
  docker exec -it terraform-enterprise tfectl app-config --format docker > docker-compose.yaml 
  Then copy only the relevant sections into a new file based on:

  • Mounted Disk
  • External Services
  • Active-Active

  Then expand only what’s necessary, referring to the Configuration Reference.

• Rebuild your docker-compose.yaml file from scratch using the examples above as a guide.