Як розгорнути OpenAnalytics на власному VPS
Потрібні ClickHouse, Postgres, Valkey, 4 GB RAM, 25 GB вільного місця й чотири DNS-записи. Покрокове встановлення та пояснення, що заповнює диск.
Вимоги до ресурсів перед першим кроком
Щоб розгорнути OpenAnalytics у власній інфраструктурі, потрібен Linux VPS приблизно з 4 GB RAM, 25 GB вільного дискового простору, Docker із Compose plugin і чотири DNS-записи, які вже вказують на цей сервер. Це основна вимога. Її слід зазначити перед першою командою, а не після неї.
Стек складається із шести application services і трьох сховищ даних. Postgres зберігає control plane: облікові записи, сайти, API keys і share links. ClickHouse зберігає необроблені події та rollup-дані, які читає dashboard. Valkey запускається двічі: один екземпляр працює як надійна черга подій, а другий — як кеш, втрата якого допустима. Для цих двох завдань потрібні протилежні eviction policies. Лише один процес, query gateway, може читати ClickHouse. Перед виконанням кожного запиту він перевіряє Ed25519-підпис у query envelope.
Якщо вам потрібні були один binary і один config file, цей варіант не підходить. GoatCounter — це варіант із single binary у цій категорії: один Go executable, SQLite за замовчуванням і взагалі без зовнішньої бази даних. Важчий стек дає funnels, web vitals, revenue attribution із власного Stripe account і MCP (model context protocol) server. Вибір між self-hosted analytics tools — це допис, у якому розглянуто цей компроміс. У цьому посібнику передбачається, що ви вже зробили вибір.
Спочатку налаштуйте чотири DNS-записи для сервера
Чотири піддомени мають визначатися в публічну IP-адресу сервера до початку налаштування, оскільки Caddy запитує сертифікати Let's Encrypt під час першого запуску. Перевірка не пройде для імені, яке ще не визначається.
app.example.comобслуговує dashboard.api.example.comобслуговує API і OAuth callbacks.c.example.comобслуговує collector і tracker script.rt.example.comобслуговує realtime stream.
Використайте чотири записи A або один запис A і три записи CNAME, що вказують на нього. Перед продовженням перевірте це за допомогою dig +short app.example.com. Ім’я, яке ви додали хвилину тому, ще може кешуватися як NXDOMAIN у DNS-resolver, який використає Let's Encrypt. Тому після невдалої першої спроби отримання сертифіката варто зачекати та переглянути журнали Caddy. Повторний запуск інсталяції не пришвидшує поширення DNS-змін.
Як самостійно розгорнути OpenAnalytics за допомогою Docker Compose
Перейдіть на позначений тегом реліз. У гілці за замовчуванням триває розроблення, а опубліковані images фактично відповідають тегу релізу. Наведені нижче команди передбачають, що Docker і плагін Compose вже встановлено. Це описано в матеріалі про запуск сервісів Docker Compose на VPS.
git clone https://github.com/OpenLabs-so/openanalytics
cd openanalytics
git checkout "$(git tag -l 'v*' --sort=-v:refname | sed '/-/d' | head -1)"
cd infra/selfhost
./generate-secrets.sh --domain example.com --email you@example.com --with-geoip
docker compose pull && docker compose up -dПараметр sed '/-/d' у команді checkout відкидає pre-release теги, тому ви переходите на найновішу стабільну версію, а не на release candidate. Параметр --with-geoip завантажує базу даних міст DB-IP під час генерації. Якщо пропустити цей параметр, кожна подія матиме значення країни null, тому на географічному поданні взагалі не буде даних. Додати базу пізніше можна командою infra/selfhost/geoip/fetch-dbip.sh, установивши GEOIP_DB_PATH=/geoip/dbip-city-lite.mmdb у env/collector.env, а потім повторно створивши collector за допомогою docker compose up -d --force-recreate collector. Цю базу оновлюють щомісяця, тому щомісяця повторюйте завантаження. Інакше дані про міста поступово застаріватимуть.
Збережіть згенеровані секрети перед подальшими діями
Генератор записує три типи даних. .env містить імена доменів і посилання на images. env/*.env містить окремий файл секретів для кожного сервісу. docker-compose.override.yml містить дві пари ключів Ed25519 у YAML block scalars: одну для підписування запитів, іншу для realtime-токенів, оскільки багаторядковий PEM не може зберігатися в env-файлі. Кожна частина передається лише сервісу, якому вона потрібна: API отримує обидва приватні ключі, query gateway — публічний ключ для запитів, а realtime-сервіс — ключ перевірки токенів. Усі ці файли додані до gitignore, і відновити їх із тими самими значеннями неможливо.
Скопіюйте ці файли з сервера вже зараз. Втрата кожного з них має конкретні наслідки:
- Якщо втратити паролі сховищ, ви втратите доступ до Postgres і ClickHouse. Скинути їх можна буде лише зсередини контейнерів.
- Якщо втратити
OA_CREDENTIAL_KEYRING, усі збережені облікові дані сторонніх сервісів неможливо відновити. Тому кожен, хто підключав обліковий запис Stripe, має підключити його повторно. - Якщо втратити
ANONYMOUS_IDENTITY_SECRET, ідентифікація відвідувачів почнеться заново: учорашні відвідувачі рахуватимуться новими, і це буде видно на графіках. - Якщо втратити
AUTH_SECRET, усі сеанси стануть недійсними, і всі користувачі мають увійти знову. - Якщо втратити приватний ключ підписування, замініть пару ключів. Дані не втрачаються.
Два секрети мають бути побайтно ідентичними в кожній із двох відповідних пар файлів. ANONYMOUS_IDENTITY_SECRET міститься у collector.env і worker.env, оскільки collector обчислює hash відвідувача, а worker записує його. OA_CREDENTIAL_KEYRING міститься у api.env і worker.env. Усе інше навмисно обмежене рівно одним сервісом, а сервіс, якому передали секрет, яким він не має володіти, завершує роботу замість запуску.
Запустіть стек і перевірте його
grep OA_IMAGE .env
docker compose pull
docker compose up -d
docker compose logs -f migrate
docker compose psmigrate застосовує схеми Postgres і ClickHouse, а потім завершує роботу, тому зупинений контейнер migrate є правильним кінцевим станом. tracker-build компілює oa.js у volume, який обслуговує Caddy, а потім також завершує роботу. Усе інше має мати стан healthy у docker compose ps. Якщо сервіс постійно перезапускається, майже завжди не проходить перевірка змінних середовища. Журнал виводить усі проблеми одним списком, а не по одній проблемі після кожного перезапуску. Дві найпоширеніші причини: змінна залишилася порожньою, що відхиляється замість трактування як не заданої, або секрет указано у файлі неправильного сервісу.
На arm64 або під час роботи з гілкою опублікованих образів немає, тому їх потрібно локально зібрати за допомогою docker compose up -d --build. На хості з 4 GB пам’яті під час такої збірки закінчується пам’ять. Спочатку додайте swap. Він потрібен лише на час збірки:
fallocate -l 4G /swapfile && chmod 600 /swapfile && mkswap /swapfile && swapon /swapfile
echo '/swapfile none swap sw 0 0' >> /etc/fstabЗбірка триває приблизно десять хвилин. Завантаження займає кілька хвилин, тому й існують release images.
Створіть перший обліковий запис негайно
Відкрийте https://app.example.com. Розгортання, у якому ще ніхто не виконав вхід, не показує форму входу: воно пропонує створити перший обліковий запис. Цей обліковий запис назавжди залишається привілейованим і єдиним має доступ до екрана налаштувань розгортання. Після його створення маршрут повертає 409, тому ніхто не зможе отримати доступ після вас. Зробіть це одразу, щойно стек буде працездатним, а не наступного тижня.
Встановіть tracker
Додайте сайт у dashboard, і він надасть вам tag. Його формат фіксований:
<script
async
src="https://c.example.com/oa.js"
data-key="YOUR_TRACKING_KEY"
data-collector="https://c.example.com"
></script>Додайте його в head сторінки. Tracking key навмисно є публічним, тому він має бути у вашому HTML, де його може прочитати будь-хто. Скрипт встановлює window.oa, а виклики на кшталт oa("track", ...) stub ставить у чергу та передає після завантаження файлу, тому custom event, згенерований заздалегідь, не втрачається. Якщо інший код на сторінці вже використовує window.oa, tracker натомість встановлює window.openanalytics. Якщо той самий сайт також доступний як onion service, не додавайте tag до тієї збірки, оскільки скрипт, завантажений із c.example.com, повертає відвідувача Tor Browser у clearnet і пов’язує обидві адреси в межах одного завантаження сторінки.
Потім перевірте весь ланцюжок від початку до кінця:
curl -s https://c.example.com/oa.js -o /dev/null -w '%{http_code} %{size_download}\n'
curl -s https://api.example.com/health | head -c 200
docker compose logs --tail=50 worker | grep -i batchПерша команда має вивести 200 і кілька кілобайтів даних. Відкрийте сторінку на своєму сайті, а потім протягом кількох секунд знайдіть у журналі worker рядок про пакет. Collector повертає 202 одразу після прийняття event, а 202 означає, що подію поставлено в чергу, але ще не збережено. Саме worker переміщує події до ClickHouse. Якщо події приймаються, але в dashboard нічого не з’являється, worker заблокований. Це підтверджує зростання довжини черги Valkey. Зазвичай причина полягає в неправильних облікових даних ClickHouse у worker.env або у відсутньому grant для таблиці, яку щойно додала міграція.
Не закривайте collector від публічного доступу, а dashboard захистіть автентифікацією
Caddy постачається у складі compose-файлу й самостійно отримує сертифікати для всіх чотирьох імен, тому стандартний варіант не потребує додаткового налаштування проксі. Якщо на сервері вже працює reverse proxy на nginx, розмістіть стек за наданим infra/selfhost/nginx.conf.example і не змінюйте обробку заголовків:
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header CF-Connecting-IP "";
proxy_set_header True-Client-IP "";
proxy_set_header Fly-Client-IP "";Collector обчислює добовий хеш відвідувача з IP-адреси клієнта, тому має отримувати цю адресу безпосередньо із з’єднання, а не із заголовка. Передавання CF-Connecting-IP від недовіреного вузла дає будь-якому клієнту змогу вказати довільну адресу. Це одночасно спотворює геолокацію та завищує кількість відвідувачів.
Доступ чітко розподіляється за іменем хоста. c. і rt. мають бути доступними кожному відвідувачу кожного сайту, який ви вимірюєте, тому не встановлюйте перед ними basic auth або список дозволених IP-адрес. app. і api. мають бути доступними лише користувачам, які увійшли в систему. Dashboard захищає власна автентифікація застосунку: вхід за паролем за замовчуванням увімкнений через AUTH_PASSWORD_SIGNIN=enabled у env/api.env, а кнопки Google або GitHub з’являються лише тоді, коли для відповідного провайдера задано і client ID, і client secret. Для magic links потрібен поштовий транспорт. Без нього API лише записує повідомлення до outbox, тому воно не доставляється, але й помилки не виникає. Якщо інші ваші self-hosted застосунки вже працюють за єдиним входом Authentik, заздалегідь вирішіть, чи долучати до нього цей dashboard, чи залишити для нього окремі облікові записи. Перший обліковий запис, створений тут, назавжди матиме привілейований статус.
Один параметр визначає, чи працюватиме dashboard взагалі. AUTH_TRUSTED_ORIGINS у env/api.env має точно відповідати origin dashboard. Якщо значення неправильне або відсутнє, API не надсилає заголовки CORS (cross-origin resource sharing), браузер відхиляє кожен виклик, а dashboard відображає макет, але не показує даних, тоді як docker compose ps повідомляє, що все працює належним чином.
Поки ви редагуєте конфігурацію проксі, налаштуйте обробку автоматизованого трафіку. Crawler-и звертаються до collector так само, як і звичайні клієнти, а їхні перегляди сторінок потрапляють до ClickHouse і враховуються у ваших показниках. Блокування AI crawler-ів на сервері дає змогу не записувати частину цього трафіку до бази даних, перш ніж він вплине і на точність даних, і на використання диска.
Що тут означає cookieless і чого це вам коштує
Файлів cookie немає. Ідентифікатор відвідувача — це хеш із сіллю. Сіль змінюється щодня, а необроблені IP-адреси ніколи не зберігаються. Геолокація визначається локально за файлом DB-IP на вашому диску, тому жоден запит про відвідувача не залишає хост. Локальне виконання запитів усуває постачальника, але не самі дані. Це те саме обмеження, яке виникає, коли ви запускаєте власний екземпляр SearXNG і IP-адреса вашого сервера стає адресою, яку бачать пошукові системи.
Перевага полягає у відсутності ідентифікатора, збереженого на пристрої відвідувача. Саме така ідентифікація підпадає під правила ЄС щодо згоди відповідно до ePrivacy. Тому агреговані конфігурації, як ця, часто використовують без банера згоди. GDPR усе одно регулює дані, які ви зберігаєте, і строк їх зберігання. Конкретну оцінку для вашого випадку дає ваш юридичний радник, а не README.
Ціна — відсутність ідентифікації між днями. Через зміну солі особа, яка відвідала сайт у понеділок, а потім у середу, навмисно враховується як два відвідувачі. Обійти це неможливо. Щоденні унікальні показники є коректними. Тижневі й місячні унікальні показники будуються на основі щоденних і завищують охоплення. Тому будь-який показник «повторних відвідувачів» за тривалий період не вимірює те, що вказано в його назві. Сеанси та шляхи переходів є надійними в межах одного дня. Зміна ANONYMOUS_IDENTITY_SECRET має такий самий ефект, як межа дня. Тому сприймайте цю зміну як зміну даних, а не як звичайне обслуговування.
Колектор враховує Do Not Track і Global Privacy Control — сигнал браузера, який повідомляє сайту, що персональні дані не можна продавати або передавати. Тег script має власні перемикачі для тієї самої мети: data-respect-gpc, data-respect-dnt і data-require-consent. Останній призупиняє весь збір даних до надання згоди та зберігає відповідь у localStorage під ключем oa.consent. Налаштування data-storage="none" повністю вимикає сховище браузера.
Чому диск заповнюється через шість місяців
Саме це зазвичай виводить із ладу self-hosted analytics-сервер. Події здебільшого не є причиною.
Почніть з images. Один release публікує десять images, які разом займають приблизно 13 GB на диску. Під час оновлення нове покоління завантажується до видалення старого, тому певний час на диску зберігаються два покоління. Це становить більшу частину вимоги у 25 GB ще до надходження першого перегляду сторінки.
Далі йдуть snapshots. snapshot.sh зупиняє stack, архівує обидва data volumes разом з усіма секретами та запускає stack знову. Тут безпечними є лише cold copies, оскільки ClickHouse у фоновому режимі об’єднує parts, а копія, створена під час такого об’єднання, буде неузгодженою. upgrade.sh автоматично створює snapshot перед кожним оновленням, тому архіви накопичуються на тому самому диску, доки ви не обмежите їхню кількість.
./snapshot.sh create --label before-something-risky
./snapshot.sh list
./snapshot.sh --keep 3Якщо вільного місця на host майже не залишилося, видаліть попереднє покоління перед оновленням. Це безпечно, поки stack працює, оскільки images, на яких базуються запущені контейнери, усе ще використовуються:
docker image prune -a -fДалі врахуйте самі події. ClickHouse ефективно стискає columnar data, тому обсяг raw events зростає повільніше, ніж зазвичай очікують, а rollup tables, які читає dashboard, малі порівняно з raw table. Вимірюйте, а не припускайте:
docker system df -v
docker compose exec clickhouse df -h /var/lib/clickhouseЩоб отримати дані для окремої таблиці, виконайте це з обліковими даними ClickHouse, які генератор записав у infra/selfhost/env/:
SELECT table, formatReadableSize(sum(bytes_on_disk)) AS size, sum(rows) AS row_count
FROM system.parts
WHERE active
GROUP BY table
ORDER BY sum(bytes_on_disk) DESC;Зніміть це значення в перший тиждень і повторіть вимірювання на четвертому тижні. Дві точки дають темп зростання, а за темпом зростання можна визначити, коли потрібно збільшити обсяг тому. Станом на October 2026 self-hosting guide не документує параметра retention або time-to-live для raw events, тому розраховуйте обсяг диска за виміряним темпом, а не припускайте, що старі рядки видаляються самостійно.
Перед видаленням варто знати про одну пастку. Видалення site або account ставить завдання в чергу для worker. Для цього мають бути задані CLICKHOUSE_MAINTENANCE_USER і CLICKHOUSE_MAINTENANCE_PASSWORD, а в ClickHouse має існувати користувач oa_maintenance із відповідними параметрами. Без них завдання на видалення залишатиметься в черзі назавжди. Site зникне з dashboard, але всі рядки залишаться на диску. У результаті очищення лише виглядатиме виконаним, а вільного місця не побільшає.
Оновлення та три витрати
git fetch --tags
git checkout "$(git tag -l 'v*' --sort=-v:refname | sed '/-/d' | head -1)"
cd infra/selfhost
./upgrade.shupgrade.sh виводить три витрати перед виконанням операції. Простій є реальним: події, які надходять, коли collector не працює, втрачаються, оскільки tracker не повторює їх надсилання. Відкат призводить до втрати даних, оскільки rollback.sh --to backups/<snapshot> повністю замінює обидва сховища та видаляє всі рядки, записані після створення цього snapshot. Третя витрата — дисковий простір, тобто описаний вище набір snapshot.
Є два правила перезапуску, у яких легко помилитися. Спочатку запустіть query gateway, а потім API, оскільки новіша версія API надсилає поля запиту, які старіший gateway відхиляє. А для ClickHouse потрібне пересоздання контейнера, а не перезапуск, оскільки docker compose restart повторно використовує початкове середовище контейнера та мовчки ігнорує внесену вами зміну:
docker compose up -d --force-recreate clickhouseДля dashboard діє така сама схема. Три джерела NEXT_PUBLIC_* у env/web.env вбудовуються в browser bundle і підставляються під час запуску контейнера, тому неправильний hostname у dashboard виправляють за допомогою docker compose up -d --force-recreate web, а не restart. Журнал web container виводить джерела, з якими він запустився. Це найшвидший спосіб перевірити, що зміна застосувалася.
Якщо ClickHouse відмовляється запускатися після редагування конфігурації, прочитайте перший рядок його журналу. Рядок, що починається з oa-entrypoint:, означає, що entrypoint відхилив установлене вами значення. В інших випадках зазвичай йдеться про некоректний XML у файлі конфігурації. Найпоширеніша причина — подвійний дефіс усередині XML-коментаря, що є недопустимим.
AGPL-3.0 і назва
Код ліцензовано за AGPL-3.0, за одним винятком: починаючи з v0.7.0 browser tracker, усе в apps/tracker/ і oa.js, який він створює, ліцензовано за MIT. Тому tag, який ви додаєте до власних сторінок, не містить умов AGPL. Запуск незміненого коду для власних сайтів не створює жодного обов’язку публікувати код. Такий обов’язок виникає, коли ви змінюєте код і запускаєте змінену версію як мережевий сервіс: тоді ліцензія вимагає запропонувати користувачам цього сервісу вихідний код ваших змін. Це стосується надання клієнтам dashboard на вашому instance, а також включення коду до продукту, який ви продаєте. Якщо зберігати зміни в public fork, цього достатньо, і додаткових дій не потрібно.
Бренд не залежить від коду. Назва "OpenAnalytics" і hosted domain проєкту ідентифікують instance, яким керують автори, і не входять до наданих ліцензією прав. Ваш deployment запускає software без цього бренду, тому перед наданням сервісу платним клієнтам дайте йому власну назву.
FAQ
Чи можна запустити OpenAnalytics на VPS із 1 GB?
Ні. Проєкту потрібно близько 4 GB RAM і 25 GB вільного дискового простору, оскільки одне розгортання запускає шість сервісів застосунку разом із Postgres, ClickHouse і двома екземплярами Valkey. Сам ClickHouse не є малим процесом. На сервері з 1 GB контейнери запускаються, після чого kernel out-of-memory killer завершує один із них, зазвичай ClickHouse. Якщо обмеження в 1 GB є жорстким, використовуйте інструмент з одним бінарним файлом, наприклад GoatCounter, який працює на SQLite без зовнішньої бази даних.
Чи потрібен cookie banner для OpenAnalytics?
Це питання для вашого юриста, але технічні факти на вашу користь. Cookie не використовується, ідентифікатор відвідувача є salted hash, який змінюється щодня, а необроблені IP-адреси ніколи не зберігаються. Тому для ідентифікації відвідувача не записуються постійні дані. GDPR усе одно регулює, які дані ви зберігаєте і як довго їх утримуєте. Якщо потрібно явно керувати збором даних через згоду, задайте data-require-consent у script tag: tracker не збиратиме нічого, доки згоду не буде надано, і збереже відповідь у localStorage під oa.consent.
Чому події повертають 202, але ніколи не з’являються в dashboard?
202 означає, що collector прийняв подію та поставив її в чергу, а не те, що він зберіг її. Worker переносить події з цієї черги до ClickHouse, тому порожній dashboard за успішних запитів вказує на проблему з worker. Прочитайте docker compose logs --tail=50 worker і моніторте розмір черги Valkey. Черга, яка постійно зростає, означає, що worker заблокований. Зазвичай причиною є неправильні облікові дані ClickHouse у worker.env або відсутній grant для таблиці, створеної під час останньої міграції.
Чому dashboard порожній, якщо всі контейнери працюють без помилок?
Спочатку перевірте AUTH_TRUSTED_ORIGINS у env/api.env. Він має точно відповідати origin dashboard. Якщо це не так, API не надсилає CORS headers, тому браузер відхиляє кожен виклик, і ви бачите працездатний інтерфейс без даних. Далі перевірте три значення NEXT_PUBLIC_* у env/web.env. Вони підставляються під час запуску web container. Щоб виправити їх, потрібен docker compose up -d --force-recreate web, оскільки звичайний restart зберігає старі значення.
Чи забороняє AGPL-3.0 пропонувати цей продукт клієнтам?
Ні, ця ліцензія встановлює одну умову. Якщо ви запускаєте код без змін, ви нікому нічого не винні. Якщо ви змінюєте код і запускаєте змінену версію як сервіс, яким користуються інші люди, ви повинні надати цим користувачам вихідний код своїх змін. Цю вимогу задовольняє public fork. Окремо, назва "OpenAnalytics" не ліцензується разом із кодом, тому для будь-якого комерційного продукту потрібна власна назва.