README
¶
infrastructure-as-coolify
Declarative Infrastructure as Code for Coolify — YAML in,
plan/apply/destroyout. No HCL, no state file, no magic.
iac-coolify is a single-binary CLI that manages Coolify v4 resources declaratively, the
way Terraform manages cloud resources — but native to Coolify, with Kubernetes-style YAML
(apiVersion/kind/metadata/spec), a stateless-first model, auto-generated docs, and a
built-in TUI for live exploration.
Status: 🚧 beta — Coolify v4.x only. APIs may change before v1.0.0. The Coolify
OpenAPI commit SHA is pinned in testdata/openapi/COMMIT_SHA,
with a nightly CI job watching upstream v4.x for drift.
Supported platforms
| OS | amd64 | arm64 |
|---|---|---|
| Linux | ✅ | ✅ |
| macOS | ✅ | ✅ |
| Windows | ✅ | — |
Install
On macOS or Linux, install through Homebrew (this repository is also the tap):
brew tap rems08/iac-coolify https://github.com/Rems08/infrastructure-as-coolify
brew trust rems08/iac-coolify # recent Homebrew requires trusting third-party taps
brew install --cask iac-coolify
brew upgrade --cask iac-coolify # update later
Or download a binary from the releases page, or pull the multi-arch container image:
docker pull ghcr.io/rems08/infrastructure-as-coolify:latest
Every option (go install, pinning a version) is covered in the
install guide;
releases are cosign-signed with SLSA 3 provenance — see
verify release signatures.
Quick start
# Validate your declarative config
iac-coolify validate examples/minimal/
# Preview the changes against live Coolify (Terraform-style diff)
export COOLIFY_API_TOKEN=... # plus --coolify-url or COOLIFY_API_URL
iac-coolify plan examples/minimal/ # runs offline (all-new) if unconfigured
iac-coolify plan examples/minimal/ --output=json --detailed-exitcode
# Apply the changes (creates projects and environments before applications)
iac-coolify apply examples/full-project/ --dry-run # offline preview, mutates nothing
iac-coolify apply examples/full-project/ # interactive confirmation prompt
iac-coolify apply examples/full-project/ --auto-approve # required in CI / non-interactive
# Tear the resources down (reverse dependency order)
iac-coolify destroy examples/full-project/ --auto-approve
# Browse the live instance in a TUI (drift, env vars, lifecycle actions)
iac-coolify explore ./coolify
# Generate the reference documentation from the resource structs
iac-coolify docs gen
plan, apply and destroy are idempotent and print per-field diffs; secret values are
redacted by construction and never reach any output. --detailed-exitcode returns 0 (no
changes), 2 (changes pending), or 1 (error). Behind a Cloudflare Access gateway, set
CF_ACCESS_CLIENT_ID and CF_ACCESS_CLIENT_SECRET.
Documentation
The full documentation lives at https://rems08.github.io/infrastructure-as-coolify/:
- Getting started — from install to a previewed change.
- How-to guides — install, environments, databases, secrets, import, TUI, CI.
- Reference — generated field-by-field schemas for every resource kind.
- Explanation — why iac-coolify and how the configuration model works.
License
Apache-2.0. See SECURITY.md for responsible disclosure and
CONTRIBUTING.md to get started.
Acknowledgements
Built on the shoulders of coollabsio/coolify, charmbracelet, spf13/cobra, and goreleaser.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
iac-coolify
command
Command iac-coolify is the declarative Infrastructure-as-Code CLI for Coolify v4.
|
Command iac-coolify is the declarative Infrastructure-as-Code CLI for Coolify v4. |
|
internal
|
|
|
apply
Package apply reconciles desired iac-coolify resources with a live Coolify instance.
|
Package apply reconciles desired iac-coolify resources with a live Coolify instance. |
|
config
Package config is the boundary between user-authored YAML and the typed resource model.
|
Package config is the boundary between user-authored YAML and the typed resource model. |
|
coolify
Package coolify is the low-level HTTP client for the Coolify v4 API.
|
Package coolify is the low-level HTTP client for the Coolify v4 API. |
|
docs
Package docs generates the reference documentation from the iac struct tags in internal/resource, keeping docs and code in lock-step (single source of truth).
|
Package docs generates the reference documentation from the iac struct tags in internal/resource, keeping docs and code in lock-step (single source of truth). |
|
importer
Package importer reverse-engineers a live Coolify instance into local iac-coolify YAML manifests.
|
Package importer reverse-engineers a live Coolify instance into local iac-coolify YAML manifests. |
|
plan
Package plan computes the semantic difference between the desired state (YAML config) and the actual state (live Coolify), rendering it Terraform-style.
|
Package plan computes the semantic difference between the desired state (YAML config) and the actual state (live Coolify), rendering it Terraform-style. |
|
resource
Package resource holds the user-facing declarative resource types (the iac-coolify YAML schema).
|
Package resource holds the user-facing declarative resource types (the iac-coolify YAML schema). |
|
secrets
Package secrets provides the opaque Secret type and env-var sourcing used throughout iac-coolify.
|
Package secrets provides the opaque Secret type and env-var sourcing used throughout iac-coolify. |
|
state
Package state holds the optional UUID resolver cache.
|
Package state holds the optional UUID resolver cache. |
|
tui
Package tui implements the read-only `explore` terminal browser for live Coolify state.
|
Package tui implements the read-only `explore` terminal browser for live Coolify state. |