n8n: инсталация с Docker и първият ти workflow

01Какво ще научиш

• Как да вдигнеш n8n с Docker Compose и Postgres и да пазиш тайните в .env.
• Как изглежда интерфейсът: платно, нодове, изпълнения (executions).
• Разликата между тригер (започва процеса) и действие (върши работа).
• Как да свържеш нодове и да предаваш данни между тях с израз (expression).
• Как да изпълняваш и тестваш стъпка по стъпка и как да закачиш (pin) данни.
• Какво е „Publish“ и кога ти трябва.
• Как да четеш историята на изпълненията, когато нещо се счупи.

02Преди да започнеш

• Docker с Compose v2 🔒 локално. Провери с docker compose version. На Windows: Docker Desktop с WSL2 — виж Обучение 3 от серията DevStation.
• Папката на проекта да е вътре във файловата система на Linux/WSL (например ~/n8n-lab), не под /mnt/c/… — през границата папките са бавни и дават грешки с права (така пише документацията на n8n).
• Документацията на n8n за пълния стек иска около 4 GB RAM и 2 процесора; нашият стек е по-малък, но с толкова си на сигурно.
• Интернет за първото теглене на образите и за примерното API.
• Мениджър на пароли — ще пазиш в него ключа за криптиране.

03Стъпки

1. Какво ще построим

   Два контейнера в един проект: n8n (редакторът и двигателят) и Postgres (там n8n пази работните процеси, достъпите и историята). После — работен процес от пет нода. Защо контейнери? Защото всяка програма идва с всичко нужно, не пречи на другите и се маха с една команда.

   Нод	Вид	Какво прави
   Manual Trigger	тригер	Стартира процеса, когато натиснеш „Execute Workflow“
   HTTP Request	действие	Взема курсовете от публично API
   Edit Fields	данни	Подрежда един ред за журнала
   Convert to File	данни	Превръща текста във файл (двоични данни)
   Read/Write Files from Disk	действие	Дописва реда към файл

2. Папка и файл с тайните

   Тайните (парола на базата, ключ за криптиране) не се пишат в compose файла. Държим ги в .env — Compose го чете сам. Генерираме ги на място, за да няма две инсталации с една и съща „тайна“.

   bash · ~/n8n-lab/.envкопирай

   mkdir -p ~/n8n-lab && cd ~/n8n-lab
   
   cat > .env <<EOF
   N8N_VERSION=2.41.4
   POSTGRES_USER=n8n
   POSTGRES_PASSWORD=$(openssl rand -hex 24)
   POSTGRES_DB=n8n
   N8N_ENCRYPTION_KEY=$(openssl rand -hex 32)
   TZ=Europe/Sofia
   EOF
   
   chmod 600 .env

   ✅

   Запази ключа извън стека

   N8N_ENCRYPTION_KEY шифрова всички достъпи, които ще запишеш в n8n. Ако го загубиш, след възстановяване от копие достъпите не могат да се разшифроват. Препиши го в мениджъра на пароли (cat .env го показва). Числото 2.41.4 е текущата стабилна версия към 01.10.2026 — виж „Обновяване“ по-долу.

