Docker installation

Below we walkthrough how to run Terraform Enterprise on Docker using Docker Compose. You do not have to deploy using Docker Compose, but we recommend it in order to simplify managing the necessary Docker volumes and container configuration.

1. Requirements

Before you begin, ensure you meet the shared requirements and Docker requirements.

2. Set up

Connect to the instance where you will run Terraform Enterprise.
Create a new directory dedicated for Terraform Enterprise Flexible Deployment Option installation files, and change into it.
Create a certs directory and place your TLS certificate (cert.pem), TLS private key (key.pem), and CA certificates bundle (bundle.pem) inside. If you don’t have a CA certificates bundle, just place your TLS certificate (cert.pem) inside bundle.pem instead. When finished, the certs directory should look like this:
```
certs
├── cert.pem
├── key.pem
└── bundle.pem
```
Create a compose.yaml file and populate it with your desired deployment configuration. Be sure to replace values enclosed in <> with your actual values (e.g., Set TFE_HOSTNAME to the DNS hostname you’ll be using to access Terraform Enterprise). Below are Compose examples for each Terraform Enterprise operational mode:

Mounted Disk
External Services
Active/Active
You can also rely on the configuration reference for a detailed breakdown of the whole environment configuration.

3. Download and install

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. Refer to Terraform Enterprise Releases for a list of versions and replace <vYYYYMM-#> with the version you wish to install; latest is not a valid tag.
```
$ docker pull images.releases.hashicorp.com/hashicorp/terraform-enterprise:<vYYYYMM-#>
```

4. Run

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
```
Active/Active only: Repeat the above steps for each node in the installation.

5. Create initial admin user

Provision your first administrative user and start using Terraform Enterprise.

Example configurations

Below we provide several example Docker Compose configurations as a starting point. These examples do not provide an exhaustive list of configuration options. Refer to Configuration Reference for a list of all configuration options.

Please refer to the Docker Compose documentation for further details on installing, configuring, and running Docker Compose.

Note: Docker container lifecycles can be managed through Docker's restart policy. Refer to the Docker documentation for more details. We recommend relying on Docker's native lifecycle management to automatically restart TFE containers that fail due to transient network or infrastructure issues.

Mounted disk

This Compose YAML deploys Terraform Enterprise in mounted disk mode, using a bind mount to make available the disk path used for TFE data storage.

This configuration uses a bind mount to store Terraform Enterprise application data. 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).

---
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:

External services

An external services deployment requires the following:

PostgreSQL database server
Blob Storage (AWS S3, Azure Cloud Storage, Google Cloud Storage, or any S3-compatible storage service)

This Compose YAML deploys Terraform Enterprise in external services mode, expecting that you will bring an external PostgreSQL server and an external S3-compatible object storage server.

---
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:

Active/Active

An active/active deployment requires the following:

PostgreSQL database server
Blob Storage (AWS S3, Azure Cloud Storage, Google Cloud Storage, or any S3-compatible storage service)
Redis version 6 or 7 (Redis Cluster is not currently supported.)

This Compose YAML deploys Terraform Enterprise in active/active mode, expecting that you will bring an external PostgreSQL server, an external S3-compatible object storage server, and an external Redis-compatible caching server.

---
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:

Service Management

This document provides example configuration for using Docker Compose as the management tool to run Terraform Enterprise as a single Docker container. Managing the lifecycle of Docker Compose is outside the scope of this document. For convenience, we have included examples of possible options for managing Docker Compose on your Linux host.

Systemd

You can use systemd to automatically run docker compose on system start using the example below. Save the below file 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

Enable this service with the following command.

$ systemctl enable --now terraform-enterprise