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
) insidebundle.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:Pull the Terraform Enterprise image from the registry.
Apply the deployment configuration
Spin up your Terraform Enterprise container by running:
In a separate terminal session you can monitor the logs by running the following command:
Monitor the health of the application until it starts reporting healthy with the following command:
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
:
Run the following command to enable the service:
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 ``:
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.
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.
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.