Overview

Terrateam Self-Hosted is the on-premise, privately hosted version of Terrateam. It is designed for:

• Evaluating Terrateam on your own infrastructure (Free)
• Deploying Terrateam to your own infrastructure for production use

To evaluate Terrateam Self-Hosted, simply follow the setup instructions below. If you need a fully supported on-premise version of Terrateam, reach out to sales@terrateam.io for a license.

Prerequisites

Before you begin, ensure you have the following:

• Docker
• Docker Compose

Note

Terrateam Docker images are built for linux/amd64.

Step 1: Create a Private Terrateam GitHub Application

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

Note

Make sure the Terrateam server is running before you install the Terrateam GitHub application.

1. Clone the terrateamio/terrateam repository:

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

2. Start the setup container:

   Note

   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

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

   Note

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

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/ directory next to docker-compose.yml:

   josh@elmer:~ $ tree terrateam/
   terrateam/
   ├── docker-compose.yml
   ├── .env
   └── README.md
   0 directories, 3 files
   josh@elmer:~ $

   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. Edit docker-compose.yml and add your Ngrok Auth Token to NGROK_AUTHTOKEN.
3. Start Terrateam:

   docker-compose up server -d

4. When the Terrateam server starts up, it will attempt to update the GitHub application Webhook URL if the following are true:
   • The TERRAT_API_BASE environment variable is unset
   • The NGROK_ENDPOINT environment variable is set
   • The GITHUB_WEBHOOK_URL_UPDATE is set to TRUE (default TRUE)

Option 2: Kubernetes

1. Source your private Terrateam GitHub application settings file:

   source .env

2. Create your Terrateam private GitHub application secrets:

   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:

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

4. Add the Terrateam Helm repository:

   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:
     1. Create a global static IP address:

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

     2. Show the IP:

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

     3. Add the global static IP to a DNS zone you control, for example, as terrateam.example.com.
     4. Install the Helm chart:

        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"

        Note

        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:

     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:
     1. Specify a custom my-values.yaml for installation:

        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: Fly.io

1. Set a random name for the Terrateam organization:

   export FLY_TERRATEAM_ORG="terrateam-$RANDOM"

2. Create the Fly organization:

   fly orgs create $FLY_TERRATEAM_ORG

3. Create a new PostgreSQL database:

   fly pg create -o $FLY_TERRATEAM_ORG -n $FLY_TERRATEAM_ORG-db

4. Set the PostgreSQL database to use the md5 authentication method:

   fly config save -a $FLY_TERRATEAM_ORG-db

5. Rename fly.toml:

   mv fly.toml fly-db.toml

6. Add the following to your local fly-db.toml in the [env] section:

   POSTGRES_HOST_AUTH_METHOD = "md5"
   POSTGRES_INITDB_ARGS = "--auth-host=md5"

7. Get the IMAGE path of your database:

   vagrant@vagrant:~$ fly status -a "$FLY_TERRATEAM_ORG-db"
   ID              STATE   ROLE    REGION  CHECKS                  IMAGE                                   CREATED                 UPDATED
   3d8d9344a1e108  started primary ams     3 total, 3 passing      flyio/postgres-flex:15.2 (v0.0.40)      2023-05-15T10:13:29Z    2023-05-15T10:13:44Z
   vagrant@vagrant:~$

8. Export the IMAGE path to an environment variable:

   export IMAGE="flyio/postgres-flex:15.2"

9. Update the application using your modified fly-db.toml:

   fly deploy -a $FLY_TERRATEAM_ORG-db --config fly-db.toml -i "$IMAGE"

10. Create the Terrateam database, user, and configure the password authentication method:

    fly postgres connect -a $FLY_TERRATEAM_ORG-db

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

11. Create the Terrateam application:

    flyctl apps create -o $FLY_TERRATEAM_ORG $FLY_TERRATEAM_ORG-app

12. Set the Terrateam application secrets:

    fly secrets set -a $FLY_TERRATEAM_ORG-app GITHUB_APP_ID=$GITHUB_APP_ID
    fly secrets set -a $FLY_TERRATEAM_ORG-app GITHUB_APP_PEM="$GITHUB_APP_PEM"
    fly secrets set -a $FLY_TERRATEAM_ORG-app GITHUB_WEBHOOK_SECRET=$GITHUB_WEBHOOK_SECRET
    fly secrets set -a $FLY_TERRATEAM_ORG-app GITHUB_APP_CLIENT_ID=$GITHUB_APP_CLIENT_ID
    fly secrets set -a $FLY_TERRATEAM_ORG-app GITHUB_APP_CLIENT_SECRET=$GITHUB_APP_CLIENT_SECRET

13. Set the Terrateam database connection string:

    fly secrets set -a $FLY_TERRATEAM_ORG-app DATABASE_URL="postgres://terrateam:terrateam@$FLY_TERRATEAM_ORG-db.internal:5432/terrateam"

14. Deploy the Terrateam application:

    fly deploy -a $FLY_TERRATEAM_ORG-app

15. When the Terrateam server starts up, it will attempt to update the GitHub application Webhook URL if the following are true:
    • The TERRAT_API_BASE environment variable is unset
    • The NGROK_ENDPOINT environment variable is set
    • The GITHUB_WEBHOOK_URL_UPDATE is set to TRUE (default TRUE)

Option 4: Manual instructions

Components

Terrateam consists of two components:

• Terrateam server ghcr.io/terrateamio/terrateam:v1
• PostgreSQL database (at least v14)

PostgreSQL database

Set the host auth method to md5

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

Note

If initializing a new database, then pass initdb the --auth-host=md5 option

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:

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

Docker run

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/terrateam:v1

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.

Note

If you set the GitHub Webhook URL manually, make sure you include a trailing /api/github/v1/events.

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: Configure Your Terraform Repositories

1. Add a .terrateam/config.yml file to the root of your Terraform repository.
2. Configure your Terrateam settings as needed. See the Configuration Reference for details.
3. Commit and push your changes to the default branch of your repository.

Step 5: Start Using Terrateam

Terrateam is now set up and ready to use with your Terraform repositories. You can start creating pull requests and using Terrateam commands to manage your infrastructure as code.

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

What is Terrateam Self-Hosted?

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

It is designed for:

• Evaluating Terrateam on your own infrastructure
• Deploying Terrateam to your own infrastructure for production use

How is Terrateam Self-Hosted different from Terrateam Cloud?

Terrateam Self-Hosted provides the flexibility to deploy all of Terrateam to your own infrastructure giving you full control of your data.

How much does Terrateam Self-Hosted cost?

Terrateam Self-Hosted is free for evaluation expiring after 30 days. Reach out for an enterprise subscription to receive a license.

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.