164 lines
7.1 KiB
Markdown
164 lines
7.1 KiB
Markdown
# 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:
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```text
|
|
├── .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](https://eu.api.ovh.com/createToken/) (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:
|
|
|
|
```bash
|
|
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).*
|
|
|
|
```hcl
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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!
|