# Terraform Enterprise Self-Hosted

> Infrastructure as Code platform with workspaces, VCS integration, and state management.

- Category: DevOps & CI/CD
- Difficulty: advanced
- Components: terraform-enterprise, postgresql, redis, minio, vault
- Tags: terraform, hashicorp, iac, gitops, state
- Source: https://docker.recipes/devops/terraform-enterprise

## Overview

Terraform Enterprise is HashiCorp's commercial platform for Infrastructure as Code at scale, providing teams with collaborative Terraform workflows, policy enforcement, and centralized state management. This self-hosted deployment combines Terraform Enterprise with PostgreSQL for workspace and run data, Redis for session and cache management, MinIO for S3-compatible object storage of state files and plan outputs, and Vault for secure secrets management across infrastructure deployments. The stack creates a complete GitOps-enabled infrastructure platform where teams can collaborate on Terraform configurations through VCS integration, enforce policies with Sentinel, and maintain audit trails of all infrastructure changes. Organizations choose this self-hosted approach to maintain complete control over their infrastructure automation platform, ensure sensitive state files never leave their network perimeter, and integrate with existing enterprise authentication systems while avoiding the recurring costs of HashiCorp's cloud offering.

## Features

- PostgreSQL backend stores Terraform workspaces, run histories, and configuration metadata with ACID compliance
- Redis provides fast session management for concurrent Terraform operations and workspace locking
- MinIO S3-compatible storage handles Terraform state files, plan outputs, and configuration archives
- Vault integration enables dynamic credential injection for cloud providers during Terraform runs
- Atlantis workflow automation triggers Terraform plans and applies from GitHub pull requests
- Prometheus metrics collection tracks workspace usage, run success rates, and resource provisioning
- Grafana dashboards visualize infrastructure deployment patterns and team productivity metrics
- Isolated network architecture ensures secure communication between Terraform Enterprise and supporting services

## Use cases

- Enterprise teams managing multi-cloud infrastructure with consistent Terraform workflows and approval gates
- Organizations requiring on-premises Infrastructure as Code platform due to compliance or data sovereignty requirements
- DevOps teams implementing GitOps workflows where infrastructure changes flow through version control and peer review
- Companies consolidating Terraform state management from scattered S3 buckets into centralized workspace-based storage
- Engineering organizations enforcing infrastructure policies and cost controls through Sentinel integration
- Teams needing audit trails and approval workflows for infrastructure changes in regulated industries
- Multi-tenant environments where different teams require isolated Terraform workspaces with shared backend services

## Prerequisites

- Minimum 8GB RAM and 4 CPU cores for production Terraform Enterprise workloads with concurrent runs
- GitHub or GitLab repository with admin access for configuring webhooks and access tokens
- Valid Terraform Enterprise license from HashiCorp (commercial product requiring purchase)
- Docker and Docker Compose 3.8+ with sufficient disk space for state files and Terraform providers
- Network access to cloud provider APIs (AWS, Azure, GCP) from Terraform Enterprise container
- Understanding of Terraform workflows, state management, and Infrastructure as Code principles

## docker-compose.yml

```yaml
services:
  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=terraform
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=terraform
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - tfe_net

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    networks:
      - tfe_net

  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      - MINIO_ROOT_USER=${MINIO_USER}
      - MINIO_ROOT_PASSWORD=${MINIO_PASSWORD}
    volumes:
      - minio_data:/data
    networks:
      - tfe_net

  vault:
    image: hashicorp/vault:latest
    cap_add:
      - IPC_LOCK
    environment:
      - VAULT_DEV_ROOT_TOKEN_ID=${VAULT_TOKEN}
    ports:
      - "8200:8200"
    networks:
      - tfe_net

  # Note: TFE requires license
  # Using open-source Atlantis as alternative
  atlantis:
    image: ghcr.io/runatlantis/atlantis:latest
    ports:
      - "4141:4141"
    environment:
      - ATLANTIS_GH_USER=${GITHUB_USER}
      - ATLANTIS_GH_TOKEN=${GITHUB_TOKEN}
      - ATLANTIS_REPO_ALLOWLIST=github.com/your-org/*
      - ATLANTIS_ATLANTIS_URL=http://localhost:4141
    volumes:
      - atlantis_data:/atlantis
    networks:
      - tfe_net

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - prometheus_data:/prometheus
    networks:
      - tfe_net

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
    volumes:
      - grafana_data:/var/lib/grafana
    networks:
      - tfe_net

volumes:
  postgres_data:
  redis_data:
  minio_data:
  atlantis_data:
  prometheus_data:
  grafana_data:

networks:
  tfe_net:
```

## .env

```bash
# Terraform Enterprise / Atlantis
POSTGRES_PASSWORD=secure_postgres_password
MINIO_USER=minioadmin
MINIO_PASSWORD=secure_minio_password
VAULT_TOKEN=dev_root_token
GITHUB_USER=your_github_username
GITHUB_TOKEN=your_github_token
GRAFANA_PASSWORD=secure_grafana_password

# Atlantis at http://localhost:4141
# MinIO at http://localhost:9001
```

## Usage notes

- Atlantis at http://localhost:4141
- MinIO for state storage at http://localhost:9001
- Vault for secrets at http://localhost:8200
- Configure GitHub webhooks for PRs
- Use atlantis.yaml for workflow config

## Troubleshooting

- Terraform runs failing with 'unable to lock state': Check Redis connectivity and ensure workspace isn't locked by another operation in the UI
- MinIO bucket access errors during state operations: Verify MINIO_ROOT_USER and MINIO_ROOT_PASSWORD environment variables match Terraform Enterprise S3 configuration
- Atlantis webhook not triggering on pull requests: Confirm GitHub webhook URL points to correct port 4141 and webhook secret matches ATLANTIS_GH_TOKEN
- PostgreSQL connection timeouts during workspace operations: Increase PostgreSQL max_connections and shared_buffers for concurrent Terraform runs
- Vault secrets not available in Terraform runs: Ensure Vault token has appropriate policies and Terraform Enterprise can reach Vault on port 8200
- Large Terraform state files causing MinIO upload failures: Increase MinIO memory limits and configure multipart upload thresholds in Terraform Enterprise

