Skip to content

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:

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 GitHub
public: false

PostgreSQL database

  1. Set the host auth method to md5
echo "host all all all md5" >> pg_hba.conf
  1. Create the Terrateam database
postgres=# create database terrateam;
CREATE DATABASE
postgres=#
  1. 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=#
  1. 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;

Terrateam server

Required 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

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.

Install

Navigate to your private Terrateam GitHub application URL and Install

Next steps

Complete the Terrateam Self-Hosted Next Steps