From 112e62fed611e3ced53d2978573673da72174a6f Mon Sep 17 00:00:00 2001
From: gaia <gaia@gaia.com>
Date: Thu, 9 Apr 2026 12:44:52 -0300
Subject: [PATCH] docs: rewrite README with clean structure and 4-layer
 architecture overview

- Remove old content (next steps executados, arquitetura defasada)
- Add clean repo structure
- Document how Picsur deploy works
- Add inventory files table
- Add next steps roadmap
---
 README.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7fd89c2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,78 @@
+# Homelab — Infraestrutura como Código
+
+> Guardiã: **Gaia** (Agente Hermes)
+> Dono: João Paulo Ferreira (jp@iamferreirajp.com)
+> Repo: [gaia/homelab](https://gitea.hackerfortress.cc/gaia/homelab)
+
+## Visão Geral
+
+Todo o homelab versionado como **IaC** — Infrastructure as Code. O objetivo: ter o ambiente completo documentado e reproduzível, do físico ao serviço.
+
+## Arquitetura em 4 camadas
+
+```
+inventory/         # Camada 0 — Single Source of Truth (máquinas, IPs, discos)
+terraform/         # Camada 1 — Provisão (VMs, pools, rede)
+ansible/           # Camada 2 — Configuração de OS
+services/          # Camada 3 — Aplicações (Docker Compose)
+```
+
+## Inventário
+
+| Arquivo | Conteúdo |
+|---------|----------|
+| `inventory/physical.yaml` | Máquinas físicas, MACs, IPs |
+| `inventory/proxmox.yaml` | VMs e LXC no Proxmox |
+| `inventory/truenas.yaml` | Discos ZFS, pools, datasets |
+| `inventory/network.yaml` | VLANs, subnets, DNS |
+
+## Serviços ativos
+
+```
+services/dockerino/       # 11 serviços via Docker Compose
+  ├── picsur/            # Galeria de imagens
+  ├── adguard/           # DNS + bloqueador
+  ├── nginx-proxy/       # Reverse proxy + Let's Encrypt
+  ├── outline/           # Wiki colaborativa
+  ├── bookstack/         # Wiki/notes
+  ├── homer/             # Dashboard
+  └── ... (mais)
+
+services/media/          # Jellyfin (media server)
+```
+
+## CI/CD — Gitea Actions
+
+Workflows em `.gitea/workflows/`:
+- `picsur.yml` — valida e faz deploy do Picsur via SSH no Dockerino
+
+## Como funciona o deploy do Picsur
+
+1. PR aberto → Gitea Actions valida (`docker compose config`, `docker compose pull`)
+2. Merge para `main` → deploy automático via SSH:
+   ```bash
+   ssh root@10.0.0.50
+   rsync -avz services/dockerino/picsur/ /root/dockerino/picsur/
+   docker compose up -d
+   ```
+
+## Próximos passos
+
+1. Preencher `inventory/` com dados reais do Proxmox e TrueNAS
+2. Configurar Terraform Cloud via API (state versionado)
+3. Migrar deploy do Picsur para ler do inventory (não hardcoded)
+4. Expandir para os outros serviços
+
+## Estrutura atual do repo
+
+```
+homelab/
+├── .gitea/workflows/       # CI/CD
+├── ansible/                 # (em construção)
+├── gitea-runner/           # Runner de CI/CD
+├── inventory/              # Single Source of Truth
+├── services/              # Docker Compose por serviço
+│   ├── dockerino/         # 11 serviços
+│   └── media/             # Jellyfin
+└── terraform/             # (em construção)
+```