Skip to content

quickstart.md

Latest commit

 

History

History
85 lines (56 loc) · 3.63 KB

quickstart.md

File metadata and controls

85 lines (56 loc) · 3.63 KB
Raw
title Quick start
category Getting started
order 20
description Bootstrap an instance, log in with the Terraform CLI, and run a first plan.

Quick start

This guide takes you from an empty deployment to a completed plan. It assumes Terrence is already running and reachable over HTTPS. If it is not yet behind TLS, set that up first: Reverse proxy (HTTPS).

Step 1: Create the first administrator

Terrence starts without any user accounts. Set the ADMIN_PASSWORD environment variable before the first start. On first boot, Terrence creates an administrator account with that password.

The administrator username defaults to admin. You can change it with ADMIN_USERNAME. The account email is set with ADMIN_EMAIL.

The bootstrap runs exactly once. Later restarts do not create or reset accounts. If the solo administrator password is lost, see Configuration for the one-shot TERRENCE_ADMIN_PASSWORD_RESET recovery.

Local registration is disabled by default. To allow anyone to register, use Site administration → Authentication → Local registration, or set TERRENCE_ENABLE_LOCAL_SIGNUP=true as the environment default. Registrations never become site administrators.

Step 2: Log in with the CLI

Install Terraform on your machine. Then run:

terraform login terraform.example.com

Replace terraform.example.com with your instance hostname. The command opens a browser page on the instance. Sign in with the administrator account. The page shows an API token. Paste it into the terminal prompt.

Terraform stores the token in ~/.terraform.d/credentials.tfrc.json. The CLI uses this token for every request.

Step 3: Create an organization

Bootstrap already created an organization named default and made the administrator its owner. Use it, or create more organizations in the web interface or with the API. ADMIN_ORGANIZATION overrides the bootstrap organization name.

For a homelab, one organization is usually enough. It already has a default project; you do not need to create another project before adding workspaces.

Step 4: Create a workspace and run your first plan

Open Workspaces → New workspace. Enter a name, choose Terraform or OpenTofu, and keep CLI or CI pipeline as the source. Execution, project, version, and automatic-apply controls are under Advanced settings. Agent execution requires an agent pool.

The new workspace shows connection instructions using its actual organization, workspace name, and engine. Copy those instructions into your configuration. The example below uses Terraform.

In a directory with a Terraform configuration, add a cloud block:

terraform {
  cloud {
    hostname     = "terraform.example.com"
    organization = "example-org"
    workspaces {
      name = "my-first-workspace"
    }
  }
}

Run:

terraform init
terraform plan

The CLI uploads the configuration and the worker executes the plan on the server. Watch the run in the web interface under the workspace page.

Step 5: Apply

Plans stop in the planned state and wait for confirmation. Confirm from the web interface, or with the API:

curl -X POST https://terraform.example.com/api/v2/runs/<run-id>/actions/apply \
  -H "Authorization: Bearer <token>"

Workspaces can enable auto-apply. With auto-apply enabled, a successful plan applies immediately.

Next steps

  • Read Core concepts to understand the run lifecycle.
  • Read Workspaces to configure execution modes and VCS connections.
  • Read Tokens to mint tokens for automation.
  • Read Configuration before running in production.