3. Файлът compose.yaml

   Един файл описва целия стек. Правилата в него: версията е закачена (не latest), данните са в именувани томове, редакторът е достъпен само от твоята машина (127.0.0.1), а n8n чака Postgres да е „здрав“, преди да стартира.

   yaml · ~/n8n-lab/compose.yamlкопирай

   name: n8n-lab
   
   services:
     postgres:
       image: postgres:18
       restart: unless-stopped
       environment:
         POSTGRES_USER: ${POSTGRES_USER}
         POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
         POSTGRES_DB: ${POSTGRES_DB}
         PGDATA: /var/lib/postgresql/data
       volumes:
         - db_data:/var/lib/postgresql/data
       healthcheck:
         test: ["CMD-SHELL", "pg_isready -h localhost -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
         interval: 5s
         timeout: 5s
         retries: 10
   
     n8n:
       image: docker.n8n.io/n8nio/n8n:${N8N_VERSION}
       restart: unless-stopped
       depends_on:
         postgres:
           condition: service_healthy
       environment:
         TZ: ${TZ}
         GENERIC_TIMEZONE: ${TZ}
         DB_TYPE: postgresdb
         DB_POSTGRESDB_HOST: postgres
         DB_POSTGRESDB_PORT: "5432"
         DB_POSTGRESDB_DATABASE: ${POSTGRES_DB}
         DB_POSTGRESDB_USER: ${POSTGRES_USER}
         DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD}
         N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}
         N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS: "true"
       ports:
         - "127.0.0.1:5678:5678"
       volumes:
         - n8n_data:/home/node/.n8n
   
   volumes:
     db_data:
     n8n_data:

   💡

   Защо точно така

   PGDATA — Postgres 18 смени мястото на данните по подразбиране; без този ред базата се връща празна. 127.0.0.1 — портът не се вижда от другите в мрежата ти; Postgres изобщо няма публикуван порт, n8n го намира по името postgres. TZ и GENERIC_TIMEZONE — по подразбиране n8n работи във времева зона America/New_York; без тях часовете в изразите и графиците ще са американски.

   Провери, че файлът е четим (Compose замества променливите и показва резултата — тайните също, затова не го пращай никому):

   bashкопирай

   docker compose config --quiet && echo "compose: OK"

4. Стартирай и провери

   bashкопирай

   cd ~/n8n-lab
   docker compose up -d
   docker compose ps

   Първия път се теглят образите — нужни са минути и интернет. После docker compose ps трябва да покаже postgres като healthy, а n8n като running. Проверка дали n8n отговаря:

   bashкопирай

   curl -sf http://localhost:5678/healthz && echo " n8n е жив"

   Ако нещо не стои, виж логовете: docker compose logs -f n8n (изход с Ctrl+C).

5. Първо влизане

   Отвори http://localhost:5678 в браузъра. При първо отваряне n8n те кара да създадеш собственически акаунт (имейл, име, парола) — друга „основна автентикация“ няма. Акаунтът е локален, в твоята база.

   Създай нов работен процес: бутонът за създаване горе вляво в страничното меню → Workflow. Празното платно ти предлага Add first step…

6. Обиколка на интерфейса

   Елемент	Какво прави
   Workflows	Списък на твоите работни процеси; публикуваните са отбелязани със знак
   Credentials	Запазени достъпи (ключове, пароли, OAuth) — шифровани с ключа от .env
   Executions	История на изпълненията на процеса — успешни и грешки; може да се филтрира по статус
   Платно (canvas)	Тук строиш процеса; двоен клик върху нод го отваря
   Add node / N	Отваря панела за търсене и добавяне на нод
   Execute Workflow	Изпълнява целия процес (Ctrl/Cmd+Enter), без да го публикуваш
   Execute step	Изпълнява само избрания нод
   Pin / P	Запазва изхода на нод за тестове — само за разработка
   Publish	Пуска процеса „на живо“ — виж по-долу
   Settings (на нод)	Always Output Data, Execute Once, Retry On Fail, On Error, бележки

   ✅

   Запазването е автоматично

   n8n записва промените сам (за няколко секунди). Няма бутон „Save“, който да забравиш. „Publish“ е друго нещо: то пуска конкретна версия в производство — но само ако процесът има тригер, който се задейства сам (график, уебхук). Процес само с Manual Trigger се пуска от редактора и няма какво да публикуваш.

   За история: старият бутон „Activate“ вече е „Publish“, а нодът „Start“ е премахнат от n8n 2.0 — заменен с Manual Trigger.

7. Първи нод: Manual Trigger

   Натисни Add first step… (или N) → търси Manual Trigger → добави. Този нод стартира процеса при натискане на Execute Workflow.

   💡

   Тригер и действие

   Тригерът започва процеса, действието върши нещо. Ръчният тригер е идеален за тест; в производство го заменяш с график или уебхук (Обучение 7 и 2).

