Skip to content

Overview

Terrateam Self-Hosted is the on-premise, privately hosted version of Terrateam.

Prerequisites

Before you begin, ensure you have the following:

  • Docker
  • Docker Compose

Step 1: Create a Private Terrateam GitHub Application

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

1. Clone the terrateamio/terrateam repository:

Terminal window
git clone https://github.com/terrateamio/terrateam.git
cd terrateam/docker/terrat

2. Start the setup container:

Terminal window
GH_ORG=YOUR_GITHUB_ORG docker-compose up setup

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

Step 2: Deploy the Terrateam Server

Choose one of the following deployment methods based on your requirements and infrastructure setup:

Option 1: Docker Compose

1. Save your private Terrateam GitHub application settings file to .env in your terrateam/docker/terrat directory next to docker-compose.yml: Your .env file should look like this but with actual values:

GITHUB_APP_ID=""
GITHUB_APP_PEM=""
GITHUB_WEBHOOK_SECRET=""
GITHUB_APP_CLIENT_ID=""
GITHUB_APP_CLIENT_SECRET=""

2. Register an Ngrok account and create an auth token.

3. Start Terrateam:

Terminal window
NGROK_AUTHTOKEN=<YOUR-NGROK-AUTH-TOKEN> docker-compose up server -d

5. When the Terrateam server starts up, it will try to update the GitHub application Webhook URL using the Ngrok endpoint, which in turn populates the TERRAT_API_BASE environment variable. To disable, set the GITHUB_WEBHOOK_URL_UPDATE environment variable to FALSE.

Option 2: Kubernetes

1. Source your private Terrateam GitHub application settings file:

Terminal window
source ./dotenv

2. Create your Terrateam private GitHub application secrets:

Terminal window
kubectl create secret generic terrateam-github-app-pem --from-literal=pem="$GITHUB_APP_PEM"
kubectl create secret generic terrateam-github-webhook-secret --from-literal=secret="$GITHUB_WEBHOOK_SECRET"
kubectl create secret generic terrateam-github-app-client-secret --from-literal=secret="$GITHUB_APP_CLIENT_SECRET"
kubectl create secret generic terrateam-github-app-client-id --from-literal=id="$GITHUB_APP_CLIENT_ID"
kubectl create secret generic terrateam-github-app-id --from-literal=id="$GITHUB_APP_ID"

3. Create your Terrateam database password secret:

Terminal window
kubectl create secret generic terrateam-db-password --from-literal=password="STRONG_PASSWORD_HERE"

4. Add the Terrateam Helm repository:

Terminal window
helm repo add terrateamio https://terrateamio.github.io/helm-charts/
helm repo update

5. Install the Helm chart based on your specific setup:

GKE with an HTTPS load balancer and managed certificate

- Create a global static IP address:

Terminal window
gcloud compute addresses create terrateam-static-ip --global

- Show the IP:

Terminal window
gcloud compute addresses describe terrateam-static-ip --global

- Add the global static IP to a DNS zone you control, for example, as terrateam.example.com

- Install the Helm chart:

Terminal window
helm install terrateam terrateamio/terrateam \
--set server.dns_name="terrateam.example.com" \
--set certificate.enabled="true" \
--set ingress.enabled="true" \
--set ingress.annotations."networking\.gke\.io\/managed-certificates"="terrateam-ingress-certificate" \
--set ingress.annotations."kubernetes\.io\/ingress\.global-static-ip-name"="terrateam-static-ip" \
--set ingress.annotations."kubernetes\.io\/ingress\.class"="gce" \
--set-string ingress.annotations."kubernetes\.io\/ingress\.allow-http"="false"

Using Google-managed SSL certificates with Ingress can take up to 60 minutes to configure. The Ingress can be in a ready state while the certificate is still in the provisioning state.

Without Ingress
Terminal window
helm install terrateam terrateamio/terrateam --set server.dns_name="terrateam.example.com"

You can use NGINX-ingress and cert-manager to expose the terrateam-server service.

Custom

Specify a custom my-values.yaml for installation:

