Terraform Enterprise Fails to Start With Nginx Permissions Error

Problem

Terraform Enterprise fails to start, and the Nginx service logs show a permission denied error when creating a temporary directory.

{"log":"nginx: [emerg] mkdir() \"/var/run/terraform-enterprise/tmp\" failed (13: Permission denied)","component":"nginx"}

Prerequisites

• Terraform Enterprise version v202404-2 or newer.
• A Flexible Deployment Options installation (Docker-based).

Cause

Running the Terraform Enterprise container as the root user causes this issue. In Terraform Enterprise v202404-2 and newer, services run under unprivileged user accounts. For example, Nginx runs as the unprivileged nginx user, which is a member of the root group.

$ docker exec -ti terraform-enterprise id nginx
## uid=999(nginx) gid=999(nginx) groups=999(nginx),0(root)

Terraform Enterprise configures Nginx to use the /var/run/terraform-enterprise/tmp path for storing temporary files. During startup, Nginx attempts to create this directory. However, when the container runs as the root user, a required startup procedure that assigns correct write permissions to the /var/run/terraform-enterprise directory is skipped. As a result, the nginx process lacks the necessary permissions to create a subdirectory.

An inspection of the directory permissions shows that only the root user has write access.

$ docker exec -ti terraform-enterprise ls -ld /var/run/terraform-enterprise/
## drwxr-xr-x 23 root root 480 Feb 25 15:41 /var/run/terraform-enterprise/

The following log message from the container's startup sequence confirms that it was not started as the default terraform-enterprise user.

Not running as builtin tfe user, will attempt to create scratch directories but skipping ownership changes...

Solution

To resolve this issue, ensure the Terraform Enterprise container runs as its default unprivileged user, terraform-enterprise. Remove any user directive from your configuration that specifies the root user or a specific UID/GID.

Docker Compose Example

In your docker-compose.yml or equivalent file, locate the service definition for Terraform Enterprise and remove the user: root line.

Incorrect Configuration:

services:
  <TFE_SERVICE_NAME>:
    ## ... other configuration
    user: root

Correct Configuration:

After removing the line, your configuration should not specify a user, allowing the container to use its default user.

services:
  <TFE_SERVICE_NAME>:
    ## ... other configuration
    ## The 'user' directive has been removed.

After applying this change, restart the Terraform Enterprise container.

Additional Information

• For more details on deployment configurations, refer to the Terraform Enterprise deployment overview.