# Manage a Self-Hosted PaaS with Terraform or OpenTofu

> Use the Levelrail provider from the Terraform or OpenTofu registry to manage projects, apps, domains and databases as code, with import and the gaps.

Canonical URL: https://levelrail.com/blog/terraform-opentofu-self-hosted-paas/

You can manage a self-hosted Levelrail server from Terraform or OpenTofu with the `glincker/levelrail` provider, which is listed on both registries. It talks to the same REST API as the dashboard and CLI with your own token, so projects, environments, apps, domains and databases can live in version control.

This post follows the [provider docs](https://docs.levelrail.com/terraform-provider) and the [packages page](https://levelrail.com/packages/). It does not add behavior the docs do not state, and it marks what the provider leaves out. You need a running Levelrail control plane first: see [the install page](https://levelrail.com/install/).

## Why manage a PaaS as code

Clicking through a dashboard works for one app. Once you have staging and production, several apps and a database or two, you want the setup written down, reviewed in a pull request and repeatable. A plan shows what would change before anything changes.

The provider does not bypass the platform. Because it uses your token against the same API, every policy and approval rule still applies. It lives in its own Go module and never ships inside the control plane binary.

## Install the provider from either registry

The provider is on the [Terraform registry](https://registry.terraform.io/providers/glincker/levelrail/latest) and the [OpenTofu registry](https://search.opentofu.org/provider/glincker/levelrail/latest) under the same name. Declare it in `main.tf`:

```hcl
terraform {
  required_providers {
    levelrail = {
      source = "registry.terraform.io/glincker/levelrail"
    }
  }
}

provider "levelrail" {
  url   = "https://deploy.example.com"
  token = var.api_token
}
```

Then run `terraform init` or `tofu init`. To test a build from the repository instead of the registry release, the docs describe a `dev_overrides` setup; with that override you skip `init` for this provider and run `plan` and `apply` directly.

## Authenticate with your own token

`url` and `token` fall back to the `APP_API_URL` and `APP_API_TOKEN` environment variables, the same ones the CLI reads. The docs recommend the variables over writing the token into a file:

```bash
export APP_API_URL=https://deploy.example.com
export APP_API_TOKEN=<your token>
```

Create the token in the dashboard or CLI. The provider cannot create tokens, so you pass the one you made in as a variable.

## Which resources exist

The docs list these resources:

| Resource | Manages |
| --- | --- |
| `levelrail_project` | A project |
| `levelrail_environment` | An environment of a project, including `protected` |
| `levelrail_app` | Image, port, replicas, strategy, env vars, limits, restart policy, probes, published ports and more |
| `levelrail_domain` | One hostname routed to an app |
| `levelrail_database` | A managed database and its connection pooler settings |
| `levelrail_environment_variables` | Variables shared by a project or an environment |
| `levelrail_app_secret` | One secret value for an app |
| `levelrail_alert_rule` | An alert rule on one app |
| `levelrail_cron_job` | A scheduled command of one app |
| `levelrail_status_page`, `levelrail_status_component` | The public status page and its rows |
| `levelrail_setting` | One runtime setting |
| `levelrail_node_labels` | Labels and taints on an existing node |

There are also data sources: `levelrail_apps`, `levelrail_nodes`, `levelrail_app_secrets`, `levelrail_cron_jobs` and `levelrail_projects`. The nodes data source needs a root token.

## A small example from the docs

This is part of the complete example in the docs: a project, an app in it and a domain.

```hcl
resource "levelrail_project" "shop" {
  name = "shop"
}

resource "levelrail_app" "web" {
  name       = "shop-web"
  image      = "ghcr.io/example/shop:1.4.2"
  port       = 3000
  replicas   = 2
  project_id = levelrail_project.shop.id
}

resource "levelrail_domain" "web" {
  app  = levelrail_app.web.name
  host = "shop.example.com"
}
```

The docs also note a few behaviors worth knowing before you apply:

- Manage hostnames only with `levelrail_domain`, not through the app resource.
- `levelrail_app.env`, when set, replaces the live plain variables. Leave it unset to manage variables elsewhere.
- `levelrail_environment_variables` only manages the keys you list.
- A database engine or version change forces a replace, which destroys data. Use `prevent_destroy` on databases you care about.
- A project cannot be deleted while it still holds apps.

## Import what already exists

Every resource supports `terraform import`, treats a 404 on read as drift and reads the live object after each write. Import IDs differ by resource, for example a project ID for `levelrail_project`, `app_name/host` for `levelrail_domain` and the app name for `levelrail_app`. The full table is in the docs.

An imported app shows its lists, sets and maps (command, labels, published ports, volumes, tags, exec probes, env) as unset until you add them to the configuration. Leaving one unset never wipes what the dashboard configured.

## What is not covered

The docs are explicit that the provider is not a full mirror of the platform. Not covered today:

- Vault-backed variables and bulk secret import. A single secret set with `levelrail_app_secret` lands in Terraform state, so protect the state.
- Bind mounts, hooks, egress policy and GPU requests on apps.
- Git and build sources, deploys and rollbacks, which are actions rather than state.
- Per-domain settings such as TLS certificates, redirects, headers, WAF, caching and auth gates.
- Creating or removing nodes, load balancers, pipelines, notification channels, backups, teams, users, roles and tokens.
- Database users, backup schedules, placement, public access and upgrades.

The docs point to their Platform as code page for some of these through the CLI. This post does not verify those claims beyond what the docs state.

## FAQ

**Does the provider work with both Terraform and OpenTofu?** Yes. It is listed as `glincker/levelrail` on both registries, and the same `required_providers` block works with `terraform init` or `tofu init`.

**Can the provider create API tokens?** No. The API only lets an interactive session create or revoke tokens. Make one in the dashboard or CLI and pass it in as a variable.

**Can I import apps I already created in the dashboard?** Yes, every resource supports import. Add the fields you want managed to the configuration afterwards.

## Next steps

Read the [provider docs](https://docs.levelrail.com/terraform-provider), check the other places Levelrail is published on [the packages page](https://levelrail.com/packages/), and install the server from [the install page](https://levelrail.com/install/) if you have not yet.

## Frequently asked questions

### Does the provider work with both Terraform and OpenTofu?

Yes. The provider is listed as glincker/levelrail on the Terraform registry and on the OpenTofu registry. Use terraform init or tofu init with the same required_providers block.

### Can the provider create API tokens?

No. There is no token resource. The API only lets an interactive session create or revoke tokens, so a provider holding a token cannot mint another one. Create tokens in the dashboard or CLI and pass them in as variables.

### Can I import apps I already created in the dashboard?

Every resource supports terraform import. An imported levelrail_app shows its lists, sets and maps as unset until you add them to the configuration.
