coolify/README.md

Deploy Coolify to OVH VPS with Terraform, Ansible, and Gitea Actions

This repository contains all the configuration needed to dynamically provision a virtual private server (VPS) on OVH Cloud using Terraform, configure the VPS and install Coolify using Ansible, and automate the entire workflow via Gitea Actions on every push to the main or master branches.

---

🏗️ Architecture & Pipeline Flow

The deployment workflow is fully automated and consists of the following steps:

graph TD
    A[Push to main/master] --> B[Gitea Actions Runner Starts]
    B --> C[Terraform Initializes & Applies]
    C -->|Creates SSH Key & Instance| D[OVH Public Cloud VPS]
    C -->|Generates| E[ansible/inventory.ini]
    B --> F[Ansible Environment Setup]
    F -->|Reads inventory.ini| G[Ansible Playbook Run]
    G -->|Configures Firewall & Installs| H[Coolify on VPS]
    H --> I[Ready to Use on Port 8000/80/443]

1. Gitea Actions is triggered on a push to the default branch.
2. Terraform provisions an OVH Public Cloud instance (acting as our VPS), registers the deployment public SSH key on the instance, and outputs the public IP address.
3. Terraform dynamically creates the Ansible inventory.ini using the provisioned VPS public IP.
4. Ansible waits for SSH to become ready, updates system packages, configures the ufw firewall (opening ports 22, 80, 443, 8000, 6001), and runs the official non-interactive Coolify installation script safely and idempotently.

---

📁 Repository Structure

├── .gitea/
│   └── workflows/
│       └── deploy.yml          # Gitea Actions CI/CD workflow configuration
├── ansible/
│   ├── ansible.cfg             # Ansible master configuration
│   ├── inventory.tpl           # Template file for dynamic inventory generation
│   └── playbook.yml            # Playbook to configure VPS and install Coolify
├── terraform/
│   ├── main.tf                 # Terraform core resources (OVH instance, SSH key)
│   ├── outputs.tf              # Outputs the VPS IP address and Instance ID
│   ├── providers.tf            # Configures the OVH Terraform Provider
│   └── variables.tf            # Input variables with sensible defaults
├── .gitignore                  # Prevents secrets/state files from being committed
└── README.md                   # This documentation file

---

⚙️ Prerequisites

To run this pipeline, you will need:

1. An OVH Cloud Account with an active Public Cloud Project.
2. OVH API Credentials with permissions to manage Public Cloud resources.
3. A Gitea Instance with Gitea Actions enabled and a runner registered.

🔑 Step 1: Generate OVH API Credentials

Go to OVH API Keys Creation Page (or the corresponding URL for your OVH region, e.g. CA or US) and create a new set of API keys. Give your token access to /cloud/* and /me/* paths.

Once created, you will receive:

• Application Key (AK)
• Application Secret (AS)
• Consumer Key (CK)

You also need your Public Cloud Project ID (often called Service Name). This can be found on your OVH Public Cloud Dashboard (it is a string of letters and numbers like sb123456-ovh).

🗝️ Step 2: Generate an SSH Keypair

Generate an SSH keypair that Gitea Actions will use to authenticate with the new VPS:

ssh-keygen -t ed25519 -f id_rsa -N "" -C "gitea-actions-coolify"

This generates:

• id_rsa (Private key, to be saved in Gitea secrets)
• id_rsa.pub (Public key, to be saved in Gitea secrets)

---

🔒 Step 3: Configure Gitea Secrets

In your Gitea repository, navigate to Settings > Actions > Secrets and add the following secrets:

Secret Name	Description	Example / Format
OVH_APPLICATION_KEY	Your OVH API Application Key	xxxxxx
OVH_APPLICATION_SECRET	Your OVH API Application Secret	xxxxxx
OVH_CONSUMER_KEY	Your OVH API Consumer Key	xxxxxx
OVH_SERVICE_NAME	Your OVH Public Cloud Project ID	ab123456-ovh-eu-1
SSH_PUBLIC_KEY	Content of the generated id_rsa.pub	ssh-ed25519 AAAAC3...
SSH_PRIVATE_KEY	Content of the generated id_rsa	-----BEGIN OPENSSH PRIVATE KEY-----...

---

💻 Running Terraform Locally

If you want to run Terraform locally to inspect, plan, or deploy from your own machine, you can do so while keeping the state synchronized with your Gitea Actions pipeline.

Step 1: Install Terraform

Make sure you have the Terraform CLI installed (>= 1.3.0).

Step 2: Configure Local Credentials

Create a file named terraform.tfvars inside the terraform/ directory. (Note: This file is already configured in .gitignore to prevent committing credentials).

ovh_endpoint           = "ovh-eu"
ovh_application_key    = "your_ovh_application_key"
ovh_application_secret = "your_ovh_application_secret"
ovh_consumer_key       = "your_ovh_consumer_key"
ovh_service_name       = "your_ovh_public_cloud_project_id"
ssh_public_key         = "your_ssh_public_key_content" # or file("~/.ssh/id_rsa.pub")

Step 3: Initialize with Gitea State Backend

To keep your state synchronized with Gitea Actions, run terraform init locally and point it to Gitea's built-in Terraform State Registry:

cd terraform

terraform init \
  -backend-config="address=https://<your-gitea-domain>/api/v1/packages/<your-gitea-username>/terraform/state/coolify" \
  -backend-config="username=<your-gitea-username>" \
  -backend-config="password=<your-gitea-token-or-password>"

Step 4: Plan and Apply

Now you can plan and apply your local changes. They will automatically read from and write to the exact same state file as Gitea Actions:

# Preview changes
terraform plan

# Apply changes to provision/update the VPS
terraform apply

---

🛠️ Customization

You can customize the deployment by overriding the default values in terraform/variables.tf:

• OVH Endpoint (ovh_endpoint): Defaults to ovh-eu. Change to ovh-ca or ovh-us depending on your account region.
• Region (region): Defaults to GRA11 (Gravelines, France). Other popular regions: SBG5 (Strasbourg), WAW1 (Warsaw), DE1 (Frankfurt), UK1 (London).
• Instance Size/Flavor (flavor_name): Defaults to b2-7 (2 vCPUs, 7 GB RAM). If you want a smaller/starter setup, you can use s1-2 (1 vCPU, 2 GB RAM) or d2-4 (2 vCPUs, 4 GB RAM). Coolify operates best with at least 2 vCPUs and 4 GB RAM.
• Operating System (image_name): Defaults to Ubuntu 22.04. Coolify supports Ubuntu 22.04/24.04 and Debian 11/12 out of the box.

---

🚀 Post-Deployment: Accessing Coolify

Once the Gitea Actions pipeline completes successfully:

1. Copy the public IP address of the server from the Terraform output or the Gitea Actions log.
2. Open your browser and navigate to http://<your-vps-ip>:8000.
3. Register your administrator account.
4. Set up your wild-card domain or custom domains inside Coolify!

Enjoy your brand-new, self-hosted, enterprise-grade PaaS on OVH VPS!