Ir para o conteúdo

Seção 0: Preparação e Planejamento

Antes de sair apertando botão, um planejamento cuidadoso e a preparação do ambiente são fundamentais para o sucesso do seu servidor doméstico. Tipo eu que elaborei esta wiki antes mesmo de começar a implementar. Esta seção aborda os pré-requisitos, a organização do projeto e considerações iniciais de segurança e resiliência.

0.0. Glossário de Termos Essenciais

Aqui estão algumas palavras difíceis que vão aparecer frequentemente durante a implementação:

  • Ansible: É a nossa grande ferramenta de automação. Ela automatiza configurações e instalações inteiras, criando todo o contexto para o uso a partir de código (Infraestrutura como Código - IaC).
  • Ansible Vault: Recurso do Ansible que permite criptografar arquivos YAML inteiros ou variáveis específicas que contêm dados sensíveis, como senhas e chaves de API.
  • Cloudflare Tunnel: Serviço da Cloudflare que cria um túnel seguro e criptografado de saída da sua rede local para a rede global da Cloudflare. Isso permite que você exponha serviços internos à internet sem abrir portas no seu roteador e sem expor seu IP público.
  • Container (Docker): Empacota uma aplicação para rodar isolada do sistema. Atribui a ela um endereço de IP e configurações de rede, comportando-se como se fosse uma máquina virtual, mas é só uma aplicação com suas dependências.
  • Docker Compose: Um arquivo no formato YAML que configura um container ou uma "stack" inteira (um conjunto de containers). Define redes (onde os containers interagem apenas com quem você definir), serviços (os próprios containers) e volumes (locais onde os dados dos containers ficam armazenados).
  • Proxmox VE: É um sistema operacional baseado em Debian, otimizado para rodar máquinas virtuais (KVM) e containers Linux (LXC). É a minha escolha para este projeto, visando a experimentação com diversas ferramentas.
  • Portainer: Um gerenciador de containers com interface gráfica leve e intuitiva.
  • Traefik: Proxy reverso moderno e dinâmico, e também um balanceador de carga.
  • ZFS: Sistema de arquivos avançado e gerenciador de volumes lógicos, conhecido por sua resiliência e funcionalidades.
  • NFS (Network File System): Protocolo para compartilhar diretórios através de uma rede. Usaremos para compartilhar datasets ZFS do host Proxmox com as VMs para os volumes Docker.
  • Ollama: Plataforma para rodar e gerenciar modelos de linguagem grandes (LLMs) localmente.
  • VM (Máquina Virtual): Emulação de um sistema de computador completo, rodando seu próprio sistema operacional.
  • RAG (Retrieval Augmented Generation): Técnica de Inteligência Artificial que combina as capacidades de LLMs com a busca de informação em uma base de dados externa para gerar respostas mais contextuais e precisas.
  • Authelia: Servidor de autenticação e autorização, usado aqui para fornecer Single Sign-On (SSO) e autenticação de dois fatores (2FA).

0.1. Hardware e Software Necessários

Para esta implementação, estou utilizando o seguinte setup:

Hardware do Servidor Físico (Host Proxmox)

  • CPU: AMD Ryzen 5 5600G (com iGPU Vega e suporte a virtualização AMD-V).
  • GPU (para passthrough): AMD RX 5600XT.
  • RAM: 48GB DDR4.

Upgrade de RAM

O guia original foi pensado para 16GB de RAM. Esta versão considera 48GB, o que oferece muito mais flexibilidade para o tamanho e número de VMs e serviços. As alocações de RAM para VMs serão mais generosas.

  • Armazenamento Primário (Proxmox OS e Discos das VMs): SSD NVMe 1TB.
  • Armazenamento Secundário (Pool de Dados ZFS /data): 2x HDDs de 500GB. Serão configurados em um pool ZFS espelhado (RAID 1) para redundância.

Espaço Útil ZFS para Dados

