OpenTofu: manage your VPS fleet with Infrastructure as Code

Visit opentofu.org/docs/intro/install for instructions based on your OS. On macOS with Homebrew: brew install opentofu. On Debian/Ubuntu: the official OpenTofu repository provides the opentofu package. Verify the installation with tofu version — the command should return the installed version.

Create a dedicated directory and four standard files.

# main.tf — main resources
# variables.tf — variable declarations
# outputs.tf — values exposed after apply
# terraform.tfvars — concrete values (gitignore if secrets)

This structure is not required by OpenTofu, but it is the widely adopted convention: main.tf holds the resources, variables.tf declares types and default values, outputs.tf exposes what Ansible or another tool needs to read after provisioning (server IP, hostname…), and terraform.tfvars contains the concrete values you do not want to hard-code in main.tf.

OpenTofu installs required providers at tofu init. The hashicorp/tls provider generates an SSH key pair locally, eliminating manual key management.

terraform {
  required_providers {
    tls = {
      source  = "hashicorp/tls"
      version = "~> 4.0"
    }
  }
}

resource "tls_private_key" "vps_key" {
  algorithm = "ED25519"
}

output "private_key_pem" {
  value     = tls_private_key.vps_key.private_key_pem
  sensitive = true
}

Run tofu init to download the provider, then tofu apply to generate the key. Retrieve it with tofu output -raw private_key_pem > ~/.ssh/vps_key && chmod 600 ~/.ssh/vps_key.

If your VPS provider does not have an official OpenTofu provider, the hashicorp/null provider with a local-exec allows you to run a local command (a curl API call, a shell script) and model the resource in the state.

resource "null_resource" "vps_provision" {
  triggers = {
    server_name = var.server_name
  }

  provisioner "local-exec" {
    command = <<EOT
      curl -s -X POST https://api.your-provider.com/v1/servers \
        -H "Authorization: Bearer ${var.api_token}" \
        -d '{"name": "${var.server_name}", "image": "ubuntu-22.04"}'
    EOT
  }
}

This pattern suits a transitional phase. If your provider exposes a REST API, a shell script called via local-exec is sufficient to create the server and write its IP to a file that outputs.tf will then expose.

Once the VPS is provisioned and Docker installed (by Ansible, typically), the kreuzwerker/docker provider lets you declare containers, networks and volumes in OpenTofu.

terraform {
  required_providers {
    docker = {
      source  = "kreuzwerker/docker"
      version = "~> 3.0"
    }
  }
}

provider "docker" {
  host = "ssh://root@${var.server_ip}:22"
}

resource "docker_container" "app" {
  name  = "my-app"
  image = docker_image.app.image_id
}

resource "docker_image" "app" {
  name = "nginx:alpine"
}

The provider connects to the VPS Docker daemon via SSH — no additional TCP port to open. The stable provider version is available on the Terraform Registry.

For solo development, the local state (terraform.tfstate) is sufficient. In a team or CI/CD context, two developers running tofu apply simultaneously corrupt the state. The solution is a remote backend with locking.

OpenTofu natively supports S3 (AWS, self-hosted MinIO) and GitLab Managed Terraform State. With a MinIO bucket on a VPS:

terraform {
  backend "s3" {
    bucket                      = "tofu-state"
    key                         = "production/terraform.tfstate"
    region                      = "eu-west-1"
    endpoint                    = "https://minio.your-domain.com"
    skip_credentials_validation = true
    skip_metadata_api_check     = true
    skip_region_validation      = true
    force_path_style            = true
  }
}

Locking is automatic: if a tofu apply is running, a second one is rejected until the first completes.

A typical Woodpecker CI or Forgejo Actions pipeline runs tofu plan on every pull request (for human review of the infrastructure diff) and tofu apply on merge to the main branch.

steps:
  - name: tofu-plan
    image: ghcr.io/opentofu/opentofu:latest
    commands:
      - tofu init
      - tofu plan -out=tfplan

  - name: tofu-apply
    image: ghcr.io/opentofu/opentofu:latest
    commands:
      - tofu apply tfplan
    when:
      branch: main
      event: push

The remote state (previous step) is essential here: the CI runner does not have access to the local state on your workstation.