Docker installation
Below we walk through 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
) insidebundle.pem
instead. When finished, thecerts
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., SetTFE_HOSTNAME
to the DNS hostname you’ll be using to access Terraform Enterprise). Below are Compose examples for each Terraform Enterprise operational mode:
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.
$ 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 Terraform Enterprise 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 Terraform Enterprise 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
Traffic Hairpinning
Terraform Enterprise on Replicated deployments offers a configuration option called hairpin_addressing, which directed traffic destined for the installation's fully qualified domain name toward 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.
In Terraform Enterprise Flexible Deployment Options, this configuration option
is no longer exposed. Operators can, however, mimic this functionality by
using the TFE_RUN_PIPELINE_DOCKER_EXTRA_HOSTS
configuration option. This configuration injects /etc/hosts
entries into the
ephemeral Docker containers used to launch the underlying terraform
binary,
mimicking the behavior of the hairpin_addressing
configuration option. Extra
hosts entries are added in the form of HOST:IP
; the value for the IP must be
a routable address for the instance where Terraform Enterprise is running. An example is shown below:
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>"