> For the complete documentation index, see [llms.txt](https://docs.terrakube.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.terrakube.io/getting-started/production-setup.md).

# Production Setup

Follow this order to deploy Terrakube and configure access before the first production run. If you only want to try it locally, use [Your First Run](https://docs.terrakube.io/getting-started/first-run.md).

### 1. Choose your deployment workflow and controls

Start with [Recommended Settings](https://docs.terrakube.io/getting-started/recommended-settings.md). Decide whether production changes come from a protected Git branch, exact-commit CI, or CLI uploads. This determines which workspace restrictions to enable later.

Choose token lifetimes and the teams that may plan, approve and destroy. You will apply service settings during deployment and workspace settings after creating each workspace.

### 2. Deploy and configure the services

Follow [Deployment](https://docs.terrakube.io/getting-started/deployment.md) and the [Helm Chart](https://docs.terrakube.io/getting-started/deployment/helm-chart.md). Configure ingress/TLS, storage, the database and Redis, then connect [user authentication](https://docs.terrakube.io/getting-started/user-management.md).

Apply the service recommendations in [Token Security](https://docs.terrakube.io/getting-started/deployment/token-security.md): independent signing secrets, token issuance/lifetime controls and, after verifying your Dex audiences, audience validation. These go in the API and registry deployment environment, not in workspace variables. Use the [Configuration Reference](https://docs.terrakube.io/reference/configuration.md) to look up exact names and defaults.

### 3. Create an organization and assign team access

[Create an organization](https://docs.terrakube.io/set-up/organizations/organizations.md), then [create teams](https://docs.terrakube.io/set-up/organizations/team-management.md) that match your identity-provider groups. Assign only the permissions each team needs; review destroy access on Custom roles.

Create [projects](https://docs.terrakube.io/set-up/projects.md) if you want to group workspaces and grant [project-level access](https://docs.terrakube.io/set-up/projects/team-access.md). Permissions from organization, project and workspace access are additive.

### 4. Prepare the source, templates and automation identity

Connect a [VCS provider](https://docs.terrakube.io/set-up/vcs-providers.md) for repository-driven workspaces. Prepare [templates](https://docs.terrakube.io/set-up/organizations/templates.md), including a plan-only template for PRs and a deployment template with an explicit approval team and saved-plan requirement.

For CI, configure [Federated Identity](https://docs.terrakube.io/set-up/organizations/federated-identity.md) with narrow claim conditions. For exact-commit deployments, follow the [GitHub Actions](https://docs.terrakube.io/integrate/ci-cd-integration/github-actions.md) guide and its branch-restriction compatibility note. CLI-driven workspaces instead use the organization's [CLI templates](https://docs.terrakube.io/set-up/organizations/templates/default-templates.md#cli-driven-templates).

### 5. Create and configure each workspace

[Create a workspace](https://docs.terrakube.io/run-terraform/workspaces/creating-workspaces.md), select its project and repository/branch or CLI workflow, then configure:

| Configure                               | Where                                                                        | Guide                                                                                                              |
| --------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Scoped team access                      | Workspace **Settings > Team Access**                                         | [Team Access](https://docs.terrakube.io/run-terraform/workspaces/team-access.md)                                   |
| Terraform inputs and environment values | Workspace **Variables**                                                      | [Variables](https://docs.terrakube.io/run-terraform/workspaces/variables.md)                                       |
| Cloud authentication                    | Workspace variables and the cloud provider's trust configuration             | [Dynamic Provider Credentials](https://docs.terrakube.io/run-terraform/workspaces/dynamic-provider-credentials.md) |
| Branch and ungated-apply controls       | Workspace **Settings > General**, as an organization-level workspace manager | [Run Restrictions](https://docs.terrakube.io/run-terraform/workspaces/run-restrictions.md)                         |

Apply the choices from step 1. `restrictApplyToConfiguredBranch` and `requireApproveToApply` are workspace attributes, not service environment variables or Terraform inputs. Branch restriction is unavailable in the UI for CLI-driven workspaces and conflicts with API-created exact-commit apply runs.

### 6. Validate a run before adding automatic triggers

[Start a run](https://docs.terrakube.io/run-terraform/workspaces/starting-a-run.md) with the intended planning identity. Check the branch, template, cloud access and approval team. Confirm the permission boundaries with a disposable workspace before using production resources.

Then configure [webhooks](https://docs.terrakube.io/run-terraform/workspaces/webhooks.md), [schedules](https://docs.terrakube.io/run-terraform/workspaces/workspace-scheduler.md) or [run triggers](https://docs.terrakube.io/run-terraform/workspaces/run-triggers.md), and test those paths too. A successful manual run does not establish that a PR or CI run uses the intended identity and template.

### 7. Operate and upgrade

Configure [executor output and run limits](https://docs.terrakube.io/getting-started/deployment/executor-log-output.md), [notifications](https://docs.terrakube.io/run-terraform/workspaces/notifications.md) and backups. Use [Upgrading](https://docs.terrakube.io/getting-started/upgrading.md) and [Updates](https://docs.terrakube.io/updates.md) before changing versions.

Optional features such as the [HTTP state backend](https://docs.terrakube.io/getting-started/deployment/http-state-backend.md), [plan artifacts](https://docs.terrakube.io/run-terraform/workspaces/plan-artifacts.md) and [policy governance](https://docs.terrakube.io/govern/policy-enforcement-opa.md) have their own configuration guides. Add them when the workflow needs them.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.terrakube.io/getting-started/production-setup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
