Terrateam Self-Hosted

Deploy a self-hosted version of Terrateam with Docker. Feature parity with Terrateam Cloud.

Cloud vs. Self-Hosted

There is no difference between Terrateam Cloud and Self-Hosted. Both versions grant you full access to all Terrateam features. No cloud-only features.

Terrateam Self-Hosted is free for forever.

Architecture

The following diagram shows an overview of the Terrateam architecture:

Architecture

The Terrateam application server is horizontally scalable. You can run as many as you'd like as long as they all point to the same PostgreSQL database.

Deployment Steps

Prerequisites

These instructions require you to run commands from a terminal.

1. Create a private Terrateam GitHub application

Terrateam Self-Hosted requires a new Terrateam GitHub application to be created.

Clone the terrateamio/terrateam repository

git clone https://github.com/terrateamio/terrateam.git
cd terrateam

Start the setup container

By default, the GitHub application will be created under your personal user account.

Modify the GH_ORG environment variable in docker-compose.yml to specify a GitHub organization.

docker-compose up setup

Navigate to http://localhost:3000 and follow the setup instructions

💡

Save your GitHub application settings file to a safe place. You'll need it for the next step.

2. Deploy the Terrateam server

The following deployment methods are supported:

Coming soon:

Amazon ECS

Next Steps

GitHub Actions Workflow

Store the Actions workflow file in .github/workflows/terrateam.yml of your repository default branch.

Expand for .github/workflows/terrateam.yaml

##########################################################################
# .github/workflows/terrateam.yml
##########################################################################
# DO NOT MODIFY
#
# THIS FILE SHOULD LIVE IN .github/workflows/terrateam.yml
#
# Looking for the Terrateam configuration file? .terrateam/config.yml.
#
# See https://terrateam.io/docs/configuration for details
##########################################################################
name: 'Terrateam Workflow'
on:
  workflow_dispatch:
    inputs:
      # The work-token and api-base-url are automatically passed in by the Terrateam backend
      work-token:
        description: 'Work Token'
        required: true
      api-base-url:
        description: 'API Base URL'
jobs:
  terrateam:
    permissions: # Required to pass credentials to the Terrateam action
      id-token: write
      contents: read
    runs-on: ubuntu-latest
    timeout-minutes: 1440
    name: Terrateam Action
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - name: Run Terrateam Action
        id: terrateam
        uses: terrateamio/action@v1 # Do not replace with a custom image. Doing so may cause Terrateam to not operate as intended.
        with:
          work-token: '${{ github.event.inputs.work-token }}'
          api-base-url: '${{ github.event.inputs.api-base-url }}'
        env:
          SECRETS_CONTEXT: ${{ toJson(secrets) }}

Cloud Provider

Terrateam needs permission to access your cloud provider in order to make changes with the Terraform CLI.

Start using Terrateam

Create a Pull Request with a Terraform code change

Create a pull request with a Terraform code change
Terrateam will automatically run terraform plan and comment back the output
Comment on the pull request with terrateam apply to apply changes
Merge the pull request

Common Use Cases

Click here to see configurations for common use cases

Configuration

Learn how to fully customize your workflow with our runtime configuration file.

Support

Join our Community Slack or email support if you need help deploying.

Terrateam server

Environment variables

You can customize the Terrateam server using environment variables.

Expand for environment variables

Key	Description
DB_HOST	Database host
DB_NAME	Database name
DB_PORT	Database port
DB_USER	Database user
DB_PASS	Database password
GITHUB_APP_ID	Github application id
TERRAT_API_BASE	Terrateam public-facing URL including a trailing `/api` e.g. `https://terrateam.example.com/api`
TERRAT_PORT	Terrateam application server port
TERRAT_PYTHON_EXEC	Python executable
GITHUB_APP_CLIENT_ID	GitHub application client id
GITHUB_APP_CLIENT_SECRET	GitHub application client secret
GITHUB_APP_PEM	GitHub application PEM
GITHUB_WEBHOOK_SECRET	GitHub application webhook secret
TERRAT_TELEMETRY_LEVEL	Telemetry level. Default `anonymous`. Set to `disabled` to disable telemetry.
INFRACOST_PRICING_API_ENDPOINT	Infracost pricing API endpoint
SELF_HOSTED_INFRACOST_API_KEY	Self-hosted Infracost API key
GITHUB_WEBHOOK_URL_UPDATE	On startup, automatically update the GitHub application webhook URL. Default `true`.

Listeners and endpoints

The Terrateam server listens on two ports:

Nginx reverse proxy port 8080
Terrateam application server port 8180

The following unauthenticated endpoints are included:

/health - Health check port 8080
/metrics - Prometheus metrics port 8180
/nginx_status - Nginx status port 8080

The /api endpoint is where your private GitHub application will deliver webhook events.

This endpoint is protected by your webhook secret.

Cost estimation

The Terrateam server sends cost estimation requests to the Cloud Pricing API (opens in a new tab) endpoint defined by the INFRACOST_PRICING_API_ENDPOINT and SELF_HOSTED_INFRACOST_API_KEY environment variables. The Cloud Pricing API is an open-source service provided by Infracost (opens in a new tab) and is easy to deploy. See their documentation (opens in a new tab) for deployment instructions.

If you prefer to use the public Infracost Pricing API, then set your Infracost API key as a GitHub Secret in your Terraform repository. See the Cost Estimation documentation for details.

Docker

Official Docker image registry path for the Terrateam server: ghcr.io/terrateamio/terrateam:v1 (opens in a new tab)

Reference Docker Compose