infra/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

⚠️ ЧИТАЙ СНАЧАЛА

Перед любой работой прочитай эти файлы:

• docs/STATUS.md — текущее состояние всех сервисов, известные проблемы
• docs/BACKLOG.md — что нужно сделать (приоритеты), что уже сделано
• docs/DECISIONS.md — почему всё устроено именно так

После завершения работы обнови соответствующий документ.

---

Правила работы

1. Только через CI/CD — никогда не фикси что-либо вручную на сервере. Внеси изменение, закоммить, запуши → CI/CD сам задеплоит. Потом проверь результат.
2. Syncthing удалён навсегда — не упоминать, не предлагать вернуть.
3. Vaultwarden удалён навсегда — не упоминать, не предлагать вернуть.
4. Tools-сервер удалён навсегда — один сервер main. Мониторинг через UptimeRobot (внешний).
5. Секреты — все в inventory/group_vars/all/vault.yml с префиксом vault_. В main.yml только алиасы "{{ vault_* }}". Никаких plaintext секретов.
6. Синтаксис-чек перед коммитом — ansible-playbook playbooks/deploy.yml --syntax-check.
7. Обновляй доки — после каждого изменения обновляй docs/STATUS.md, docs/BACKLOG.md или docs/DECISIONS.md.

---

Команды

# Prerequisites (один раз, на машине оператора)
ansible-galaxy collection install community.general community.docker ansible.posix
echo "yourpassword" > ~/.vault-password-file && chmod 600 ~/.vault-password-file

# Первичная настройка сервера (от root)
ansible-playbook playbooks/bootstrap.yml -u root

# Деплой
ansible-playbook playbooks/deploy.yml

# Редактировать секреты
ansible-vault edit inventory/group_vars/all/vault.yml

# Проверка синтаксиса (без подключения к серверу)
ansible-playbook playbooks/deploy.yml --syntax-check

# Dry run
ansible-playbook playbooks/deploy.yml --check

# Только конкретная роль
ansible-playbook playbooks/deploy.yml --tags base
ansible-playbook playbooks/deploy.yml --tags docker
ansible-playbook playbooks/deploy.yml --tags services
ansible-playbook playbooks/deploy.yml --tags backup

---

Архитектура

Серверы:

• main (87.249.49.32) — единственный сервер: Traefik, Forgejo, Plane, Docmost, n8n, CI/CD runner

Трафик: Internet → Cloudflare proxy → Traefik (80/443) → сервисы. Порты 80/443 открыты только для IP-адресов Cloudflare (UFW whitelist).

Секреты: inventory/group_vars/all/vault.yml (Ansible Vault AES-256). Пароль vault: ~/.vault-password-file (в .gitignore, никогда не коммитить).

TLS: Wildcard сертификат *.walava.io через Cloudflare DNS-01 (Traefik certresolver).

Роли:

• base — UFW, fail2ban, sshd, deploy user
• docker — Docker CE + Compose plugin
• services — основной стек (templates → /opt/services/, docker compose up)
• backup — backup каждые 6 часов → S3 (walava-backup/), только для main-сервера

Шаблоны → файлы на сервере:

• roles/services/templates/docker-compose.yml.j2 → /opt/services/docker-compose.yml
• roles/services/templates/env.j2 → /opt/services/.env (mode 0600)
• roles/services/templates/traefik/traefik.yml.j2 → /opt/services/traefik/traefik.yml
• roles/services/templates/traefik/dynamic/routes.yml.j2 → /opt/services/traefik/dynamic/routes.yml

Добавление нового сервиса:

1. Добавить контейнер в docker-compose.yml.j2 в сеть backend
2. Добавить роутер в routes.yml.j2 (НЕ docker labels — используется file provider)
3. Добавить домен в inventory/group_vars/all/main.yml
4. Добавить DNS A-запись в Cloudflare (через API или вручную)

---

CI/CD

Push в master → Forgejo Actions запускает:

ansible-playbook playbooks/deploy.yml

Workflow: .forgejo/workflows/deploy.yml

---

Домены (все на walava.io)

Сервис	Домен
Forgejo	git.walava.io
Plane	hub.walava.io
Docmost	wiki.walava.io
n8n	auto.walava.io
Traefik dashboard	traefik.walava.io
Landing	walava.io