ealmeida/claude-plugins
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: refactor 30+ skills to Anthropic progressive disclosure pattern

Browse Source 
- All SKILL.md files now <500 lines (avg reduction 69%)
- Detailed content extracted to references/ subdirectories
- Frontmatter standardised: only name + description (Anthropic standard)
- New skills: brand-guidelines, spec-coauthor, report-templates, skill-creator
- Design skills: anti-slop guidelines, premium-proposals reference
- Removed non-standard frontmatter fields (triggers, version, author, category)

Plugins affected: infraestrutura, marketing, dev-tools, crm-ops, gestao,
core-tools, negocio, perfex-dev, wordpress, design-media

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Emanuel Almeida
2026-03-12 15:05:03 +00:00
parent 9404af7ac9
commit 6b3a6f2698
397 changed files with 67154 additions and 17257 deletions
Download Patch File Download Diff File Expand all files Collapse all files

465
infraestrutura/skills/proxmox-setup/SKILL.md
View File

@@ -1,20 +1,11 @@
---
name: proxmox-setup
description: Instalação completa de Proxmox VE 8.x em Hetzner - installimage, ZFS RAID-1, NAT networking, vSwitch. Use when user mentions "proxmox install", "setup proxmox", "proxmox hetzner", "new proxmox node".
author: Descomplicar® Crescimento Digital
version: 1.0.0
quality_score: 75
user_invocable: true
desk_task: 1712
allowed-tools: Task, Read, Bash
dependencies:
- ssh-unified
- notebooklm
description: Instalacao completa de Proxmox VE 8.x em Hetzner -- installimage, ZFS RAID-1, NAT networking single-IP e vSwitch com optimizacoes.
---
# Proxmox Setup
Instalação completa e configuração de Proxmox VE 8.x em servidor dedicado Hetzner com ZFS RAID-1, networking NAT single-IP e optimizações.
Instalacao completa e configuracao de Proxmox VE 8.x em servidor dedicado Hetzner com ZFS RAID-1, networking NAT single-IP e optimizacoes.
## Quando Usar
@@ -22,7 +13,6 @@ Instalação completa e configuração de Proxmox VE 8.x em servidor dedicado He
- Setup inicial com ZFS mirror NVMe
- Configurar networking NAT para single-IP
- Preparar node para clustering futuro
- Aplicar Hetzner-specific gotchas e optimizações
## Sintaxe
@@ -30,19 +20,6 @@ Instalação completa e configuração de Proxmox VE 8.x em servidor dedicado He
/proxmox-setup <server-ip> <hostname> [--zfs-pool rpool] [--arc-max 16G] [--vswitch]
```
## Exemplos
```bash
# Setup básico single-IP NAT
/proxmox-setup 138.201.45.67 cluster.descomplicar.pt
# Setup com vSwitch (MTU 1400)
/proxmox-setup 138.201.45.67 cluster.descomplicar.pt --vswitch
# Custom ZFS ARC (para 64GB RAM)
/proxmox-setup 138.201.45.67 pve-node1.descomplicar.pt --arc-max 8G
```
## Knowledge Sources (Consultar SEMPRE)
### NotebookLM Proxmox Research
@@ -53,104 +30,35 @@ mcp__notebooklm__notebook_query \
```
### Hub Docs
- `/media/ealmeida/Dados/Hub/05-Projectos/Cluster Descomplicar/Research/Proxmox-VE/Guia-Definitivo-Proxmox-Hetzner.md`
- Módulo 1: Instalação (installimage, ZFS vs LVM, Kernel PVE)
- Módulo 2: Networking (NAT masquerading, vSwitch MTU 1400)
- `Hub/05-Projectos/Cluster Descomplicar/Research/Proxmox-VE/Guia-Definitivo-Proxmox-Hetzner.md`
---
## Workflow Completo
### Fase 1: Pre-Installation Checks
**1.1 Verificar Rescue Mode**
```bash
# Via SSH MCP
# Via SSH MCP - verificar Rescue Mode
mcp__ssh-unified__ssh_execute \
server:"hetzner-rescue" \
command:"uname -a && df -h"
# Expected: rescue kernel, /dev/md* present
```
**1.2 Consultar NotebookLM para Hardware Specs**
```bash
# Query: "hetzner installimage zfs raid configuration"
# Obter template correcto para specs do servidor
```
**1.3 Backup de Configuração Actual (se aplicável)**
```bash
ssh root@SERVER_IP "tar -czf /tmp/backup-configs.tar.gz /etc /root"
scp root@SERVER_IP:/tmp/backup-configs.tar.gz ~/backups/
```
Consultar NotebookLM para hardware specs e template correcto.
### Fase 2: installimage com ZFS RAID-1
**2.1 Criar Template installimage**
Detalhes completos do template installimage e configuracao ZFS em: `references/installimage-zfs.md`
Template base para 2x NVMe 1TB + HDD 16TB:
```bash
DRIVE1 /dev/nvme0n1
DRIVE2 /dev/nvme1n1
SWRAID 0
SWRAIDLEVEL 0
BOOTLOADER grub
HOSTNAME HOSTNAME_PLACEHOLDER
PART /boot ext3 1024M
PART lvm vg0 all
LV vg0 root / ext4 50G
LV vg0 swap swap swap 16G
LV vg0 tmp /tmp ext4 10G
LV vg0 home /home ext4 20G
IMAGE /root/images/Debian-bookworm-latest-amd64-base.tar.gz
```
**CRITICAL: Depois de boot, converter para ZFS:**
**2.2 Executar installimage**
```bash
# No Rescue Mode
installimage
# Seleccionar Debian 12 (Bookworm)
# Copiar template acima
# Salvar e confirmar
# Reboot automático
```
**2.3 Conversão para ZFS (Pós-Install)**
**IMPORTANTE:** installimage não suporta ZFS directamente. Workflow:
1. Instalar Debian 12 com LVM (installimage)
Resumo do workflow:
1. Instalar Debian 12 com LVM via installimage
2. Boot em Debian
3. Instalar ZFS + Proxmox
4. Migrar para ZFS pool (ou aceitar LVM para root, ZFS para VMs)
**Opção A: ZFS para VMs apenas (RECOMENDADO para Hetzner)**
```bash
# Criar ZFS pool em NVMe para VMs
zpool create -f \
-o ashift=12 \
-o compression=lz4 \
-o atime=off \
rpool mirror /dev/nvme0n1p3 /dev/nvme1n1p3
# Criar datasets
zfs create rpool/vm-disks
zfs create rpool/ct-volumes
```
**Opção B: ZFS root (AVANÇADO - requer reinstall manual)**
- Não suportado por installimage
- Requer particionamento manual + debootstrap
- Consultar: https://pve.proxmox.com/wiki/ZFS_on_Linux
**Recomendação para Cluster Descomplicar:** Opção A (LVM root, ZFS para VMs)
4. Criar ZFS pool para VMs (Opcao A recomendada: LVM root, ZFS para VMs)
### Fase 3: Proxmox VE 8.x Installation
**3.1 Configurar Repositórios Proxmox**
```bash
# Adicionar repo Proxmox
echo "deb [arch=amd64] http://download.proxmox.com/debian/pve bookworm pve-no-subscription" > /etc/apt/sources.list.d/pve-install-repo.list
@@ -158,375 +66,86 @@ echo "deb [arch=amd64] http://download.proxmox.com/debian/pve bookworm pve-no-su
# Adicionar key
wget https://enterprise.proxmox.com/debian/proxmox-release-bookworm.gpg -O /etc/apt/trusted.gpg.d/proxmox-release-bookworm.gpg
# Update
# Update e instalar
apt update && apt full-upgrade
```
**3.2 Instalar Proxmox VE**
```bash
apt install proxmox-ve postfix open-iscsi chrony
```
**Configuração Postfix:**
- Seleccionar "Local only"
- System mail name: HOSTNAME
**3.3 Remover Kernel Debian (usar PVE kernel)**
```bash
# Verificar kernel actual
uname -r # Should be pve kernel
# Remover kernel Debian se boot em PVE kernel
# Remover kernel Debian (apos boot em PVE kernel)
apt remove linux-image-amd64 'linux-image-6.1*'
update-grub
```
**3.4 Reboot em Proxmox Kernel**
```bash
reboot
```
### Fase 4: ZFS Tuning (128GB RAM)
### Fase 4: ZFS Tuning
**4.1 Configurar ARC Limits**
```bash
# ARC max 16GB (deixa 110GB para VMs)
# ARC min 4GB
echo "options zfs zfs_arc_max=17179869184" >> /etc/modprobe.d/zfs.conf
echo "options zfs zfs_arc_min=4294967296" >> /etc/modprobe.d/zfs.conf
# Aplicar
update-initramfs -u -k all
```
**4.2 Optimizar ZFS para NVMe**
```bash
# Verificar ashift (deve ser 12 para NVMe 4K sectors)
zdb -C rpool | grep ashift
# Activar compression LZ4 (se ainda não)
zfs set compression=lz4 rpool
# Disable atime (performance)
zfs set atime=off rpool
# Snapshot visibility
zfs set snapdir=hidden rpool
```
**4.3 Criar ZFS Datasets para PBS (se HDD 16TB)**
```bash
# Dataset para PBS datastore
zfs create rpool/pbs-datastore
zfs set mountpoint=/mnt/pbs-datastore rpool/pbs-datastore
zfs set compression=lz4 rpool/pbs-datastore
zfs set dedup=off rpool/pbs-datastore
```
Detalhes em: `references/installimage-zfs.md` (seccao ZFS Tuning)
### Fase 5: Networking NAT (Single-IP Hetzner)
**5.1 Configurar /etc/network/interfaces**
Configuracao completa de NAT, port forwarding e vSwitch em: `references/networking-nat.md`
**Template para Single-IP NAT:**
```bash
auto lo
iface lo inet loopback
### Fase 6: Proxmox Web UI + Storage
# Interface física (verificar nome com 'ip a')
auto eno1
iface eno1 inet static
address SERVER_IP/32
gateway GATEWAY_IP
pointopoint GATEWAY_IP
# Bridge interna para VMs (NAT)
auto vmbr0
iface vmbr0 inet static
address 10.10.10.1/24
bridge-ports none
bridge-stp off
bridge-fd 0
# NAT masquerading
post-up echo 1 > /proc/sys/net/ipv4/ip_forward
post-up iptables -t nat -A POSTROUTING -s '10.10.10.0/24' -o eno1 -j MASQUERADE
post-down iptables -t nat -D POSTROUTING -s '10.10.10.0/24' -o eno1 -j MASQUERADE
```
**CRITICAL Hetzner Gotchas:**
- Gateway /32 point-to-point (não /24 ou /26)
- IP e gateway podem estar em subnets diferentes
- Verificar IP real e gateway no Hetzner Robot
**5.2 Aplicar Networking**
```bash
# Test config
ifup --no-act vmbr0
# Apply
systemctl restart networking
# Verificar
ip a
ping -c 3 8.8.8.8
```
**5.3 Port Forwarding (Opcional - para expor VMs)**
```bash
# Exemplo: Redirecionar porta 8080 host → porta 80 VM 10.10.10.100
iptables -t nat -A PREROUTING -i eno1 -p tcp --dport 8080 -j DNAT --to 10.10.10.100:80
# Persistir com iptables-persistent
apt install iptables-persistent
iptables-save > /etc/iptables/rules.v4
```
### Fase 6: vSwitch Configuration (Opcional)
**Se --vswitch flag presente:**
**6.1 Configurar VLAN no Robot Panel**
- Hetzner Robot → vSwitch → Create VLAN
- Anotar VLAN ID (ex: 4000)
**6.2 Adicionar ao /etc/network/interfaces**
```bash
# vSwitch interface (MTU 1400 OBRIGATÓRIO)
auto enp7s0.4000
iface enp7s0.4000 inet manual
mtu 1400
# Bridge vSwitch
auto vmbr1
iface vmbr1 inet static
address 10.0.0.1/24
bridge-ports enp7s0.4000
bridge-stp off
bridge-fd 0
mtu 1400
```
**CRITICAL:** MTU 1400 não negociável para vSwitch Hetzner.
### Fase 7: Proxmox Web UI + Storage
**7.1 Aceder Web UI**
```
https://SERVER_IP:8006
User: root
Password: (root password do servidor)
```
**7.2 Remover Enterprise Repo (se no-subscription)**
```bash
# Comentar enterprise repo
sed -i 's/^deb/#deb/' /etc/apt/sources.list.d/pve-enterprise.list
# Verificar
apt update
```
**7.3 Configurar Storage no Web UI**
- Datacenter → Storage → Add
- **Directory:** Local (já existe)
- **ZFS:** rpool/vm-disks (para VMs)
- **PBS:** Adicionar PBS server (se já instalado)
Storage no Web UI: Datacenter -> Storage -> Add (Directory, ZFS, PBS).
### Fase 8: Validation Checklist
### Fase 7: Validation Checklist
**8.1 Verificações Técnicas**
```bash
# PVE version
pveversion -v
# ZFS status
zpool status
zpool list
zfs list
# Networking
ping -c 3 8.8.8.8
curl -I https://www.google.com
# Web UI
curl -k https://localhost:8006
# ARC stats
arc_summary | grep "ARC size"
pveversion -v # PVE version
zpool status # ZFS status
zpool list && zfs list
ping -c 3 8.8.8.8 # Networking
curl -k https://localhost:8006 # Web UI
arc_summary | grep "ARC size" # ARC stats
```
**8.2 Security Hardening**
**Security Hardening:**
```bash
# SSH: Disable root password (usar keys)
sed -i 's/#PermitRootLogin yes/PermitRootLogin prohibit-password/' /etc/ssh/sshd_config
systemctl restart sshd
# Firewall básico (opcional - configurar via Web UI depois)
pve-firewall start
```
**8.3 Criar VM Teste**
```bash
# Via CLI (ou Web UI)
qm create 100 \
--name test-vm \
--memory 1024 \
--cores 1 \
--net0 virtio,bridge=vmbr0 \
--ide2 local:iso/debian-12.iso,media=cdrom \
--bootdisk scsi0 \
--scsi0 rpool/vm-disks:10
# Start
qm start 100
# Verificar consegue aceder internet (NAT funcional)
```
## Output Summary
```
✅ Proxmox VE 8.x instalado: HOSTNAME
🖥️ Hardware:
- CPU: (detect)
- RAM: 128GB (ARC max 16GB, disponível 110GB para VMs)
- Storage: 2x 1TB NVMe ZFS RAID-1 + 16TB HDD
💾 Storage:
- ZFS pool: rpool (mirror)
- Compression: LZ4 (ratio ~1.5x)
- ARC: 4GB min, 16GB max
- Datasets: vm-disks, ct-volumes, pbs-datastore
🌐 Networking:
- Mode: NAT masquerading (single-IP)
- Internal subnet: 10.10.10.0/24
- Gateway: GATEWAY_IP (point-to-point)
[Se vSwitch] vSwitch VLAN 4000: 10.0.0.0/24 (MTU 1400)
🔐 Access:
- Web UI: https://SERVER_IP:8006
- SSH: root@SERVER_IP (key only)
- API: https://SERVER_IP:8006/api2/json
📋 Next Steps:
1. Configurar firewall via Web UI (Datacenter → Firewall)
2. Criar API token para Terraform (/pve-api-token)
3. Setup PBS (/pbs-config)
4. Criar Cloud-Init templates
5. Migrar workloads (/vm-migration)
6. [Futuro] Cluster formation (/proxmox-cluster)
⚠️ Hetzner Gotchas Applied:
✓ Gateway /32 point-to-point
✓ NAT masquerading (MAC filtering bypass)
✓ vSwitch MTU 1400 (se aplicável)
✓ ZFS ARC tuning
✓ PVE kernel (não Debian stock)
⏱️ Setup time: ~45min (vs 2h manual)
```
## Hetzner-Specific Gotchas (CRITICAL)
### 1. MAC Filtering
**Problema:** Bridged networking com MAC não registado = bloqueado
**Solução aplicada:** NAT masquerading (bypass MAC filtering)
**Alternativa:** Pedir virtual MAC no Robot panel (grátis)
### 2. Gateway Point-to-Point
**Problema:** Gateway fora da subnet do IP principal
**Solução:** `address IP/32` + `pointopoint GATEWAY` (não /24 ou /26)
### 3. vSwitch MTU 1400
**Problema:** vSwitch Hetzner requer MTU 1400 (não 1500 standard)
**Solução:** Forçar `mtu 1400` em vmbr1 e enp7s0.4000
### 4. ZFS vs LVM Trade-off
**Problema:** installimage não suporta ZFS root directo
**Solução:** LVM para root (compatibilidade), ZFS para VMs (performance)
### 5. Kernel PVE vs Debian
**Problema:** Kernel stock Debian não optimizado para virtualização
**Solução:** Instalar proxmox-ve + remover kernel Debian
---
## Troubleshooting
### Web UI não acessível
```bash
# Verificar serviço
systemctl status pveproxy
| Problema | Comando diagnostico |
|----------|-------------------|
| Web UI nao acessivel | `systemctl status pveproxy` + `journalctl -u pveproxy -f` |
| VMs sem internet (NAT) | `cat /proc/sys/net/ipv4/ip_forward` + `iptables -t nat -L -n -v` |
| ZFS ARC nao limita | `cat /sys/module/zfs/parameters/zfs_arc_max` |
| vSwitch MTU issues | `ping -M do -s 1372 10.0.0.2` |
# Logs
journalctl -u pveproxy -f
---
# Firewall
iptables -L -n -v | grep 8006
```
## Quando NAO Usar
### VMs sem internet (NAT)
```bash
# Verificar IP forwarding
cat /proc/sys/net/ipv4/ip_forward # Should be 1
- Para servidores non-Hetzner (diferentes gotchas de networking)
- Para Proxmox ja instalado (usar outras skills de config)
- Para troubleshooting (criar skill especifica)
# Verificar iptables NAT
iptables -t nat -L -n -v
# Re-aplicar regras
ifdown vmbr0 && ifup vmbr0
```
### ZFS ARC não limita
```bash
# Verificar configs
cat /sys/module/zfs/parameters/zfs_arc_max
# Re-aplicar
modprobe -r zfs
modprobe zfs
```
### vSwitch MTU issues
```bash
# Forçar MTU em todas interfaces
ip link set enp7s0.4000 mtu 1400
ip link set vmbr1 mtu 1400
# Test
ping -M do -s 1372 10.0.0.2 # 1372 = 1400 - 28 (headers)
```
---
## References
- `references/installimage-zfs.md` - Template installimage, conversao ZFS, tuning ARC
- `references/networking-nat.md` - NAT single-IP, port forwarding, vSwitch, gotchas Hetzner
- **NotebookLM:** 276ccdde-6b95-42a3-ad96-4e64d64c8d52 (150+ fontes)
- **Guia Definitivo:** Hub/05-Projectos/Cluster Descomplicar/Research/Proxmox-VE/Guia-Definitivo-Proxmox-Hetzner.md
- **Proxmox Docs:** https://pve.proxmox.com/pve-docs/pve-admin-guide.html
- **Hetzner Docs:** https://docs.hetzner.com/robot/dedicated-server/
---
**Versão:** 1.0.0 | **Autor:** Descomplicar® | **Data:** 2026-02-14
## Metadata (Desk CRM Task #1712)
```
Projeto: Cluster Proxmox Descomplicar (#65)
Tarefa: Migração Infraestrutura para Cluster Proxmox HA (#1712)
Milestone: TBD
Tags: proxmox, pve, hetzner, zfs, networking, instalacao
Status: Research → Implementation
```
---
**/** @author Descomplicar® | @link descomplicar.pt | @copyright 2026 **/
---
## Quando NÃO Usar
- Para servidores non-Hetzner (diferentes gotchas de networking)
- Para Proxmox já instalado (usar outras skills de config)
- Para troubleshooting (criar skill específica)
Projecto: Cluster Proxmox Descomplicar (#65) | Tarefa: #1712