Com 2x HDDs de 500GB em espelho (RAID 1), você terá aproximadamente 500GB de espaço útil para os dados das suas aplicações Docker (configs, mídia, downloads, etc.). Planeje de acordo.

Máquina de Controle Ansible

Para esta função, você precisará de uma máquina secundária (ou sua máquina principal) para executar os comandos Ansible remotamente.

  • Um computador pessoal ou notebook.
  • Sistema Operacional Suportado:
    • Linux (Ubuntu, Fedora, etc.)
    • macOS
    • Windows com WSL2 (Windows Subsystem for Linux 2)

Rede Doméstica

  • Roteador com servidor DHCP habilitado (para atribuição inicial de IPs, embora usemos IPs estáticos para os servidores).
  • Conexão à Internet.

Software e Contas (Antes de Iniciar)

  • ISO do Proxmox VE: Baixe a versão estável mais recente do site oficial do Proxmox.
  • Ferramenta para Pendrive Bootável:
    • Ventoy (Windows, macOS, Linux) <- Minha escolha pessoal pela flexibilidade.
    • Rufus (Windows)
    • Balena Etcher (Windows, macOS, Linux)
  • Cliente SSH:
    • OpenSSH (nativo em Linux e macOS).
    • PuTTY (popular para Windows, ou use o cliente SSH nativo do Windows Terminal/PowerShell).
    • Domínio Próprio Registrado: (e.g., meudominio.com)

    Domínio Próprio é Essencial

    Este guia depende de um domínio próprio para acesso externo seguro via Cloudflare Tunnel e para a correta emissão de certificados SSL/TLS.

0.2. Estrutura do Repositório Git do Projeto (home-server)

Graças ao Ansible, vamos adotar a Infraestrutura como Código (IaC), gerenciando todas as configurações e scripts em um repositório Git.

Estrutura de Diretórios Proposta

A estrutura do seu projeto home-server/ será: 

homeserver/                 # repositório lioevano/wiki-home-server
├── server/                 # implementação (reflete a wiki)
│   ├── ansible/
│   │   ├── ansible.cfg
│   │   ├── inventories/home/
│   │   │   ├── hosts.ini
│   │   │   └── group_vars/all/
│   │   │       ├── main.yml
│   │   │       ├── vault.yml.example   # modelo versionado
│   │   │       └── vault.yml           # criptografado (ansible-vault)
│   │   ├── playbooks/          # setup-*.yml, vm-deploy.yml, full-deploy.yml
│   │   ├── roles/
│   │   │   ├── common/
│   │   │   ├── infra/          # docker, proxmox-host-config, proxmox-vm, traefik-config, authelia-config
│   │   │   ├── apps/           # desktop-environment, ml-tools
│   │   │   └── tools/          # ai-cli-tools
│   │   └── templates/          # prometheus, loki, promtail, litellm, portainer_stack_env
│   ├── docker/stacks/
│   │   ├── .env.template
│   │   ├── core/               # Traefik, Cloudflared, Authelia
│   │   ├── apps/               # Nextcloud, mídia, monitoramento, n8n, Home Assistant
│   │   └── ai/                 # Ollama, LiteLLM, Open WebUI, OpenClaw, OpenClaude, Promtail
│   └── scripts/
│       ├── bootstrap.sh
│       ├── restore.sh
│       └── validation/
├── wiki/                   # esta documentação (MkDocs): mkdocs.yml, docs/
├── tools/                  # dev.py (tarefas) e wikisync (wiki -> server)
├── .claude/                # skills e permissões do Claude Code
├── CLAUDE.md               # contexto do projeto para o Claude
├── INDEX.md                # mapa do repositório (mantido pela skill update-index)
├── .gitignore
└── README.md

Ações Imediatas para Estruturação do Projeto

