From e888ea338f23f51ef1cb202260a691a499c930cd Mon Sep 17 00:00:00 2001
From: JulienAldon <julien.aldon@wanadoo.fr>
Date: Tue, 20 Jan 2026 00:49:58 +0100
Subject: [PATCH] add instructions to add a module to terraform

---
 README.md | 84 +++++++++++++++++++++++++++++++++----------------------
 1 file changed, 51 insertions(+), 33 deletions(-)

diff --git a/README.md b/README.md
index d44823d..bfdf515 100644
--- a/README.md
+++ b/README.md
@@ -28,7 +28,6 @@ cp terraform.tfvars.example
 ```
 fill with your secrets (do no push this file)
 
-
 ## Usefull commands
 ```sh
 opentofu.tofu init
@@ -51,11 +50,17 @@ ssh-add ~/.ssh/id_ed25519
 ```
 
 ## Add new service
-### Create base module
+### Create backup folder on proxmox host
+```sh
+mkdir /main/backups/<service-name>
+```
+
+### Create a module
 ```sh
 mkdir modules/apps/<module-hostname>
 ```
-Example
+
+Example tree
 ```sh
 modules/apps/bookshelf/
 ├── cloud-init
@@ -71,7 +76,7 @@ modules/apps/bookshelf/
 └── .env
 ```
 
-#### main.tf
+#### `modules/apps/<service-name>/main.tf`
 
 ```hcl
 module "vm" {
@@ -98,38 +103,46 @@ module "vm" {
         domain          = var.domain
         ssh_key         = var.ssh_public_key
         proxmox_host_ip = var.proxmox_host_ip
-        environment-setup-script = indent(6, file("${path.module}/lib/scripts/env.sh"))
+        environment-setup-script = indent(6, file("${path.module}/../common/scripts/env.sh"))
         env-file-content = indent(6, file("${path.module}/.env"))
       }
     )
 }
 ```
 
-Add inside templatefile object scripts content to upload with `cloud-init`.
-
-#### variables.tf
+Add inside `templatefile()` object scripts content to upload with `cloud-init` :
+- Backups scripts
+- Backups services
+- Install scripts
+- Application services
 
+#### `modules/apps/<service-name>/variables.tf`
 ```hcl
 variable "name" {
+  description = "Virtual Machine name"
   type = string
 }
 
 variable "vm_id" {
+  description = "Virtual Machine id"
   type = number
 }
 
 variable "node_name" {
-  type    = string
+  description = "Proxmox node name"
+  type = string
   default = "mop"
 }
 
 variable "cores" {
-  type    = number
+  description = "Number of CPU cores for this virtual machine"
+  type = number
   default = 2
 }
 
 variable "memory" {
-  type    = number
+  description = "Memory RAM for this virtual machine" 
+  type = number
   default = 2048
 }
 
@@ -140,41 +153,45 @@ variable "balloon" {
 }
 
 variable "template_id" {
+  description = "Virtual machine template ID"
   type = number
 }
 
 variable "ssh_public_key" {
-  type        = string
   description = "Public SSH key for cloud-init user"
+  type = string
 }
 
 variable "hostname" {
-  description = "VM hostname"
-  type        = string
-  default     = "test"
+  description = "Virtual Machine hostname"
+  type = string
+  default = "test"
 }
 
 variable "domain" {
-  description = "VM domain"
-  type        = string
-  default     = ""
+  description = "Virtual Machine domain"
+  type = string
+  default = ""
 }
 
 variable "disk_size" {
-  type    = number
+  description = "Disk size for the virtual machine"
+  type = number
   default = 10
 }
 
 variable "proxmox_host_ip" {
+  description = "Proxmox host base ip"
   type = string
 }
 
 variable "vm_ip_address" {
+  description = "Virtual machine ip"
   type = string
 }
 ```
 
-#### output.tf
+#### `modules/apps/<service-name>/output.tf`
 
 ```hcl
 output "traefik_service" {
@@ -187,11 +204,10 @@ output "traefik_service" {
     }]
 }
 ```
+This `traefik_serive` variable `output.tf` supports multiple service for one VM.
 
-This output supports multiple service for one vm.
-
-#### cloud-init/service.yaml
-
+#### `cloud-init/service.yaml`
+##### Base users, groups and ssh-key
 ```hcl
 #cloud-config
 hostname: ${hostname}
@@ -212,27 +228,29 @@ disable_root: true
 
 package_update: true
 package_upgrade: false
+```
 
+##### Backup setup
+```hcl
 packages:
-  - git
   - nfs-common
 
 mounts:
   - [ "192.168.1.12:/main/backups", "/backups", "nfs", "defaults,_netdev,x-systemd.requires=network-online.target", "0", "0" ]
+```
 
+`nfs-common`: NFS mount package for `/main/backups` mount point.
+`mounts`: adds NFS mount point to `/etc/fstab` file.
+
+##### Environment variables for scripts
+```hcl
 write_files:
-  - path: /opt/bookshelf/env.sh
+  - path: /opt/<service-name>/env.sh
     permissions: "0644"
     content: |
       ${environment-setup-script}
-  - path: /opt/bookshelf/bookshelf.env
+  - path: /opt/<service-name>/<service-name>.env
     permissions: "0644"
     content: |
       ${env-file-content}
-
-runcmd:
-    - ls /
-
-final_message: |
-  Base system ready for ${hostname}
 ```
\ No newline at end of file