Deploy Terraform Enterprise to Docker

This topic describes how to deploy Terraform Enterprise to Docker using Docker Compose. You can use another installation method, but we recommend Docker Compose because it simplifies managing the necessary Docker volumes and container configuration.

Overview

Complete the following steps to install Terraform Enterprise:

Complete the prerequisites
Set up the installation folders and files
Download and install the Docker image
Apply the deployment installation

Complete post installation tasks, such creating the initial admin user account and configuring service management controls.

Prerequisites

Complete the following tasks before attempting to install Terraform Enterprise.

Prepare the deployment environment

Provide a DNS hostname for Terraform Enterprise and the associated TLS certificate. Additionally, you must configure your network so that your host can receive and send traffic. Refer to Prepare the host environment for details about preparing the host environment.

Deploy storage systems for `active` and `external` mode

If you intend to operate Terraform Enterprise in active or external mode, deploy the database and other storage devices so that Terraform can connect to them when the application starts. Refer to Data storage settings overview for additional information.

Create the deployment configuration

Create a deployment configuration file and specify settings for the operational mode, license, TLS certificates, and network configuration. Add any additional configurations necessary for your environment. Refer to Configuration file overview for additional information.

Set up installation folders and files

Connect to the host instance.
Create a dedicated directory for the Terraform Enterprise installation files.
Navigate to the installation directory.
Create a certs directory.
Place your TLS certificate (cert.pem), TLS private key (key.pem), and CA certificates bundle (bundle.pem) inside inside thecerts directory. If you do not have a CA certificates bundle, place your TLS certificate (cert.pem) inside bundle.pem instead.
Place your deployment configuration file into the Terraform Enterprise installation directory. Refer to Example deployment configurations for pre-formatted configurations that you can copy and modify. Refer to the configuration reference for information about all deployment configuration settings.

Download and install the image

Log in to the Terraform Enterprise container image registry, using terraform as the username, and your Hashicorp Terraform Enterprise license as the password:
```
$ echo "<HASHICORP_LICENSE>" |  docker login --username terraform images.releases.hashicorp.com --password-stdin
```

Pull the Terraform Enterprise image from the registry.

$ docker pull images.releases.hashicorp.com/hashicorp/terraform-enterprise:<vYYYYMM-#>

Apply the deployment configuration

Spin up your Terraform Enterprise container by running:
```
$ docker compose up --detach
```
In a separate terminal session you can monitor the logs by running the following command:
```
$ docker compose logs --follow
```
Monitor the health of the application until it starts reporting healthy with the following command:
```
$ docker compose exec tfe tfe-health-check-status
```
If you are operating Terraform in active-active mode, repeat the steps for each node in the installation.

Post installation tasks

Complete the following tasks after the initial installation.

Review startup checks

When you start Terraform Enterprise, several startup checks also run to prevent errors related to invalid configurations or certificates, as well as other issues that could prevent the application from running successfully or safely. Refer to the startup checks reference for additional information.

Create the initial admin user

Provision your first administrative user and start using Terraform Enterprise.

Manage Docker containers

We recommend using Docker's native lifecycle management to automatically restart Terraform Enterprise containers that fail due to transient network or infrastructure issues. You can manage Docker container lifecycles using Docker's restart policy. Refer to the Docker documentation for details.

Manage the Docker service

You can use systemd to automatically run docker compose when the system starts up. Managing the Docker Compose lifecycle is outside the scope of these instructions, but we provide the following example for managing Docker Compose on your Linux host for your convenience.

Store the following configuration as /etc/systemd/system/terraform-enterprise.service:

[Unit]
Description=Terraform Enterprise Service
Requires=docker.service
After=docker.service network.target

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/etc/terraform-enterprise
ExecStart=/usr/local/bin/docker compose up -d
ExecStop=/usr/local/bin/docker compose down
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target

Run the following command to enable the service:

$ systemctl enable --now terraform-enterprise

Route requests to Terraform Enterprise public hostname

You can direct requests sent to Terraform Enterprise's fully qualified domain name to the instance's internal IP address. This is useful for cloud environments where HTTP clients running on instances behind a load balancer cannot send requests to the public hostname of that load balancer.

Add the TFE_RUN_PIPELINE_DOCKER_EXTRA_HOSTS variable to your deployment configuration file and specify a comma-separated list of additional hosts to send requests to. Format each item in the list as HOST:IP. The IP must be a routable address for the instance where Terraform Enterprise is running.

The following example sends requests to the fully-qualified domain name ``:

name: terraform-enterprise
services:
  tfe:
    image: images.releases.hashicorp.com/hashicorp/terraform-enterprise:<vYYYYMM-#>
    environment:
      TFE_HOSTNAME: "terraform.example.com"
      TFE_RUN_PIPELINE_DOCKER_EXTRA_HOSTS: "terraform.example.com:<IP.ADDRESS.OF.INSTANCE>"

