Еще работа над документаций

README.md

@@ -1,11 +1,17 @@
-> **Последнее обновление:** 2026-01-08 | **Версия NiFi:** 1.x.x
+> **Последнее обновление:** 2026-01-08 | **Версии:** NiFi 1.27.0 / Kafka 3.8.0 / Postgres 16.4
 
 Учебный стенд для знакомства с Apache NiFi и Kafka: NiFi + NiFi Registry + Postgres + Kafka + Kafka UI.
 
 ## Содержание
 
+<details>
+<summary>Показать/скрыть</summary>
+
 - [Содержание](#содержание)
+- [Требования](#требования)
 - [Быстрый старт](#быстрый-старт)
+  - [Сценарий первого запуска (5-10 минут)](#сценарий-первого-запуска-5-10-минут)
+  - [Команды управления](#команды-управления)
   - [Что сохраняется между перезапусками](#что-сохраняется-между-перезапусками)
 - [Адреса и доступы](#адреса-и-доступы)
 - [Важно про адреса (внутри Docker и с хоста)](#важно-про-адреса-внутри-docker-и-с-хоста)
@@ -30,7 +36,47 @@
   - [Проблемы с правами доступа](#проблемы-с-правами-доступа)
   - [Дополнительная диагностика](#дополнительная-диагностика)
 
+</details>
+
+## Требования
+- Docker Engine / Docker Desktop с поддержкой `docker compose` (Compose v2).
+- Свободные порты на машине: `18443`, `18080`, `5437`, `9092`, `8082`.
+- Ресурсы (примерно): 2 CPU, 6–8 GB RAM.
+
 ## Быстрый старт
+Если вы запускаете стенд впервые — пройдите сценарий ниже. Если нужно просто запустить/остановить/сбросить — используйте шпаргалку в “Команды управления”.
+
+Все команды `docker compose ...` запускайте в терминале ОС на хосте из корня репозитория (рядом с `docker-compose.yml`).
+
+### Сценарий первого запуска (5-10 минут)
+
+1) Поднимите стенд:
+   ```sh
+   docker compose up -d
+   docker compose ps
+   ```
+2) Дождитесь запуска NiFi (может занять 1–3 минуты), затем откройте:
+   - NiFi: http://localhost:18443/nifi/
+   - Kafka UI: http://localhost:8082/
+3) Инициализируйте демо-схемы/таблицы в Postgres (требуется один раз после первого старта или после `docker compose down -v`):
+   ```sh
+   docker compose exec -T postgres psql -U postgres -d app -f /nifi-templates/SampleKafka2Postgres.sql
+   ```
+4) Импортируйте flow в NiFi из файлов:
+   - `nifi-templates/Sample2Kafka.json`
+   - `nifi-templates/SampleKafka2Postgres.json`
+   Подробный гайд: `MENTEE_GUIDE_JSON_FLOWS.md`.
+5) Внутри каждого process group:
+   - включите Controller Services;
+   - запустите процессоры.
+6) Проверьте результат:
+   - в Kafka UI в topic `Sample2Kafka` появляются сообщения;
+   - в Postgres растёт число строк:
+     ```sh
+     docker compose exec -it postgres bash -c "export PGPASSWORD=postgres; psql -U postgres -d app -c 'SELECT COUNT(*) FROM ods.samplekafka2postgres;'"
+     ```
+
+### Команды управления
 ```sh
 docker compose up -d
 docker compose ps
@@ -59,6 +105,7 @@ docker compose up -d
 ```sh
 docker compose down -v
 ```
+После `docker compose down -v` потребуется заново выполнить SQL-инициализацию и импортировать flow (см. сценарий выше).
 
 ### Что сохраняется между перезапусками
 - `docker compose stop/start` — сохраняется всё (контейнеры не удаляются).
@@ -69,7 +116,7 @@ docker compose down -v
 
 ## Адреса и доступы
 - NiFi: http://localhost:18443/nifi/
-  > 💡 **Примечание:** В текущей конфигурации аутентификация отключена для упрощения обучения. Логин и пароль не требуются.
+  > 💡 **Примечание:** В текущей конфигурации NiFi доступен по HTTP, логин не требуется. Если вы включите HTTPS/аутентификацию, креды заданы в `docker-compose.yml` (`admin` / `Password123456`).
 - NiFi docs: https://nifi.apache.org/documentation/
 - Registry: http://localhost:18080/nifi-registry
 - Registry docs: https://nifi.apache.org/docs/nifi-registry-docs/
@@ -80,6 +127,8 @@ docker compose down -v
 
 > ⚠️ **Критически важно:** Если вы настраиваете подключение *в NiFi*, то `localhost` почти всегда будет неправильным (NiFi живёт в контейнере).
 
+Почему так: внутри контейнера `localhost` — это сам контейнер. Контейнеры из одного `docker compose` видят друг друга по именам сервисов (Docker DNS), поэтому `postgres`, `kafka`, `registry` работают как “хосты”.
+
 Используйте имена сервисов из `docker-compose.yml`:
 - Postgres (из NiFi): `jdbc:postgresql://postgres:5432/app`
 - Kafka (из NiFi): `kafka:29092`
@@ -139,10 +188,12 @@ select * from ods.samplekafka2postgres order by id desc limit 10;
 
 > ⚠️ **Важно:** В Apache Kafka 3.8.0 скрипты находятся в `/opt/kafka/bin/`, поэтому нужно указывать полный путь.
 
+Команды ниже выполняются внутри контейнера Kafka (через `docker compose exec ...`). Если вы запускаете Kafka CLI на хосте — используйте `--bootstrap-server localhost:9092`.
+
 **Чтение сообщений:**
 ```sh
 docker compose exec kafka /opt/kafka/bin/kafka-console-consumer.sh \
-  --bootstrap-server localhost:9092 \
+  --bootstrap-server kafka:29092 \
   --topic Sample2Kafka \
   --from-beginning
 ```
@@ -152,7 +203,7 @@ docker compose exec kafka /opt/kafka/bin/kafka-console-consumer.sh \
 **Интерактивный режим** (ввод сообщений вручную):
 ```sh
 docker compose exec kafka /opt/kafka/bin/kafka-console-producer.sh \
-  --bootstrap-server localhost:9092 \
+  --bootstrap-server kafka:29092 \
   --topic Sample2Kafka
 ```
 После запуска введите сообщение и нажмите Enter. Нажмите `Ctrl+C` для выхода.
@@ -161,7 +212,7 @@ docker compose exec kafka /opt/kafka/bin/kafka-console-producer.sh \
 ```sh
 echo '{"dttm": 1704698992000, "txt": "Тестовое сообщение"}' | \
   docker compose exec -T kafka /opt/kafka/bin/kafka-console-producer.sh \
-  --bootstrap-server localhost:9092 \
+  --bootstrap-server kafka:29092 \
   --topic Sample2Kafka
 ```
 > 💡 **Примечание:** Флаг `-T` отключает TTY, что позволяет использовать pipe.
@@ -169,7 +220,7 @@ echo '{"dttm": 1704698992000, "txt": "Тестовое сообщение"}' | \
 **Просмотр списка топиков:**
 ```sh
 docker compose exec kafka /opt/kafka/bin/kafka-topics.sh \
-  --bootstrap-server localhost:9092 \
+  --bootstrap-server kafka:29092 \
   --list
 ```
 
@@ -311,3 +362,4 @@ docker compose exec postgres bash
 2. Перезапустите проблемный контейнер: `docker compose restart nifi` (или другой сервис)
 3. Попробуйте полный сброс: `docker compose down -v && docker compose up -d`
    > ⚠️ **Внимание:** Это удалит все данные из Postgres, NiFi и Registry.
+   После этого потребуется заново выполнить `/nifi-templates/SampleKafka2Postgres.sql` и импортировать flow.