Install
Markdown
Ask AI
Share

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.

Markdown
Ask AI
Share

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 and the packages page. 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.

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 and the OpenTofu registry 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:

ResourceManages
levelrail_projectA project
levelrail_environmentAn environment of a project, including protected
levelrail_appImage, port, replicas, strategy, env vars, limits, restart policy, probes, published ports and more
levelrail_domainOne hostname routed to an app
levelrail_databaseA managed database and its connection pooler settings
levelrail_environment_variablesVariables shared by a project or an environment
levelrail_app_secretOne secret value for an app
levelrail_alert_ruleAn alert rule on one app
levelrail_cron_jobA scheduled command of one app
levelrail_status_page, levelrail_status_componentThe public status page and its rows
levelrail_settingOne runtime setting
levelrail_node_labelsLabels 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, check the other places Levelrail is published on the packages page, and install the server from the install page 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.

Next steps

Keep reading

The lightest self-hosted PaaS, ranked The lightest self-hosted PaaS, ranked

comparison 8 min read

Lightest Self-Hosted PaaS Options by RAM (2026)

Levelrail, CapRover, Dokku, Coolify and Dokploy ranked by the RAM each project's docs state, next to a measured idle figure, for small and cheap VPS plans.

  • Self-hosting
  • Comparison
  • PaaS
Install the CLI with npm or Homebrew Install the CLI with npm or Homebrew

tutorial 3 min read

Install the Levelrail CLI: npm, Homebrew or a Binary

Three ways to install levelrail-cli: npm or a runner like npx, the Homebrew tap, or a release binary for macOS, Linux and Windows. It is a client only.

  • Self-hosting
  • DevOps
  • Tutorial