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
) insidebundle.pem
instead. When finished, thecerts
directory should look like this: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:Pull the Terraform Enterprise image from the registry.
4. Run
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:
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).
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.
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.
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
:
Enable this service with the following command.