8. HTTP Request: вземи курса

   Натисни + след тригера → HTTP Request. Задай:

   Поле	Стойност
   Method	GET
   URL	https://api.frankfurter.dev/v1/latest?base=EUR&symbols=USD,GBP
   Authentication	None (публично API, без ключ)

   Натисни Execute step. В изхода трябва да видиш обект като този (датата и числата ще са различни):

   json · изход на HTTP Requestкопирай

   {"amount":1.0,"base":"EUR","date":"2026-09-30","rates":{"GBP":0.85463,"USD":1.1355}}

   След като имаш данните, натисни Pin (P) в изхода: n8n ще ползва запомнените данни при следващите тестове и няма да вика API-то всеки път. Това работи само за разработка и само ако изходът не е двоичен файл. Ако искаш свежи данни — Unpin.

   ⚠️

   Версията на API-то

   Използваме /v1/: отговорът има обект rates, удобен за първи урок. Авторите на API-то са го обявили за остаряло в полза на /v2/, но казват, че v1 остава достъпно за неопределено време; v2 връща списък с друга форма. Ако някога смениш на v2, изразите по-долу трябва да се променят.

9. Edit Fields: подреди ред за журнала

   Добави нод Edit Fields (Set) след HTTP Request. Режим Manual Mapping → добави поле с име logLine. Задръж курсора над стойността и избери Expression, после постави:

   израз · стойност на logLineкопирай

   {{ $now.toFormat('yyyy-MM-dd HH:mm') + ' | EUR/USD: ' + $json.rates.USD + ' | EUR/GBP: ' + $json.rates.GBP + '\n' }}

   Какво значи това. Каквото е в {{ }}, е JavaScript. $now е сегашният момент, .toFormat(…) го оформя като текст, $json са данните от предишния нод. '\n' в края е нов ред — без него следващият запис ще залепне към предишния. Натисни Execute step — полето logLine трябва да покаже един ред текст.

10. Convert to File и запис на файла

    Нодът за запис работи с двоични данни (файл), а при нас има текст. Затова първо добави Convert to File → Operation: Convert to Text File → Text Input Field: logLine. После добави Read/Write Files from Disk → Operation: Write File to Disk:

    Поле	Стойност
    File Path and Name	/home/node/.n8n-files/eur_rates_log.txt
    Input Binary Field	полето с файла от предния нод — по подразбиране data (виж изхода на Convert to File и сложи същото име)
    Options → Append	включено (дописва, не презаписва)

    ⚠️

    Защо точно тази папка

    От n8n 2.0 променливата N8N_RESTRICT_FILE_ACCESS_TO е по подразбиране ~/.n8n-files: файловите нодове могат да пишат само там. Пътят е вътре в контейнера, не на твоята машина. Файлът оцелява при рестарт на контейнера, но се губи при docker compose down — за трайно място на файловете трябва отделен том (отделна тема). Преди първото изпълнение подготви папката:
    bashкопирай

    docker compose exec n8n mkdir -p /home/node/.n8n-files

    ⚠️ Не сме проверили дали n8n сам създава тази папка — командата е безобидна и гарантира, че я има.

11. Изпълни целия процес и провери

    Натисни Execute Workflow (или Ctrl/Cmd+Enter). Всеки нод трябва да стане зелен. Провери файла от терминала:

    bashкопирай

    docker compose exec n8n cat /home/node/.n8n-files/eur_rates_log.txt
    # Трябва да видиш нещо като:
    # 2026-10-01 14:32 | EUR/USD: 1.1355 | EUR/GBP: 0.85463

    Изпълни още веднъж — във файла трябва да се появи втори ред. Това показва, че „Append“ работи.

12. Преименувай нодовете и дай име на процеса

    Добра практика: избери нод и натисни F2 (или десен бутон → Rename) и му дай описателно име, за да разбираш процеса след месеци:

    • Manual Trigger → „Ръчен старт“
    • HTTP Request → „Вземи курс EUR“
    • Edit Fields → „Подреди ред за журнала“
    • Convert to File → „Текст във файл“
    • Read/Write Files from Disk → „Запиши в журнала“

    Дай име и на самия процес, например „Курс EUR — дневен журнал“ (n8n го записва автоматично).

13. Когато нещо се счупи: история на изпълненията

    Нарочно счупи процеса: в HTTP Request смени symbols=USD,GBP с symbols=XXX (несъществуваща валута). API-то отговаря с грешка 404, а нодът се проваля, защото успех за него е само отговор от клас 2xx. Изпълни процеса — нодът става червен. После отвори Executions горе, избери последното изпълнение (филтър Status → Failed) и виж кой нод е паднал и защо. Върни symbols=USD,GBP.

    По подразбиране n8n изчиства стари изпълнения след 336 часа (14 дни) или когато са над 10 000 — така базата не расте безкрайно.