Terminal window
helm inspect values terrateamio/terrateam > my-values.yaml
helm install -f my-values.yaml terrateam terrateamio/terrateam

6. When the Terrateam server starts up, it will try to update the GitHub application Webhook URL using the Helm chart value server.dns_name, which in turn populates the TERRAT_API_BASE environment variable. To disable, set the GITHUB_WEBHOOK_URL_UPDATE environment variable to FALSE.

Option 3: Manual Instructions

Components

Terrateam consists of two components:

PostgreSQL Database

Set the host auth method to md5

Terminal window
echo "host all all all md5" >> pg_hba.conf

Create the Terrateam database

postgres=# create database terrateam;
CREATE DATABASE
postgres=#

Set the password authentication method

postgres=# ALTER SYSTEM SET password_encryption = 'md5';
ALTER SYSTEM
postgres=# SELECT pg_reload_conf();
pg_reload_conf
----------------
t
(1 row)
postgres=# SHOW password_encryption;
password_encryption
---------------------
md5
(1 row)
postgres=#

Create the Terrateam user

CREATE USER terrateam WITH ENCRYPTED PASSWORD 'terrateam';
GRANT ALL PRIVILEGES ON DATABASE terrateam TO terrateam;
GRANT ALL ON SCHEMA public TO terrateam;
ALTER DATABASE terrateam OWNER TO terrateam;

Environment Variables

Set the following environment variables in the Terrateam server container:

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

Docker Run

Terminal window
docker run \
-p 8080:8080 \
-e DB_HOST="db" \
-e DB_USER="terrateam" \
-e DB_PASS="terrateam" \
-e DB_NAME="terrateam" \
-e GITHUB_APP_ID="1" \
-e GITHUB_APP_PEM="-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAsYd4c7nM/N\n-----END RSA PRIVATE KEY-----\n" \
-e GITHUB_WEBHOOK_SECRET="02d87878a0ac61d75d25cz8fec1d1af509f9a6d9" \
-e GITHUB_APP_CLIENT_ID="Iv1.8ea942184ee41c0b" \
-e GITHUB_APP_CLIENT_SECRET="8dab6d1de78a2cdbc9o014dubcf4a55ca44a3c81" \
-e TERRAT_API_BASE="https://terrateam-public-endpoint.example.com/api"
ghcr.io/terrateamio/terrat-oss:latest

Webhook URL

When the Terrateam server starts up, it will try to update the GitHub application Webhook URL using the TERRAT_API_BASE environment variable. To disable, set the GITHUB_WEBHOOK_URL_UPDATE environment variable to FALSE.

Step 3: Install the Terrateam GitHub Application

1. Navigate to the GitHub application settings page for your Terrateam GitHub application.

2. Click “Install App” and select the repositories you want to use with Terrateam.

3. Click “Install” to complete the installation.

Step 4: Start Using Terrateam

Terrateam is now set up and ready to use with your Terraform and OpenTofu repositories. Navigate to our Quickstart Guide Step 2 for next steps.

Troubleshooting

If you encounter any issues during the installation process, refer to the following troubleshooting tips:

  • Ensure that your Terrateam server is running and accessible from the internet.
  • Double-check that your GitHub application settings are correct and match the values in your Terrateam server environment variables.
  • Verify that your database connection string is correct and that the Terrateam user has the necessary permissions.
  • Check the logs of your Terrateam server for any error messages or warnings.
  • Make sure you’ve installed your private GitHub application after the Terrateam server is successfully up and running.

If you’re still having trouble, reach out to the Terrateam support team or community for assistance.

Frequently Asked Questions

How Does Terrateam Self-Hosted Interact with My Source Code?

Terrateam never stores source code and never clones repositories. Terrateam uses the GitHub API to retrieve source code and interact with the repository.

Does the Terrateam Server Work with GitHub Enterprise Server?

Yes. To use Terrateam with GitHub Enterprise Server, set the following environment variables:

GITHUB_API_BASE_URL
GITHUB_APP_URL
GITHUB_WEB_BASE_URL

Is the Terrateam Server Horizontally Scalable?

Yes. Add as many Terrateam servers as you want as long as they’re all pointing to the same database.