Docs
Self-Hosted
Overview

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:

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
  1. Create a pull request with a Terraform code change
  2. Terrateam will automatically run terraform plan and comment back the output
  3. Comment on the pull request with terrateam apply to apply changes
  4. 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
KeyDescription
DB_HOSTDatabase host
DB_NAMEDatabase name
DB_PORTDatabase port
DB_USERDatabase user
DB_PASSDatabase password
GITHUB_APP_IDGithub application id
TERRAT_API_BASETerrateam public-facing URL including a trailing /api e.g. https://terrateam.example.com/api
TERRAT_PORTTerrateam application server port
TERRAT_PYTHON_EXECPython executable
GITHUB_APP_CLIENT_IDGitHub application client id
GITHUB_APP_CLIENT_SECRETGitHub application client secret
GITHUB_APP_PEMGitHub application PEM
GITHUB_WEBHOOK_SECRETGitHub application webhook secret
TERRAT_TELEMETRY_LEVELTelemetry level. Default anonymous. Set to disabled to disable telemetry.
INFRACOST_PRICING_API_ENDPOINTInfracost pricing API endpoint
SELF_HOSTED_INFRACOST_API_KEYSelf-hosted Infracost API key
GITHUB_WEBHOOK_URL_UPDATEOn 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)