14. Всекидневни команди, копие и обновяване

    bash · от ~/n8n-labкопирай

    docker compose up -d          # стартирай всичко
    docker compose ps             # състояние
    docker compose logs -f n8n    # логове на n8n (Ctrl+C за изход)
    docker compose restart n8n    # рестарт само на n8n
    docker compose down           # спри; данните остават в томовете

    Копие на данните. Две части: базата и ключът за криптиране (той е във .env — копирай и този файл на сигурно място).

    bash · копиекопирай

    mkdir -p backups
    docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB"' > backups/n8n-db-$(date +%Y%m%d).sql
    
    docker compose exec n8n n8n export:workflow --backup --output=/home/node/.n8n/backups/
    docker compose cp n8n:/home/node/.n8n/backups ./backups/workflows

    Обновяване. Сменяш числото N8N_VERSION в .env по текущите издания на n8n, после:

    bashкопирай

    docker compose pull
    docker compose up -d

    ⚠️

    Преди всяко обновяване — копие

    Прегледай бележките към изданията за несъвместими промени. Postgres не се надгражда със смяна на числото: скок между основни версии не отваря старите данни — първо pg_dump и официалният наръчник на PostgreSQL.

15. Чести грешки

    ❌

    n8n не стартира — връзка към Postgres

    Healthcheck-ът на Postgres още не е минал. Изчакай половин минута, виж docker compose logs postgres | tail -20, после docker compose restart n8n. Ако си сменял потребителя или паролата във .env след първото пускане, базата пази старите — върни стойностите (docker compose down -v трие всички томове, само в тестова среда!).
    ❌

    Записът на файл дава грешка за достъп или за липсваща папка

    Пътят трябва да е в /home/node/.n8n-files/ (виж стъпката за запис) и папката да съществува. Пътят е в контейнера; n8n вижда само своята файлова система.
    ❌

    В полето излиза [object Object]

    Опитваш се да покажеш цял обект като текст. Вземи конкретното поле: {{ $json.rates.USD }}, не {{ $json.rates }}. Ако искаш целия обект като текст — {{ JSON.stringify($json.rates) }}.
    ❌

    localhost:5678 не се отваря

    Първо docker compose ps — работи ли контейнерът? После curl -sf http://localhost:5678/healthz. На Windows, ако работи в Ubuntu, но не в браузъра, в PowerShell пусни wsl --shutdown и стартирай Docker Desktop наново.
    🔐

    Не отваряй стека към интернет „така“

    Всичко е вързано към 127.0.0.1 нарочно. За достъп отвън ти трябват HTTPS, обратен прокси и отделна работа по сигурността.

04Проверка

Чеклист

• docker compose version показва v2.x.
• .env съществува с генерирани тайни, права 600, а ключът е преписан на сигурно място.
• docker compose config --quiet не дава грешка; docker compose ps показва postgres healthy и n8n running.
• /healthz отговаря; собственическият акаунт е създаден.
• HTTP Request връща обект с rates; редът за журнала се подрежда с израз.
• Във файла се добавя нов ред при всяко изпълнение.
• Разбираш защо нарочно счупеното изпълнение се вижда в Executions.
• Има копие на базата и на работните процеси.

Тест

05Какво следва

06Източници

1. n8n: инсталиране с Docker Compose — Compose v2, бележката за WSL, секцията за Postgres и PGDATA; още: n8n-hosting: Compose с Postgres.
2. n8n 2.0: несъвместими промени — публикуване, достъп до файлове, премахнатият нод „Start“.
3. Запазване и публикуване · Създаване и пускане на работни процеси · бързи клавиши · pin и тестови данни.
4. Нодове: HTTP Request · Edit Fields (Set) · Convert to File · Read/Write Files from Disk.
5. Променливи за средата: изпълнения · сигурност · часова зона; копия и възстановяване.
6. n8n: справочник за изразите — $now, $json.
7. n8n: издания в GitHub — текуща стабилна 2.41.4 към 01.10.2026.
8. Frankfurter 🌐 глобален — публичното API за валутни курсове.