Initial commit

README.md

@@ -0,0 +1,145 @@
+# VM Service Template
+
+This repository is a starter template for deploying one or more service VMs in Proxmox using Terraform, then configuring and launching applications with Ansible and Docker Compose.
+
+It is designed to work with a shared Terraform module stored in a separate repository. This repo acts as the wrapper/root module and provides the service-specific inputs, deployment workflow, and app stack files.
+
+## What this repo does
+
+- Creates one or more Proxmox VMs from a reusable Terraform module.
+- Uses cloud-init and QEMU guest agent in the template VM.
+- Writes the VM IP address into Ansible inventory.
+- Tags VMs with Terraform, Docker, service name, and IP metadata.
+- Deploys an application stack with Ansible and Docker Compose.
+
+## Repository layout
+
+```text
+terraform/   Terraform wrapper for the shared Proxmox module.
+compose/     Docker Compose application files.
+ansible/     Playbook and role used to configure and deploy the app.
+.gitea/      Workflow files for apply and deploy.
+```
+
+## Requirements
+
+- Terraform installed locally or in CI.
+- Access to the Proxmox API.
+- A shared Proxmox VM module in a separate repository.
+- Ansible installed for application deployment.
+- Docker and Docker Compose available on the target VM.
+
+## How it works
+
+1. Terraform reads the instance configuration from `terraform.tfvars`.
+2. Terraform calls the shared Proxmox module to create the VM.
+3. Terraform outputs the VM IP address and tags.
+4. The workflow writes the IP into `ansible/inventory/hosts.ini`.
+5. Ansible connects to the VM and deploys the Compose stack.
+
+## Single instance
+
+Use `instance_mode = "single"` and define one `instance` object.
+
+Example:
+
+```hcl
+instance_mode = "single"
+
+instance = {
+  service_name = "grafana"
+  vm_name      = "grafana-01"
+  node_name    = "pop"
+  app_port     = 3000
+  app_image    = "grafana/grafana:latest"
+  vm_tags      = ["monitoring"]
+}
+```
+
+## Multi instance
+
+Use `instance_mode = "multi"` and define an `instances` map.
+
+Example:
+
+```hcl
+instance_mode = "multi"
+
+instances = {
+  grafana = {
+    service_name = "grafana"
+    vm_name      = "grafana-01"
+    node_name    = "pop"
+    app_port     = 3000
+    app_image    = "grafana/grafana:latest"
+    vm_tags      = ["monitoring"]
+  }
+
+  caddy = {
+    service_name = "caddy"
+    vm_name      = "caddy-01"
+    node_name    = "pop"
+    app_port     = 80
+    app_image    = "caddy:latest"
+    vm_tags      = ["proxy"]
+  }
+}
+```
+
+## Defaults
+
+The template supports module defaults for items like:
+
+- datastore
+- BIOS
+- machine type
+- SSH key
+- bridge
+- CPU, RAM, and disk size
+
+Override only what you need in the service repo.
+
+## Running locally
+
+```bash
+cd terraform
+cp single.tfvars.example terraform.tfvars
+terraform init
+terraform apply
+```
+
+After Terraform finishes, run:
+
+```bash
+cd ..
+ansible-playbook -i ansible/inventory/hosts.ini ansible/playbooks/deploy.yml
+```
+
+## Workflow trigger
+
+This template is intended to be run after the repository is created from it.
+
+The usual flow is:
+
+- create a new repo from this template,
+- update the tfvars file,
+- trigger the workflow manually with `workflow_dispatch`,
+- or push the first commit to start deployment.
+
+## Notes
+
+- The shared Proxmox module should live in a separate repository.
+- The service repo should contain the wrapper, not the internal Proxmox resource logic.
+- VM IP tags are generated after Terraform apply.
+- If the VM disk is resized manually in Proxmox, Terraform may see drift on the next run.
+
+## Example use case
+
+This template works well for service VMs such as:
+
+- Grafana
+- Caddy
+- Jellyfin
+- Code Server
+- Monitoring or proxy VMs
+