This configuration injects /etc/hosts entries into the ephemeral Docker containers used to launch the underlying terraform binary. Refer to the TFE_RUN_PIPELINE_DOCKER_EXTRA_HOSTS reference for additional information.

Example deployment configurations

You can copy one of the following example configurations and modify the values to per your environment. Refer to Configuration Reference for a list of all configuration options.

Refer to the Docker Compose documentation for details on installing, configuring, and running Docker Compose.

Example `disk` mode configuration

The following compose configuration deploys Terraform Enterprise in disk mode using a bind mount to make the disk path used for Terraform Enterprise data storage available. The path you specify as the source of the bind mount must exist on the instance running Terraform Enterprise. This path must be backed by durable storage as provided by your cloud provider, such as Elastic Block Storage for AWS.

# Caution: $ is a reserved character in docker compose files for variable interpolation and can be escaped by using $$.
# https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/
---
name: terraform-enterprise
services:
  tfe:
    image: images.releases.hashicorp.com/hashicorp/terraform-enterprise:<vYYYYMM-#>
    environment:
      TFE_LICENSE: "<Hashicorp license>"
      TFE_HOSTNAME: "<TFE hostname (DNS) e.g. terraform.example.com>"
      TFE_ENCRYPTION_PASSWORD: '<Encryption password>'
      TFE_OPERATIONAL_MODE: "disk"
      TFE_DISK_CACHE_VOLUME_NAME: "${COMPOSE_PROJECT_NAME}_terraform-enterprise-cache"
      TFE_TLS_CERT_FILE: "/etc/ssl/private/terraform-enterprise/cert.pem"
      TFE_TLS_KEY_FILE: "/etc/ssl/private/terraform-enterprise/key.pem"
      TFE_TLS_CA_BUNDLE_FILE: "/etc/ssl/private/terraform-enterprise/bundle.pem"
      TFE_IACT_SUBNETS: "<IACT subnet, eg. 10.0.0.0/8,192.168.0.0/24>"
    cap_add:
      - IPC_LOCK
    read_only: true
    tmpfs:
      - /tmp:mode=01777
      - /run
      - /var/log/terraform-enterprise
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - type: bind
        source: /var/run/docker.sock
        target: /run/docker.sock
      - type: bind
        source: ./certs
        target: /etc/ssl/private/terraform-enterprise
      - type: bind
        source: <mounted_disk_path_on_host>
        target: /var/lib/terraform-enterprise
      - type: volume
        source: terraform-enterprise-cache
        target: /var/cache/tfe-task-worker/terraform
volumes:
  terraform-enterprise-cache:

Example `external` mode configuration

The following compose configuration deploys Terraform Enterprise in external mode and expects to connect to an external PostgreSQL server and an external S3-compatible object storage server.

# Caution: $ is a reserved character in docker compose files for variable interpolation and can be escaped by using $$.
# https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/
---
name: terraform-enterprise
services:
  tfe:
    image: images.releases.hashicorp.com/hashicorp/terraform-enterprise:<vYYYYMM-#>
    environment:
      TFE_LICENSE: "<Hashicorp license>"
      TFE_HOSTNAME: "<TFE hostname (DNS) e.g. terraform.example.com>"
      TFE_ENCRYPTION_PASSWORD: '<Encryption password>'
      TFE_OPERATIONAL_MODE: "external"
      TFE_DISK_CACHE_VOLUME_NAME: "${COMPOSE_PROJECT_NAME}_terraform-enterprise-cache"
      TFE_TLS_CERT_FILE: "/etc/ssl/private/terraform-enterprise/cert.pem"
      TFE_TLS_KEY_FILE: "/etc/ssl/private/terraform-enterprise/key.pem"
      TFE_TLS_CA_BUNDLE_FILE: "/etc/ssl/private/terraform-enterprise/bundle.pem"
      TFE_IACT_SUBNETS: "<IACT subnet, eg. 10.0.0.0/8,192.168.0.0/24>"

      # Database settings. See the configuration reference for more settings.
      TFE_DATABASE_USER: "<Database user e.g. postgres>"
      TFE_DATABASE_PASSWORD: '<Database password e.g. postgres>'
      TFE_DATABASE_HOST: "<Database hostname and port e.g. postgres:5432>"
      TFE_DATABASE_NAME: "<Database name e.g. hashicorp>"
      TFE_DATABASE_PARAMETERS: "<Database parameters e.g. sslmode=disable>"

      # Object storage settings. See the configuration reference for more settings.
      TFE_OBJECT_STORAGE_TYPE: "s3"
      TFE_OBJECT_STORAGE_S3_ACCESS_KEY_ID: "<AWS Access Key ID>"
      TFE_OBJECT_STORAGE_S3_SECRET_ACCESS_KEY: '<AWS Secret Access Key>'
      TFE_OBJECT_STORAGE_S3_REGION: "<AWS Region e.g.us-east-1>"
      TFE_OBJECT_STORAGE_S3_BUCKET: "<Bucket name>"
    cap_add:
      - IPC_LOCK
    read_only: true
    tmpfs:
      - /tmp:mode=01777
      - /run
      - /var/log/terraform-enterprise
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - type: bind
        source: /var/run/docker.sock
        target: /run/docker.sock
      - type: bind
        source: ./certs
        target: /etc/ssl/private/terraform-enterprise
      - type: volume
        source: terraform-enterprise-cache
        target: /var/cache/tfe-task-worker/terraform
