# n8n Docker Stack

Self-hosted n8n с PostgreSQL, Redis, Task Runners, Prometheus и Grafana — готовый production-стек с минимальными усилиями на настройку

## Зачем

- **Изоляция** — отключена телеметрия, шаблоны и внешние запросы к n8n.io
- **Производительность** — queue mode с workers, внешний task runner для JS и Python
- **Надёжность** — PostgreSQL вместо SQLite, Redis как брокер очередей
- **Наблюдаемость** — Prometheus + Grafana с готовым дашбордом
- **Воспроизводимость** — автоимпорт workflows и credentials при каждом старте
- **Контроль версий** — встроенные workflows для экспорта и коммита в git

---

## Сервисы

| Сервис | Порт | Описание |
|---|---|---|
| n8n | 5678 | Основной сервер |
| n8n-worker-1 | — | Worker для queue mode |
| n8n-runner-1 | — | Внешний раннер JS + Python |
| postgres | 5433 | База данных |
| redis (Valkey) | — | Очередь Bull |
| prometheus | 9090 | Сбор метрик |
| grafana | 3000 | Дашборды |
| fix-permissions | — | Однократная правка прав (uid 1000) |
| n8n-import | — | Автоимпорт workflows и credentials при старте |

---

## Быстрый старт

```bash
cp .env.example .env
# Заполнить .env

docker compose up -d
```

Стек запускается без `.env` — все переменные имеют дефолты в `docker-compose.yml`.

---

## Деплой через Portainer

Portainer позволяет управлять стеком через UI без прямого доступа к серверу.

**Важно:** деплой через «URL» (одиночная ссылка на compose-файл) не работает — Portainer не скачивает вспомогательные файлы (`prometheus.yml`, `grafana/` и т.д.). Использовать только **Repository**.

### Требования

Portainer должен быть запущен так, чтобы **путь к данным на хосте и внутри контейнера совпадал**. Иначе Docker Engine не найдёт файлы клонированного репозитория — Portainer передаёт ему свои внутренние пути, а Docker ищет их на хосте.

```bash
docker stop portainer && docker rm portainer

PORTAINER_DATA="$HOME/portainer/data"
mkdir -p "$PORTAINER_DATA"

docker run -d \
  -p 9443:9443 \
  --name portainer \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$PORTAINER_DATA":"$PORTAINER_DATA" \
  portainer/portainer-ce:latest \
  --data "$PORTAINER_DATA"
```

Флаг `--data` указывает Portainer хранить данные по тому же пути, что смонтирован с хоста — пути совпадают, Docker Engine находит файлы.

### Шаги

1. **Stacks → Add stack → Repository**
2. Repository URL: адрес репозитория
3. Compose path: `docker-compose.yml`
4. Добавить переменные окружения или указать путь к `.env`
Важно правильно настроить WEBHOOK_URL
```
# URL для вебхуков (адрес, по которому n8n доступен снаружи)
WEBHOOK_URL=http://YOUR_SERVER_IP:5678
```
⚠️ Важно: Если указан неверный адрес, то Form Data и вебхуки не будут работать

5. Deploy the stack

> (Опционально) Дать права
```sh
sudo chmod 777 /home/bbr/portainer/data/compose
```

### Документация

- [Установка Docker Compose](https://docs.n8n.io/hosting/installation/server-setups/docker-compose/)
- [Stacks in Portainer](https://docs.portainer.io/user/docker/stacks/add)
- [Git repository deployment](https://docs.portainer.io/user/docker/stacks/add#option-3-git-repository)

---

## Встроенные workflows

В `n8n/backup/workflows/` лежат служебные workflow, которые импортируются автоматически при каждом старте.

| Файл | Назначение |
|---|---|
| `Backup_Workflows.json` | Экспорт всех workflow в `n8n/shared/` |
| `Backup_Сredentials.json` | Экспорт всех credentials в `n8n/shared/` |
| `Git_Commit_Workflows.json` | Коммит экспортированных файлов в git |
| `Git_Pull_Workflows.json` | Pull изменений из git-репозитория |

### Настройка credentials

Встроенные workflows обращаются к API локального n8n. Для работы необходимо:

1. Сгенерировать API ключ: n8n → **Settings → API → Create an API key**
2. Создать credentials типа **n8n API**:
   - **URL**: `http://n8n:5678/api/v1`
   - **API Key**: ключ из шага 1
3. Сохранить credentials в файл `n8n/backup/credentials/n8n_local.json`

### Защита credentials от перезаписи

n8n CLI не имеет встроенного `--skipExisting` для импорта credentials. Скрипт реализует это через маркер-файлы в `n8n_storage` volume (`/home/node/.n8n/imported/`).

| Тип | Поведение при повторном деплое |
|---|---|
| Credentials | Импортируются **один раз**, затем пропускаются |
| Workflows | Перезаписываются **всегда** |

Принудительный переимпорт — задать `FORCE_IMPORT=true` в env сервиса `n8n-import`.

Для добавления своих workflow при старте — положить JSON в `n8n/backup/workflows/` или `n8n/backup/credentials/`.

### Документация

- [n8n Public API / Authentication](https://docs.n8n.io/api/authentication/)
- [n8n CLI commands](https://docs.n8n.io/hosting/cli-commands/)
- [Автоимпорт workflows](https://docs.n8n.io/hosting/cli-commands/#import-workflows-and-credentials)

---

## Политика хранения данных

| Что | Лимит |
|---|---|
| Данные выполнений | 7 дней / 5 000 записей |
| История версий workflow | 30 дней |
| Логи n8n (файлы) | 10 файлов × 20 MB = ~200 MB |
| Логи Docker (все сервисы) | 3–5 файлов × 5–10 MB на сервис |
| Prometheus TSDB | 15 дней / 1 GB |
| Redis | 256 MB max (LRU) |

Бинарные данные в `n8n/shared/` автоматически не очищаются — при активном использовании нод Read/Write Files настроить очистку по расписанию.

### Документация

- [Execution data — pruning и retention](https://docs.n8n.io/hosting/scaling/execution-data/)
- [Executions environment variables](https://docs.n8n.io/hosting/configuration/environment-variables/executions/)
- [Workflow history](https://docs.n8n.io/workflows/history/)
- [Логирование](https://docs.n8n.io/hosting/logging-monitoring/logging/)
- [Environment Variables (все)](https://docs.n8n.io/hosting/configuration/environment-variables/)
- [Task Runners](https://docs.n8n.io/hosting/configuration/task-runners/)
- [Queue mode](https://docs.n8n.io/hosting/scaling/queue-mode/)
- [Мониторинг n8n](https://docs.n8n.io/hosting/logging-monitoring/monitoring/)
- [Prometheus](https://docs.n8n.io/hosting/configuration/configuration-examples/prometheus/)
- [Аудит безопасности](https://docs.n8n.io/hosting/securing/security-audit/)