# 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. **Секреты** — все в `inventory/group_vars/all/vault.yml` с префиксом `vault_`. В `main.yml` только алиасы `"{{ vault_* }}"`. Никаких plaintext секретов.
4. **Синтаксис-чек перед коммитом** — `ansible-playbook playbooks/deploy.yml --syntax-check`.
5. **Обновляй доки** — после каждого изменения обновляй `docs/STATUS.md`, `docs/BACKLOG.md` или `docs/DECISIONS.md`.

---

## Команды

```bash
# 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

# Деплой tools-сервера
ansible-playbook playbooks/tools.yml

# Деплой всего сразу
ansible-playbook playbooks/site.yml

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

# Проверка синтаксиса (без подключения к серверу)
ansible-playbook playbooks/deploy.yml --syntax-check
ansible-playbook playbooks/tools.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, Vaultwarden, Мониторинг, CI/CD runner
- `tools` (85.193.83.9) — Outline wiki, n8n, docker-mailserver, SnappyMail

**Трафик:** 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 сертификат `*.csrx.ru` через Cloudflare DNS-01 (Traefik certresolver).

**Роли:**
- `base` — UFW, fail2ban, sshd, deploy user
- `docker` — Docker CE + Compose plugin
- `services` — основной стек (templates → `/opt/services/`, docker compose up)
- `tools` — tools-стек (templates → `/opt/tools/`, docker compose up)
- `backup` — backup каждые 6 часов → S3 (`visual-backup/data/`), только для 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`

**Добавление нового сервиса на main:**
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

**Добавление сервиса на tools:**
1. Добавить контейнер в `roles/tools/templates/docker-compose.yml.j2`
2. Добавить роутер в `routes.yml.j2` с `url: "http://{{ ip_tools }}:PORT"`
3. Открыть порт в UFW (задача в `roles/tools/tasks/main.yml`)

---

## CI/CD

Push в `master` → Forgejo Actions запускает:
```
ansible-playbook playbooks/deploy.yml
ansible-playbook playbooks/tools.yml
```
Workflow: `.forgejo/workflows/deploy.yml`