Manual Instructions

Deploy Terrateam anywhere.

Prerequisites

Completed Step 1
A private Terrateam GitHub application
The Terrateam GitHub application settings file
A PostgreSQL database
A Docker orchestrator (Kubernetes, ECS, Nomad, etc.)

Components

Terrateam consists of two components:

Terrateam server (ghcr.io/terrateamio/terrateam:v1 (opens in a new tab))
PostgreSQL database (at least v14)

GitHub application

Complete Step 1 in the deployment steps to automatically create the Terrateam GitHub application. If you need to manually create the GitHub application, you can use our Probot yaml as a guide:

Expand for yaml

default_events:
  - issue_comment
  - issues
  - pull_request
  - pull_request_review
  - pull_request_review_comment
  - push
  - workflow_job
  - workflow_run
default_permissions:
  actions: write
  checks: read
  contents: write
  issues: write
  metadata: read
  pull_requests: write
  statuses: write
  members: read
  secrets: write
  emails: read
name: terrateam-io
url: https://terrateam.io/
description: Terraform automation for teams
public: false

PostgreSQL database

Set the host auth method to md5

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

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;

Use a stronger password than the example above

Terrateam server

Required 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

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

GitHub application 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.

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

For example: https://terrateam-public-endpoint.example.com/api/github/v1/events

Install

Navigate to your private Terrateam GitHub application URL and Install

Next steps

Complete the Terrateam Self-Hosted Next Steps

Fly.io Amazon ECS