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
Step 1: Create a Private Terrateam GitHub Application
Terrateam Self-Hosted requires a new Terrateam GitHub application to be created.
- Clone the
terrateamio/terrateam
repository: - Start the
setup
container: - 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
- Save your private Terrateam GitHub application settings file to
.env
in yourterrateam/
directory next todocker-compose.yml
: Your.env
file should look like this but with actual values: - Edit
docker-compose.yml
and add your Ngrok Auth Token toNGROK_AUTHTOKEN
. - Start Terrateam:
- 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 toTRUE
(defaultTRUE
)
- The
Option 2: Kubernetes
- Source your private Terrateam GitHub application settings file:
- Create your Terrateam private GitHub application secrets:
- Create your Terrateam database password secret:
- Add the Terrateam Helm repository:
- Install the Helm chart based on your specific setup:
- GKE with an HTTPS load balancer and managed certificate:
- Create a global static IP address:
- Show the IP:
- Add the global static IP to a DNS zone you control, for example, as
terrateam.example.com
. - Install the Helm chart:
- Without Ingress:
You can use NGINX-ingress and cert-manager to expose the
terrateam-server
service. - Custom:
- Specify a custom
my-values.yaml
for installation:
- Specify a custom
- GKE with an HTTPS load balancer and managed certificate:
- 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 theTERRAT_API_BASE
environment variable. To disable, set theGITHUB_WEBHOOK_URL_UPDATE
environment variable toFALSE
.
Option 3: Fly.io
- Set a random name for the Terrateam organization:
- Create the Fly organization:
- Create a new PostgreSQL database:
- Set the PostgreSQL database to use the
md5
authentication method: - Rename
fly.toml
: - Add the following to your local
fly-db.toml
in the[env]
section: - Get the
IMAGE
path of your database: - Export the
IMAGE
path to an environment variable: - Update the application using your modified
fly-db.toml
: - Create the Terrateam database, user, and configure the password authentication method:
- Create the Terrateam database:
- Set the password authentication method:
- Create the Terrateam user:
- Create the Terrateam application:
- Set the Terrateam application secrets:
- Set the Terrateam database connection string:
- Deploy the Terrateam application:
- 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 toTRUE
(defaultTRUE
)
- The
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
Create the Terrateam database
Set the password authentication method
Create the Terrateam user
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
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
- Navigate to the GitHub application settings page for your Terrateam GitHub application.
- Click “Install App” and select the repositories you want to use with Terrateam.
- Click “Install” to complete the installation.
Step 4: Configure Your Terraform Repositories
- Add a
.terrateam/config.yml
file to the root of your Terraform repository. - Configure your Terrateam settings as needed. See the Configuration Reference for details.
- 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:
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.