Skip to content

concepts.md

Latest commit

 

History

History
155 lines (119 loc) · 6.24 KB

concepts.md

File metadata and controls

155 lines (119 loc) · 6.24 KB
Raw
page_title Core Concepts
subcategory Getting Started
description Understand the Coolify resource model and how the provider maps to it.

Core Concepts

Resource hierarchy

Coolify organizes infrastructure in a hierarchy:

Server (physical or VM with Docker)
  └── Project (logical grouping)
       └── Environment (production, staging, dev)
            ├── Application (web app, API, worker)
            ├── Database (PostgreSQL, MySQL, Redis, etc.)
            └── Service (one-click apps from the catalog)

The Terraform provider maps each level to a resource or data source.

Resource types

Infrastructure

Resource Purpose
coolify_project Logical group for applications and databases
coolify_environment Environment within a project (production, staging)
coolify_server A Docker host registered with Coolify
coolify_server_hetzner Provision a Hetzner Cloud server and register it with Coolify
coolify_private_key SSH key for server access or Git clone
coolify_cloud_token Hetzner/cloud provider API token
coolify_github_app GitHub App integration for repository access

Applications

Five application types cover different deployment methods:

Resource Source
coolify_application Public Git repository
coolify_application_private_git Private Git repository (SSH key)
coolify_application_github_app GitHub App integration
coolify_application_dockerfile Dockerfile (no Git repo required)
coolify_application_docker_image Docker image (Docker Hub, GHCR)

All application resources support configurable timeouts for long builds.

Databases

Eight database engines are supported:

coolify_database_postgresql, coolify_database_mysql, coolify_database_mariadb, coolify_database_redis, coolify_database_mongodb, coolify_database_clickhouse, coolify_database_keydb, coolify_database_dragonfly

All database resources share a common schema: placement (project_uuid, server_uuid, environment_name), networking (image, is_public, public_port), and resource limits (limits_memory, limits_cpus, and related fields). Coolify's public API does not accept log drain or SSL fields (is_log_drain_enabled, is_include_timestamps, enable_ssl, ssl_mode) on create or update; set those in the Coolify UI. The provider keeps them in state when you import or when Coolify returns them on read.

Operations

Resource Purpose
coolify_environment_variable Inject config into apps, services, or databases
coolify_storage Persistent volume mount for apps, services, or databases
coolify_scheduled_task Cron-based task on apps or services
coolify_deployment Trigger a deploy (with force-redeploy via triggers)
coolify_resource_action Start, stop, or restart an application, database, or service
coolify_database_backup Schedule automated backups with cron syntax
coolify_service Deploy one-click services from the Coolify catalog

Data sources

Every resource has a corresponding data source for reading existing state. Plural data sources (e.g., coolify_projects) return all resources of that type. Additional read-only data sources include:

  • coolify_server_resources: list all resources deployed on a server
  • coolify_server_domains: list all domains configured on a server
  • coolify_environment_variables: list env vars for an app, service, or database
  • coolify_version: read the Coolify instance version
  • coolify_team: read team info and members
  • coolify_hetzner_images: list available Hetzner Cloud images
  • coolify_hetzner_locations: list available Hetzner Cloud locations
  • coolify_hetzner_server_types: list available Hetzner Cloud server types
  • coolify_hetzner_ssh_keys: list SSH keys in Hetzner Cloud
  • coolify_hetzner_firewalls: list existing Hetzner Cloud firewalls (Coolify >= v4.2.0)
  • coolify_hetzner_networks: list existing Hetzner Cloud private networks (Coolify >= v4.2.0)
  • coolify_digitalocean_images / coolify_digitalocean_regions / coolify_digitalocean_sizes / coolify_digitalocean_ssh_keys: list DigitalOcean catalog items (Coolify >= v4.2.0)
  • coolify_vultr_os / coolify_vultr_plans / coolify_vultr_regions / coolify_vultr_ssh_keys: list Vultr catalog items (Coolify >= v4.2.0)

Import

All stateful resources support terraform import (action and validation resources are lifecycle-only). Most use a single UUID:

terraform import coolify_project.main <uuid>

Resources with composite IDs use colon-separated values:

terraform import coolify_database_backup.daily <db-uuid>:<backup-id>
terraform import coolify_environment_variable.key application:<app-uuid>:<env-uuid>

See the Import Guide for full details.

Immutable fields

Some fields force resource replacement when changed. These are marked with RequiresReplace in the schema:

  • project_uuid, server_uuid, environment_name on all application and database resources
  • github_app_uuid on coolify_application_github_app

Plan output will show # forces replacement for these fields. project_uuid and server_uuid are null after a simple UUID import, because Coolify GET does not return them. The next apply stores the configuration value in place. A change from one known UUID to another still replaces the resource.

Renaming coolify_environment.name updates Coolify in place. The applications, databases, and services in that environment stay where they are. Terraform replaces any of those resources whose environment_name is set from the renamed name. Point them at environment_uuid instead:

environment_uuid = coolify_environment.staging.uuid

Do not set environment_name on that same resource. Coolify looks up the name first, so a name would ignore the UUID. Switching an existing resource from environment_name to environment_uuid updates state in place. The Coolify resource stays where it is. Changing a known environment_uuid, or changing environment_name from one known name to another, still forces a new resource.

Next steps

Follow the Quick Start to deploy your first application in under five minutes.