Первый commit

2026-01-08 12:32:22 +03:00
commit 08225bd3fd
8 changed files with 1432 additions and 0 deletions
@@ -0,0 +1,49 @@
+# Repository Guidelines
+
+This repo is a small Docker Compose environment for learning Apache NiFi with NiFi Registry, Postgres, Kafka, and Kafka UI.
+
+## Project Structure & Module Organization
+
+- `docker-compose.yml`: single entrypoint defining all services and ports.
+- `drivers/`: JDBC drivers mounted into the NiFi container (e.g. `drivers/postgresql-42.7.4.jar`).
+- `nifi-templates/`: NiFi templates/flows and helper SQL (`*.json`, `*.xml`, `*.sql`) mounted into Postgres at `/nifi-templates`.
+- `README.md`: usage notes, URLs, and connection strings.
+- (local) `shared-folder/`: host folder mounted to `/opt/nifi/nifi-current/ls-target` for file-based demos.
+
+## Build, Test, and Development Commands
+
+- `docker compose up`: start the full stack.
+- `docker compose stop`: stop containers without removing volumes.
+- `docker compose start`: start previously stopped containers (preserves all state).
+- `docker compose down`: remove containers and networks.
+- `docker compose down -v`: remove containers, networks, and all named volumes (destructive clean reset).
+- `docker compose logs -f nifi`: follow NiFi logs while debugging processors.
+- `docker compose exec postgres bash -c "export PGPASSWORD=postgres; psql -U postgres -d app"`: open `psql` in the Postgres container.
+
+Notes on state persistence:
+- `postgres`, `nifi`, and `registry` persist state via named volumes in `docker-compose.yml` (survive `docker compose down`, wiped by `docker compose down -v`).
+- Kafka message/topic persistence is disabled by default (see the commented `kafka-data` volume in `docker-compose.yml`).
+
+## Coding Style & Naming Conventions
+
+- YAML: 2-space indentation; keep service names stable (`nifi`, `registry`, `postgres`, `kafka`, `kafka-ui`) to avoid breaking docs.
+- Templates: name files by purpose and target, e.g. `SampleKafka2Postgres.json` and matching `SampleKafka2Postgres.sql`.
+- Docs: keep `README.md` examples runnable and aligned with `docker-compose.yml` ports/URLs.
+
+## Testing Guidelines
+
+No automated tests are currently included. Validate changes by:
+- running `docker compose up` and checking UIs load (NiFi `http://localhost:18443/nifi/`, Registry `http://localhost:18080/nifi-registry`, Kafka UI `http://localhost:8082/`);
+- importing/updating a template from `nifi-templates/` and performing a small end-to-end smoke run.
+If you need a clean slate for validation, use `docker compose down -v` (this wipes Postgres/NiFi/Registry state).
+
+## Commit & Pull Request Guidelines
+
+- Commit messages in history are short, descriptive, and written in Russian (e.g. “Доработки документации”, “Добавлены Postgres, Kafka…”). Follow the same style.
+- PRs: include a short description, the motivation (issue link if applicable), and note any port/credential changes. Add screenshots for UI-facing doc updates when helpful.
+
+## Security & Configuration Tips
+
+This is for local learning, not production. Defaults include:
+- NiFi single-user creds in `docker-compose.yml` (`admin` / `Password123456`);
+- Postgres creds (`postgres` / `postgres`) and published port `5437`.
@@ -0,0 +1,147 @@
+# nifi-docker
+
+Учебный стенд для знакомства с Apache NiFi и Kafka: NiFi + NiFi Registry + Postgres + Kafka + Kafka UI.
+
+## Быстрый старт
+```sh
+docker compose up -d
+docker compose ps
+```
+
+Остановить стенд:
+```sh
+docker compose stop
+```
+
+Запустить обратно (после `stop` состояние сохраняется):
+```sh
+docker compose start
+```
+
+Удалить контейнеры и сеть:
+```sh
+docker compose down
+```
+Затем поднять обратно (с сохранённым состоянием в томах):
+```sh
+docker compose up -d
+```
+
+Удалить ещё и тома (volumes) — полный сброс (деструктивно):
+```sh
+docker compose down -v
+```
+
+### Что сохраняется между перезапусками
+- `docker compose stop/start` — сохраняется всё (контейнеры не удаляются).
+- `docker compose down` — контейнеры удаляются, но тома (volumes) остаются: сохраняются NiFi (`conf`/`state`), NiFi Registry, Postgres.
+- `docker compose down -v` — полный сброс: удаляются и контейнеры, и тома (volumes).
+
+Примечание: в этой конфигурации Kafka-сообщения/топики не сохраняются между `docker compose down` → `up` (чтобы не копить дисковое пространство). Между `stop` → `start` Kafka сохраняется. Пример подключения тома (volume) для Kafka есть в `docker-compose.yml`.
+
+## Адреса и доступы
+- NiFi: http://localhost:18443/nifi/ (логин `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/
+- Kafka UI: http://localhost:8082/
+- Kafka UI docs: https://docs.kafka-ui.provectus.io/
+
+## Важно про адреса (внутри Docker и с хоста)
+Если вы настраиваете подключение *в NiFi*, то `localhost` почти всегда будет неправильным (NiFi живёт в контейнере).
+
+Используйте имена сервисов из `docker-compose.yml`:
+- Postgres (из NiFi): `jdbc:postgresql://postgres:5432/app`
+- Kafka (из NiFi): `kafka:29092`
+- Registry (из NiFi): `http://registry:18080`
+
+А с локальной машины:
+- Postgres: `jdbc:postgresql://localhost:5437/app`
+- Kafka: `localhost:9092`
+
+## PostgreSQL
+JDBC-драйвер для Postgres лежит в `drivers/` и монтируется в контейнер NiFi как `/opt/nifi/nifi-current/drivers/`.
+
+Параметры для DBCP в NiFi:
+- Database Connection URL: `jdbc:postgresql://postgres:5432/app`
+- Database Driver Class Name: `org.postgresql.Driver`
+- Database Driver Location(s): `/opt/nifi/nifi-current/drivers/postgresql-42.7.4.jar`
+- Database User: `postgres`
+- Password: `postgres`
+
+### Подключение через DBeaver (удобнее всего)
+Postgres проброшен наружу на порт `5437`, поэтому в DBeaver создайте подключение со следующими параметрами:
+- Host: `localhost`
+- Port: `5437`
+- Database: `app`
+- Username: `postgres`
+- Password: `postgres`
+
+Если DBeaver предложит скачать драйвер — соглашайтесь скачать/установить драйвер PostgreSQL.
+
+Инициализация демо-схем/таблиц:
+```sh
+docker compose exec -T postgres psql -U postgres -d app -f /nifi-templates/SampleKafka2Postgres.sql
+```
+Запускайте это после первого старта или после `docker compose down -v` (скрипт не идемпотентный: при повторном запуске будут ошибки про существующие схемы/таблицы).
+
+### Через консоль (если нужно)
+Просмотр данных:
+```sh
+docker compose exec -it postgres bash -c "export PGPASSWORD=postgres; psql -U postgres -d app"
+select * from ods.samplekafka2postgres order by id desc limit 10;
+```
+
+## Kafka
+- С локальной машины (например, для консольных утилит): `localhost:9092`
+- Из NiFi (внутри Docker): `kafka:29092`
+
+## Примеры flow (шаблоны)
+В `nifi-templates/` лежат примеры:
+- `Sample2Kafka.xml` / `Sample2Kafka.json` — публикует сообщения в Kafka topic `Sample2Kafka`
+- `SampleKafka2Postgres.json` — читает из Kafka topic `Sample2Kafka` и пишет в Postgres (в `stg.samplekafka2postgres`, затем вызывает `ods.load_samplekafka2postgres()`)
+
+### Памятка: как импортировать Process Group / Flow в NiFi
+Файлы нужно загружать через браузер с вашей машины (каталог `nifi-templates/`).
+
+**Вариант 1: шаблон `.xml` (Template)**
+1) Откройте NiFi: http://localhost:18443/nifi/
+2) В верхнем меню найдите `Templates` → `Upload Template` → выберите файл `nifi-templates/Sample2Kafka.xml`.
+3) На канвасе: нажмите правой кнопкой мыши → `Instantiate Template` (или иконка Template на панели) → выберите шаблон → разместите process group на канвасе.
+
+**Вариант 2: flow definition `.json`**
+Название пункта может отличаться в зависимости от UI/версии, но смысл один — “загрузить process group/flow definition из файла”:
+1) В верхнем меню найдите действие вроде `Upload` / `Import` / `Process Group` → выберите загрузку из файла.
+2) Выберите `nifi-templates/SampleKafka2Postgres.json` (или `Sample2Kafka.json`) и разместите process group на канвасе.
+
+После импорта, как правило, нужно:
+- перейти внутрь process group;
+- включить Controller Services (Configure → `Controller Services` → Enable, или “enable all controller services”);
+- затем запустить процессоры.
+
+Рекомендуемый минимальный сценарий:
+1) topic `Sample2Kafka` вручную создавать обычно не требуется: он создаётся автоматически при первой попытке записи (если в Kafka включено автосоздание топиков; по умолчанию оно включено). Если по какой-то причине topic не появился — создайте его в Kafka UI.
+2) Импортируйте flow в NiFi (в зависимости от UI: import/upload template для `.xml` или import flow definition для `.json`). Если вы импортировали раньше, то после `docker compose down` flow сохранится.
+3) Внутри flow включите Controller Services, затем запустите процессоры.
+
+Kafka UI уже настроен в `docker-compose.yml`:
+- Cluster name: `Kafka Cluster`
+- Bootstrap Servers: `kafka:29092`
+
+## Shared folder (общая папка)
+Каталог `shared-folder/` на хосте смонтирован в контейнер NiFi как `/opt/nifi/nifi-current/ls-target` (удобно для ListFile/GetFile).
+Если после запуска контейнеров возникают проблемы с правами: `sudo chown -R $USER shared-folder`.
+
+## Полезные команды
+```sh
+docker compose logs -f nifi
+docker compose logs -f kafka
+docker compose exec postgres bash
+```
+
+Для доступа из NiFi к сервисам на локальной машине используйте `host.docker.internal` вместо `localhost`.
+
+## Если что-то не работает
+- NiFi может запускаться 1–3 минуты; смотрите `docker compose logs -f nifi`.
+- Если процессор в NiFi не подключается к Kafka/Postgres, проверьте, что используете адреса “из NiFi” (см. раздел про Docker).
+- Если порты заняты, измените проброс портов в `docker-compose.yml`.
@@ -0,0 +1,96 @@
+services:
+
+  nifi:
+    image: apache/nifi:1.27.0
+    ports:
+      - 18443:8443 # Unsecured HTTP Web Port
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    environment:
+      - SINGLE_USER_CREDENTIALS_USERNAME=admin
+      - SINGLE_USER_CREDENTIALS_PASSWORD=Password123456
+      - NIFI_WEB_HTTP_PORT=8443
+    volumes:
+      - ./drivers:/opt/nifi/nifi-current/drivers
+      - ./shared-folder:/opt/nifi/nifi-current/ls-target
+      - nifi-conf:/opt/nifi/nifi-current/conf
+      - nifi-state:/opt/nifi/nifi-current/state
+      # Если хочешь сохранять очереди/контент/провенанс (обычно для обучения не нужно) — раскомментируй:
+      # - nifi-flowfile-repo:/opt/nifi/nifi-current/flowfile_repository
+      # - nifi-content-repo:/opt/nifi/nifi-current/content_repository
+      # - nifi-provenance-repo:/opt/nifi/nifi-current/provenance_repository
+      # - nifi-database-repo:/opt/nifi/nifi-current/database_repository
+
+  registry:
+    image: apache/nifi-registry:1.27.0
+    ports:
+      - 18080:18080
+    environment:
+      - NIFI_REGISTRY_WEB_HTTP_PORT=18080
+    volumes:
+      - registry-db:/opt/nifi-registry/nifi-registry-current/database
+      - registry-flow-storage:/opt/nifi-registry/nifi-registry-current/flow_storage
+      
+  postgres:
+    image: postgres:16.4
+    # restart: always
+    ports:
+      - 5437:5432
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: app
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+      - ./nifi-templates:/nifi-templates
+    
+  kafka:
+    image: apache/kafka:3.8.0
+    hostname: kafka
+    container_name: kafka
+    ports:
+      - 9092:9092
+    # Если хочешь сохранять топики/сообщения между `docker compose down/up` — раскомментируй:
+    # volumes:
+    #   - kafka-data:/tmp/kraft-combined-logs
+    environment:
+      KAFKA_BROKER_ID: 1
+      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT,CONTROLLER:PLAINTEXT
+      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:29092,PLAINTEXT_HOST://localhost:9092
+      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
+      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
+      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
+      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
+      KAFKA_PROCESS_ROLES: broker,controller
+      KAFKA_NODE_ID: 1
+      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:29093
+      KAFKA_LISTENERS: PLAINTEXT://kafka:29092,CONTROLLER://kafka:29093,PLAINTEXT_HOST://0.0.0.0:9092
+      KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT
+      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
+      KAFKA_LOG_DIRS: /tmp/kraft-combined-logs
+      CLUSTER_ID: MkU3OEVBNTcwNTJENDM2Qk
+
+  kafka-ui:
+    container_name: kafka-ui
+    image: provectuslabs/kafka-ui:v0.7.2
+    ports:
+      - 8082:8080
+    depends_on:
+      - kafka
+    environment:
+      DYNAMIC_CONFIG_ENABLED: "true"
+      KAFKA_CLUSTERS_0_NAME: "Kafka Cluster"
+      KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: "kafka:29092"
+      KAFKA_CLUSTERS_0_PROPERTIES_SECURITY_PROTOCOL: "PLAINTEXT"
+
+volumes:
+  pgdata:
+  nifi-conf:
+  nifi-state:
+  registry-db:
+  registry-flow-storage:
+  # nifi-flowfile-repo:
+  # nifi-content-repo:
+  # nifi-provenance-repo:
+  # nifi-database-repo:
+  # kafka-data:
@@ -0,0 +1,42 @@
+create schema stg;
+
+CREATE TABLE stg.samplekafka2postgres (
+	dttm timestamptz NULL,
+	txt text NULL
+);
+
+
+create schema ods;
+
+CREATE TABLE ods.samplekafka2postgres (
+	id serial4 NOT NULL,
+	ins_dttm timestamptz default now() NOT NULL,
+	dttm timestamptz NULL,
+	txt text NULL,
+	CONSTRAINT samplekafka2postgres_pkey PRIMARY KEY (id)
+);
+
+create or replace procedure ods.load_samplekafka2postgres()
+language plpgsql 
+as $$
+begin 
+	-- перенос содержимого таблицы в ods полностью
+	insert into ods.samplekafka2postgres(dttm, txt)
+	select dttm, txt
+	from stg.samplekafka2postgres;
+
+	-- удаление делаем в процессе NiFi
+	-- delete from stg.samplekafka2postgres;
+
+	commit;
+end; $$;
+
+-- Примеры запросов
+select * from ods.samplekafka2postgres;
+
+delete from stg.samplekafka2postgres;
+delete from ods.samplekafka2postgres where ins_dttm < now() - interval '10 minute'; 
+
+select * from stg.samplekafka2postgres;
+select * from ods.samplekafka2postgres order by id desc;
+select count(*) from ods.samplekafka2postgres;