tcwlab/opentofu repository overview

⁠tcwlab/opentofu

⁠Quick start

docker pull tcwlab/opentofu:latest

# Run against the current directory
docker run --rm -v "$PWD:/workspace" tcwlab/opentofu:latest version

Or as a Forgejo / GitHub Actions container job:

tofu-validate:
  runs-on: ubuntu-22.04
  container:
    image: tcwlab/opentofu:latest
  steps:
    - uses: https://data.forgejo.org/actions/checkout@v4
    - run: tofu fmt -check -recursive
    - run: |
        find . -name '*.tf' -execdir tofu init -backend=false \; \
                            -execdir tofu validate \;

⁠Tags

Always pin a concrete version in production. latest is fine for local experiments, but pinning protects your pipeline from a toolchain bump that lands without a PR. The major/minor floating tags (1, 1.11) are convenient for internal use; external consumers should pin the full SemVer.

The opentofu image tag mirrors the OpenTofu CLI version exactly. When OpenTofu 1.11.6 is released, tcwlab/opentofu:1.11.6 contains that exact version (not a wrapper SemVer).

⁠Supported architectures

• linux/amd64
• linux/arm64

Every tag is a multi-arch manifest list. Docker pulls the right architecture automatically.

⁠What's included

Base image: alpine:3.23. Default workdir: /workspace. Default user: tofuusr (non-root, uid auto-assigned).

⁠Usage

⁠Validate Terraform/OpenTofu code

docker run --rm -v "$PWD:/workspace" tcwlab/opentofu:1.11.6 \
  sh -c 'find . -name "*.tf" -execdir tofu init -backend=false \; -execdir tofu validate \;'

⁠Format check

docker run --rm -v "$PWD:/workspace" tcwlab/opentofu:1.11.6 fmt -check -recursive

⁠Forgejo workflow — full snippet

lint:
  name: OpenTofu Format
  runs-on: ubuntu-22.04
  container:
    image: tcwlab/opentofu:1.11.6
  steps:
    - uses: https://data.forgejo.org/actions/checkout@v4
    - name: Format check
      run: tofu fmt -check -recursive

validate:
  name: OpenTofu Validate
  runs-on: ubuntu-22.04
  needs: lint
  container:
    image: tcwlab/opentofu:1.11.6
  steps:
    - uses: https://data.forgejo.org/actions/checkout@v4
    - name: Validate
      run: |
        find . -name '*.tf' -execdir tofu init -backend=false \; \
                            -execdir tofu validate \;

⁠Configuration

⁠Volume mount points

⁠Environment variables

The image passes all environment variables directly to OpenTofu. Common patterns:

⁠Working directory

The image runs with WORKDIR /workspace. If your IaC files are in a subdirectory, use:

- run: |
    cd ./infra
    tofu init -backend=false
    tofu validate

⁠Why tcwlab/opentofu and not upstream images?

Pinning discipline. Public OpenTofu images (Docker Hub official, GitHub Container Registry) often use latest or floating major versions, which means your CI toolchain can silently advance to a new OpenTofu version without a PR. tcwlab/opentofu enforces the principle that every tool version is explicit — the image tag is the version, and upgrades happen via PR.

Additional benefits:

• Deterministic builds — same tag always pulls the exact OpenTofu version (no surprises).
• Consistent Alpine base — all tcwlab images use Alpine 3.23, minimal and hardened identically.
• Multi-arch by default — linux/amd64 and linux/arm64 in every release.
• Security scanning — each build is scanned with Trivy before publication.

⁠Source, issues, contributing

• Source: github.com/tcwlab/opentofu⁠
• Issues / feature requests: github.com/tcwlab/opentofu/issues⁠
• Docker Hub: hub.docker.com/r/tcwlab/opentofu⁠

⁠Build, supply chain

Every release is built and published by the repo's own .forgejo/workflows/ci.yml⁠ on a Forgejo runner:

• Multi-arch build (linux/amd64, linux/arm64) via docker buildx with --sbom=true --provenance=mode=max.
• Trivy vulnerability scan on HIGH/CRITICAL severity (failures show up as PR comments).
• Self-lint via betterlint running against the Dockerfile.

The opentofu image version is cut by semantic-release from Conventional Commits on main. The version exactly mirrors the OpenTofu CLI version (e.g., release of OpenTofu 1.11.6 triggers a new tcwlab/opentofu:1.11.6 image).

⁠License

Apache License 2.0. See LICENSE⁠ for the full text.

OpenTofu itself is licensed under MPL-2.0. See opentofu/opentofu⁠ for details.