volumes:
  terraform-enterprise-cache:

Example `active-active` mode configuration

The following compose configuration deploys Terraform Enterprise in active-active mode and expects to connect to an external PostgreSQL server, external S3-compatible object storage server, and external Redis-compatible caching server.

# Caution: $ is a reserved character in docker compose files for variable interpolation and can be escaped by using $$.
# https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/
---
name: terraform-enterprise
services:
  tfe:
    image: images.releases.hashicorp.com/hashicorp/terraform-enterprise:<vYYYYMM-#>
    environment:
      TFE_LICENSE: "<Hashicorp license>"
      TFE_HOSTNAME: "<TFE hostname (DNS) e.g. terraform.example.com>"
      TFE_ENCRYPTION_PASSWORD: '<Encryption password>'
      TFE_OPERATIONAL_MODE: "active-active"
      TFE_DISK_CACHE_VOLUME_NAME: "${COMPOSE_PROJECT_NAME}_terraform-enterprise-cache"
      TFE_TLS_CERT_FILE: "/etc/ssl/private/terraform-enterprise/cert.pem"
      TFE_TLS_KEY_FILE: "/etc/ssl/private/terraform-enterprise/key.pem"
      TFE_TLS_CA_BUNDLE_FILE: "/etc/ssl/private/terraform-enterprise/bundle.pem"
      TFE_IACT_SUBNETS: "<IACT subnet, eg. 10.0.0.0/8,192.168.0.0/24>"

      # Database settings. See the configuration reference for more settings.
      TFE_DATABASE_USER: "<Database user e.g. postgres>"
      TFE_DATABASE_PASSWORD: '<Database password e.g. postgres>'
      TFE_DATABASE_HOST: "<Database hostname and port e.g. postgres:5432>"
      TFE_DATABASE_NAME: "<Database name e.g. hashicorp>"
      TFE_DATABASE_PARAMETERS: "<Database parameters e.g. sslmode=disable>"

      # Object storage settings. See the configuration reference for more settings.
      TFE_OBJECT_STORAGE_TYPE: "s3"
      TFE_OBJECT_STORAGE_S3_ACCESS_KEY_ID: "<AWS Access Key ID>"
      TFE_OBJECT_STORAGE_S3_SECRET_ACCESS_KEY: "<AWS Secret Access Key>"
      TFE_OBJECT_STORAGE_S3_REGION: "<AWS Region e.g.us-east-1>"
      TFE_OBJECT_STORAGE_S3_BUCKET: "<Bucket name>"

      # Redis settings. See the configuration reference for more settings.
      TFE_REDIS_HOST: "<Redis hostname and port e.g. redis:6379>"
      TFE_REDIS_USER: "<Redis username>"
      TFE_REDIS_PASSWORD: "<Redis password>"
      TFE_REDIS_USE_TLS: "<To use tls? e.g. false>"
      TFE_REDIS_USE_AUTH: "<To use customized credential to authenticate? e.g. false>"

      # Vault cluster settings.
      # If you are using the default internal vault, this should be the private routable IP address of the node itself.
      TFE_VAULT_CLUSTER_ADDRESS: "https://<private_ip_of_the_node>:8201"
    cap_add:
      - IPC_LOCK
    read_only: true
    tmpfs:
      - /tmp:mode=01777
      - /run
      - /var/log/terraform-enterprise
    ports:
      - "80:80"
      - "443:443"
      - "8201:8201"
    volumes:
      - type: bind
        source: /var/run/docker.sock
        target: /run/docker.sock
      - type: bind
        source: ./certs
        target: /etc/ssl/private/terraform-enterprise
      - type: volume
        source: terraform-enterprise-cache
        target: /var/cache/tfe-task-worker/terraform
volumes:
  terraform-enterprise-cache: