Resolving TFE Password Issues in FDO Docker deployment

Problem

During the installation of Terraform Enterprise (TFE) in a Docker environment, the container may stop unexpectedly. When you review the logs, you may see an error similar to the following.

"Error reading Vault configuration: failed decrypting unseal key: could not decrypt ciphertext: chacha20poly1305: message authentication failed"

[ERROR] terraform-enterprise: check failed: name=database duration=1m30.008561657s err=\"timeout: context deadline exceeded\""}

Cause

This issue occurs when a password configured in the Docker Compose file contains a dollar sign ($). Docker Compose interprets strings like $VAR or ${VAR} as environment variables for interpolation. If a password contains a $ that is not intended for variable substitution, Docker Compose may replace it with an empty string, causing authentication to fail.

For example, a password set like this will cause an issue.

version: '3.8'
services:
  my_service:
    image: my_image
    environment:
      - PASSWORD=$mypassword

To confirm if this is the cause, run the following command while the container is running and inspect the values for environment variables such as TFE_ENCRYPTION_PASSWORD, TFE_DATABASE_PASSWORD, or TFE_REDIS_PASSWORD.

$ docker inspect terraform-enterprise-tfe-1

Solutions

There are two primary methods to resolve this issue by ensuring the dollar sign is treated as a literal character.

Solution 1: Use a Double Dollar Sign to Escape

To include a literal dollar sign in your password, use a double dollar sign ($$). This syntax tells Docker Compose to escape the character and treat it as a single literal $.

Update your Docker Compose file as shown in this example.

version: '3.8'
services:
  my_service:
    image: my_image
    environment:
      - PASSWORD=$$mypassword

Solution 2: Use Single Quotes to Prevent Interpolation

Enclosing the password value in single quotes (') prevents Docker Compose from performing variable interpolation. The string will be treated literally, preserving any dollar signs.

Update your Docker Compose file as shown in this example.

version: '3.8'
services:
  my_service:
    image: my_image
    environment:
      - PASSWORD='$mypassword'

Additional Information

For more details on how Docker Compose handles environment variables, refer to the official Docker Compose Interpolation Syntax documentation.