Na sua máquina de controle Ansible:

  1. Crie o diretório raiz do projeto e navegue até ele: 
    mkdir home-server && cd home-server
  2. Inicialize o repositório Git: 
    git init
  3. Crie a estrutura de diretórios completa conforme detalhado no seu documento original (e resumido acima). Use mkdir -p para eficiência. Exemplo parcial: 
    mkdir -p ansible/inventories/home/group_vars/all ansible/playbooks ansible/roles/common docker/stacks/core scripts

Dica para Criar Estrutura

Você pode listar a estrutura completa e usar um script simples ou até pedir a uma IA para gerar os comandos mkdir -p para você.

  1. Crie o arquivo .gitignore com o seguinte conteúdo:

    .gitignore (raiz do repositório)
    # Ambientes Python
.venv/
venv/
wiki/venv/
__pycache__/
*.pyc
.pytest_cache/

# Build da wiki
wiki/site/
site/

# Ansible
*.retry
*.safe
.ansible/
# vault.yml é versionado SOMENTE criptografado; cópias abertas nunca:
*.decrypted*

# Docker: .env reais (com segredos) nunca são versionados; o .env.template sim.
.env
server/docker/stacks/.env
server/docker/stacks/*/.env

# Rascunho de execução do Claude (superpowers)
.superpowers/

# Sistema operacional e editores
.DS_Store
Thumbs.db
.vscode/
.idea/

  2. Crie o modelo de variáveis das stacks Docker em docker/stacks/.env.template. Ele documenta todas as variáveis ${...} usadas pelos docker-compose.yml; os .env reais (gerados pelo Ansible ou definidos no Portainer) nunca são versionados.

docker/stacks/.env.template
# docker/stacks/.env.template
# Contrato de variáveis usadas pelos docker-compose.yml das stacks (core, apps, ai).
# Este MODELO pode ser versionado; os arquivos .env REAIS nunca são commitados.
# Em produção, os .env são gerados pelo Ansible (templates/portainer_stack_env.j2,
# playbooks setup-*-volumes.yml) ou definidos como "Environment variables" no Portainer.

# --- Comuns ---
SYSTEM_TIMEZONE=America/Sao_Paulo
BASE_DOMAIN_FROM_VAULT=
DOCKER_PUID=1000
DOCKER_PGID=1000
CORE_SERVICES_VM_IP_VAR=
VM_NFS_MOUNT_BASE_PATH=/mnt/pve_data_zfs
ZFS_DOCKER_VOLUMES_DATASET_NAME=docker-volumes

# --- Stack core (Traefik, Cloudflared, Authelia) ---
CLOUDFLARE_API_TOKEN_FROM_VAULT=
CLOUDFLARE_TUNNEL_TOKEN_FROM_VAULT=
AUTHELIA_STORAGE_POSTGRES_PASSWORD_FROM_VAULT=

# --- Stack apps: produtividade (Nextcloud) ---
PROD_STACK_NEXTCLOUD_CONFIG_PATH=
PROD_STACK_NEXTCLOUD_DATA_PATH=
PROD_STACK_NEXTCLOUD_DB_PATH=
PROD_STACK_NEXTCLOUD_HTML_PATH=
NEXTCLOUD_DB_PASSWORD_FROM_PORTAINER_ENV=
NEXTCLOUD_ADMIN_PASSWORD_FROM_PORTAINER_ENV=

# --- Stack apps: mídia (Jellyfin, Sonarr, Radarr, qBittorrent) ---
MEDIA_STACK_JELLYFIN_CONFIG_PATH=
MEDIA_STACK_SONARR_CONFIG_PATH=
MEDIA_STACK_RADARR_CONFIG_PATH=
MEDIA_STACK_QBITTORRENT_CONFIG_PATH=
MEDIA_STACK_MOVIES_PATH=
MEDIA_STACK_TVSHOWS_PATH=
MEDIA_STACK_MUSIC_PATH=
ZFS_DOWNLOADS_DATASET_NAME_NFS_PATH=

# --- Stack apps: monitoramento (Prometheus, Grafana, Loki, Promtail) ---
MONITORING_PROMETHEUS_CONFIG_PATH=
MONITORING_PROMETHEUS_DATA_PATH=
MONITORING_GRAFANA_DATA_PATH=
MONITORING_GRAFANA_DB_PATH=
MONITORING_LOKI_CONFIG_PATH=
MONITORING_LOKI_DATA_PATH=
MONITORING_PROMTAIL_CONFIG_PATH=
MONITORING_PROMTAIL_POSITIONS_PATH=
GRAFANA_DB_PASSWORD_FROM_PORTAINER_ENV=
GRAFANA_ADMIN_INITIAL_PASSWORD_FROM_PORTAINER_ENV=

# --- Stack apps: automação (n8n, Home Assistant) ---
N8N_SUBDOMAIN=n8n
N8N_CONFIG_PATH=
N8N_ADMIN_USER_FROM_PORTAINER_ENV=
N8N_ADMIN_PASSWORD_FROM_PORTAINER_ENV=
AUTO_STACK_HOMEASSISTANT_CONFIG_PATH=

# --- Stack ai (Ollama, LiteLLM, Open WebUI, OpenClaw, OpenClaude, Promtail) ---
AI_DESKTOP_VM_IP=
AI_STACK_OLLAMA_MODELS_PATH=
AI_STACK_LITELLM_CONFIG_PATH=
AI_STACK_OPENWEBUI_DATA_PATH=
AI_STACK_OPENCLAW_CONFIG_PATH=
AI_STACK_OPENCLAUDE_CONFIG_PATH=
AI_STACK_OPENCLAUDE_MEMORY_PATH=
AI_STACK_PROMTAIL_CONFIG_PATH=
AI_STACK_PROMTAIL_POSITIONS_PATH=
LITELLM_MASTER_KEY=
OPENWEBUI_SECRET_KEY=
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
GEMINI_API_KEY=

Segurança de Segredos com .gitignore

O arquivo ansible/inventories/home/group_vars/all/vault.yml conterá segredos e será criptografado. Adicioná-lo ao .gitignore é uma camada extra de precaução contra commits acidentais se você o descriptografar localmente. Arquivos .env reais com segredos (gerados nas VMs ou gerenciados pelo Portainer) NUNCA devem ser commitados.

  1. Crie um arquivo README.md inicial na raiz do projeto com uma breve descrição.
  2. Adicione todos os arquivos criados e faça o primeiro commit: 
    git add .
git commit -m "Estrutura inicial do projeto home-server e IaC"
  3. (Recomendado) Configure um repositório Git remoto (e.g., GitHub, GitLab) e envie (push) suas alterações.

0.3. Considerações de Segurança e Resiliência

Estes são os pilares que sustentam a arquitetura:

  • Segurança:
    • Princípio do Menor Privilégio: Cada componente e usuário terá apenas as permissões estritamente necessárias.
    • Atualizações Constantes: Manteremos Proxmox, VMs, imagens Docker e aplicações atualizadas.
    • Senhas Fortes e Únicas: Gerenciadas pelo Ansible Vault para a infraestrutura e um gerenciador pessoal para contas de usuário.
    • Autenticação de Dois Fatores (2FA): Implementada com Authelia para proteger o acesso aos serviços.
    • Isolamento de Rede e Firewall: Uso de redes Docker distintas e firewalls (Proxmox PVE Firewall e UFW nas VMs).
  • Resiliência:
    • Estratégia de Backup 3-2-1: Pelo menos 3 cópias dos dados, em 2 mídias diferentes, com 1 cópia off-site. Detalhado na Seção de Manutenção e Recuperação.
    • ZFS para Proteção de Dados Local: O pool /data com RAID 1 e snapshots ZFS.
    • Monitoramento: Acompanhamento da saúde do sistema para detecção proativa de problemas.
    • Infraestrutura como Código (IaC): Ansible permite reconstruir a infraestrutura de forma consistente e rápida.

Com este planejamento e estrutura inicial, você está pronto para avançar para a configuração da sua Máquina de Controle Ansible.