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:
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
- 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)