From e4cccc8a3a26a83c0480aef19a1524d35fc819b6 Mon Sep 17 00:00:00 2001
From: alessandrovitali <mail@alessandrovitali.net>
Date: Tue, 18 Aug 2026 16:12:55 +0200
Subject: [PATCH] feat: add README

---
 .gitignore |  1 +
 README.md  | 76 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 77 insertions(+)
 create mode 100644 README.md

diff --git a/.gitignore b/.gitignore
index 807de7f..7bd638e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,6 +6,7 @@
 
 # Secrets
 .env
+.envrc
 
 # Ansible
 ansible/inventory.ini
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..423b491
--- /dev/null
+++ b/README.md
@@ -0,0 +1,76 @@
+# dokploy
+
+Terraform + Ansible setup for a self-hosted [Dokploy](https://dokploy.com/) instance.
+
+## Setup
+
+1. Create a Hetzner Cloud API key
+2. Create a Cloudflare DNS key with `Zone.DNS` edit permission
+
+### Local setup
+
+Secrets live in `terraform/.env` and are injected as `TF_VAR_*` environment
+variables into the local shell session:
+
+```env
+TF_VAR_hcloud_token=...
+TF_VAR_cloudflare_api_token=...
+TF_VAR_domain_name=...
+```
+
+#### direnv
+
+Setup direnv on the development machine and add `terraform/.envrc`:
+
+```env
+dotenv_if_exists .env
+```
+
+Then load the variables into the shell:
+
+```sh
+cd terraform
+direnv allow
+```
+
+Run Terraform / Tofu manually:
+```sh
+tofu init
+tofu plan
+tofu apply
+```
+
+#### Without direnv
+
+Load the file manually, scoped to a single command:
+
+```sh
+cd terraform
+set -a; . ./.env; set +a
+tofu plan
+```
+
+Or use a wrapper that keeps the variables contained to the `tofu` subprocess:
+
+```sh
+#!/bin/sh
+set -a
+. ./.env
+set +a
+exec tofu "$@"
+```
+
+## CI/CD
+
+CI reads the same variables from the git forge's secret store — no `.env` file is needed.
+
+Add the necessary variables 
+
+GitHub Actions example:
+
+```yaml
+env:
+  TF_VAR_hcloud_token: ${{ secrets.TF_VAR_HCLOUD_TOKEN }}
+  TF_VAR_cloudflare_api_token: ${{ secrets.TF_VAR_CLOUDFLARE_API_TOKEN }}
+  TF_VAR_domain_name: ${{ secrets.TF_VAR_DOMAIN_NAME }}
+```