Перейти до змісту

Встановлення

Ця сторінка описує процес production-встановлення Bangi Tracker. Використовуйте цей гайд як базу та за потреби змінюйте команди, версії, домени й шляхи до файлів відповідно до вашого сервера та середовища розгортання.

1. Придбайте та підготуйте VPS

  1. Створіть новий VPS (рекомендовано Ubuntu LTS).
  2. Виберіть розмір сервера, регіон і спосіб автентифікації (рекомендовано SSH-ключ).
  3. Підключіться до сервера:
ssh root@<server-ip>
  1. Виконайте базове hardening-налаштування сервера (наприклад, створіть non-root користувача та налаштуйте firewall). Це поза межами цього гайду.

2. Налаштуйте DNS домену

Спрямуйте ваш домен на IP-адресу VPS.

  1. Відкрийте панель керування у вашого DNS-провайдера.
  2. Створіть або оновіть запис A:
  3. Host: @ для кореневого домену або піддомен (наприклад, tracker для tracker.<your-domain>)
  4. Value: <server-ip> (публічна IP-адреса вашого сервера)
  5. TTL: <ttl-value> (час кешування DNS у секундах)
  6. Зачекайте на поширення DNS.

Поширення DNS часто займає кілька хвилин, але інколи може тривати до 24-48 годин залежно від провайдера, кешів резолверів і значення TTL.

3. Налаштуйте сертифікат Let's Encrypt (Certbot)

HTTPS є обов'язковим для production, оскільки шифрує трафік між користувачами та сервером, захищає облікові дані від перехоплення й підвищує довіру користувачів. Сучасні браузери також позначають сайти без HTTPS як "Not secure", а частина інтеграцій потребує HTTPS.

Встановіть Certbot і отримайте SSL-сертифікат для вашого домену.

sudo apt update
sudo apt install -y certbot python3-certbot-nginx
sudo certbot certonly --nginx -d <your-domain>

Let's Encrypt перевіряє право власності на домен перед випуском сертифіката. Багато хостинг-провайдерів (наприклад, DigitalOcean або Vultr) вже мають встановлений nginx, тому перевірка --nginx зазвичай найпростіша.

Якщо у вашому середовищі nginx недоступний, використовуйте standalone-режим Certbot або DNS challenge для підтвердження домену.

Перевірте автоматичне продовження сертифіката:

sudo certbot renew --dry-run

Примітки: - Шляхи до сертифікатів: - /etc/letsencrypt/live/<your-domain>/fullchain.pem - /etc/letsencrypt/live/<your-domain>/privkey.pem

4. Запуск застосунку через Docker Compose

Застосунок можна розгортати в різних середовищах. У цьому гайді описано, як розгорнути та запустити сервіси Bangi Tracker за допомогою Docker Compose.

4.1 Встановіть Docker і Docker Compose

Встановіть необхідні пакети ОС для додавання зовнішніх репозиторіїв:

sudo apt update
sudo apt install -y ca-certificates curl gnupg

Додайте офіційний GPG-ключ Docker і APT-репозиторій:

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo $VERSION_CODENAME) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Встановіть Docker Engine і плагін Docker Compose із репозиторію Docker:

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Увімкніть автозапуск Docker і перевірте, що Docker Compose доступний:

sudo systemctl enable --now docker
docker compose version

4.2 Налаштуйте сервіси

У цьому розділі ви підготуєте всі runtime-конфігураційні файли стеку: облікові дані бази даних, змінні середовища бекенда, API-налаштування фронтенда та файл бази IP2Location, який використовує бекенд.

Створіть директорію для Bangi Tracker.

mkdir -p /app/bangi-tracker
cd /app/bangi-tracker

Створіть локальні конфігураційні файли для наступних кроків:

touch bangi-db.env bangi-backend-config.env bangi-ui-config.js docker-compose.yml

Згенеруйте надійні паролі перед редагуванням environment-файлів:

openssl rand -base64 24

4.2.1 Налаштуйте сервіс MariaDB

Відредагуйте bangi-db.env так:

MARIADB_DATABASE=bangi_tracker
MARIADB_USER=bangi
MARIADB_PASSWORD=<generate-strong-password>
MARIADB_ROOT_PASSWORD=<generate-strong-password>

Довідка щодо конфігурації MariaDB:

Обов'язково змінити для production-безпеки: - MARIADB_PASSWORD: пароль для MARIADB_USER. - MARIADB_ROOT_PASSWORD: root-пароль для ініціалізації контейнера MariaDB та адмін-задач.

Можна змінити: - MARIADB_DATABASE: назва бази даних для даних застосунку Bangi Tracker. - MARIADB_USER: користувач бази для застосунку (не root).

4.2.2 Налаштуйте сервіс бекенда

Відредагуйте bangi-backend-config.env за шаблоном:

MARIADB_HOST=mariadb
MARIADB_PORT=3306
BASIC_AUTHENTICATION_USERNAME=admin
BASIC_AUTHENTICATION_PASSWORD=<generate-strong-password>
LANDING_PAGES_BASE_PATH=/app/landings
IP2LOCATION_DB_PATH=/app/IP2LOCATION-LITE-DB1.IPV6.BIN
LANDING_PAGE_RENDERER_BASE_URL=http://landing-renderer/landings
INTERNAL_PROCESS_BASE_URL=http://localhost:8000/process

Довідка щодо змінних середовища:

Важливо: - Змінні з цього розділу використовуються і в коді застосунку, і в docker-compose.yml. - Якщо ви змінюєте назви сервісів, шляхи, URL або порти, внесіть відповідні зміни в docker-compose.yml (наприклад, volumes, depends_on і відкриті порти).

Обов'язково змінити для production-безпеки: - BASIC_AUTHENTICATION_PASSWORD: пароль для автентифікації в Bangi Tracker.

Можна змінити: - BASIC_AUTHENTICATION_USERNAME: ім'я користувача для автентифікації в Bangi Tracker.

Зазвичай не варто змінювати, якщо ви також не оновлюєте docker-compose.yml (і не розумієте пов'язані зміни): - LANDING_PAGES_BASE_PATH: шлях у файловій системі, де зберігаються файли лендингів. - IP2LOCATION_DB_PATH: шлях у файловій системі до файлу бази IP2Location. - LANDING_PAGE_RENDERER_BASE_URL: базовий URL сервісу рендерингу лендингів, який використовує бекенд. - INTERNAL_PROCESS_BASE_URL: базовий URL внутрішнього endpoint для обробки доменів/кампаній.

4.2.3 Налаштуйте сервіс фронтенда

Відредагуйте bangi-ui-config.js так:

window.APP_CONFIG = window.APP_CONFIG || {
  BACKEND_API_BASE_URL: "https://<your-domain>/api/v2"
};

Довідка щодо конфігурації фронтенда:

  • BACKEND_API_BASE_URL: публічний базовий URL, який UI використовує для всіх API-запитів до бекенда.

4.2.4 Налаштуйте базу IP2Location

IP2LOCATION_DB_PATH вказує на файл бази геолокації IP, який використовує бекенд. IP2Location надає кілька варіантів баз; ця конфігурація протестована лише з IP2LOCATION-LITE-DB1.IPV6.BIN.

Кроки налаштування:

  1. Зареєструйте акаунт на сайті IP2Location.
  2. Завантажте потрібну версію файлу бази IP2Location для вашого розгортання.
  3. Помістіть файл у /app/bangi-tracker.

Обслуговування:

Бази IP2Location періодично оновлюються провайдером. Регулярно завантажуйте нові версії та замінюйте старий файл.

Завантажте базу IP2Location із локальної машини на сервер через scp:

scp ~/Downloads/IP2LOCATION-LITE-DB1/IP2LOCATION-LITE-DB1.IPV6.BIN root@<server-ip>:/tmp

Потім перемістіть файл бази в директорію застосунку:

mv /tmp/IP2LOCATION-LITE-DB1.IPV6.BIN /app/bangi-tracker/

4.3 Налаштування Docker Compose

docker-compose.yml має містити:

services:
  mariadb:
    image: mariadb:11.4
    restart: always
    env_file:
      - bangi-db.env
    volumes:
      - .mariadb:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
  landing-renderer:
    image: php:8.2-apache
    volumes:
      - ./landings:/var/www/html/landings
  backend:
    image: ghcr.io/devalentino/bangi-backend:0.0.1a1
    restart: always
    env_file:
      - bangi-backend-config.env
      - bangi-db.env
    ports:
      - '8000:5000'
    volumes:
      - ./landings:/app/landings
      - ./IP2LOCATION-LITE-DB1.IPV6.BIN:/app/IP2LOCATION-LITE-DB1.IPV6.BIN
    healthcheck:
      test: [ "CMD", "curl", "-f", "http://0.0.0.0:5000/api/v2/health" ]
      interval: 120s
      timeout: 10s
      retries: 3
      start_period: 120s
    depends_on:
      mariadb:
        condition: service_healthy
  ui:
    image: ghcr.io/devalentino/bangi-ui:0.0.1a1
    restart: always
    ports:
      - '8001:80'
    volumes:
      - ./bangi-ui-config.js:/usr/share/nginx/html/app-config.js

Перевірте, що всі файли створені:

ls -la

Вивід має виглядати приблизно так:

total 11152
drwxr-xr-x 2 root root     4096 Feb 18 17:12 .
drwxr-xr-x 3 root root     4096 Feb 18 16:19 ..
-rwxr-xr-x 1 root root 11399090 Feb 18 17:06 IP2LOCATION-LITE-DB1.IPV6.BIN
-rw-r--r-- 1 root root      482 Feb 18 16:52 bangi-backend-config.env
-rw-r--r-- 1 root root      120 Feb 18 16:52 bangi-db.env
-rw-r--r-- 1 root root      111 Feb 18 16:53 bangi-ui-config.js
-rw-r--r-- 1 root root     1272 Feb 18 17:12 docker-compose.yml

Запустіть застосунок:

docker compose pull
docker compose up -d

Перевірте логи та стан контейнерів:

docker compose ps
docker compose logs -f

5. Налаштуйте Nginx (SSL + Reverse Proxy)

Nginx — це фінальний шар, який поєднує домен, SSL-сертифікати та сервіси застосунку. Його також можна використовувати для налаштування додаткових кампанійних доменів. На багатьох хостингах Nginx вже встановлено; перевірити це можна так:

sudo ls -la /etc/nginx/

Якщо директорія існує та містить конфігураційні файли, ви можете пропустити наступний крок встановлення. Якщо директорії немає, встановіть Nginx.

5.1 Встановіть Nginx (Ubuntu)

sudo apt update
sudo apt install -y nginx
sudo systemctl enable --now nginx
sudo nginx -v

5.2 Налаштуйте Nginx для вашого домену

Створіть файл конфігурації сайту /etc/nginx/sites-available/<your-domain> з таким вмістом:

server {
    listen 80;
    server_name <your-domain>;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name <your-domain>;

    ssl_certificate /etc/letsencrypt/live/<your-domain>/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/<your-domain>/privkey.pem;

    location /api/v2 {
        proxy_pass http://127.0.0.1:8000/api/v2;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location / {
        proxy_pass http://127.0.0.1:8001/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Що робить ця конфігурація:

  • Перший блок server слухає порт 80 (HTTP) і постійно перенаправляє весь трафік на HTTPS, щоб усі запити були захищені.
  • Другий блок server обробляє зашифрований трафік на порту 443, використовуючи сертифікат і приватний ключ Let's Encrypt. Сертифікати створюються в розділі 3.
  • location /api/v2 проксіює API-запити до контейнера бекенда на 127.0.0.1:8000, зберігаючи префікс /api/v2.
  • location / проксіює всі інші запити до контейнера фронтенда на 127.0.0.1:8001.
  • Директиви proxy_set_header передають оригінальний host, IP клієнта та протокол, щоб сервіси коректно логували реальний клієнтський трафік і правильно обробляли secure-запити.

5.3 Увімкніть і перевірте конфігурацію

sudo rm -f /etc/nginx/sites-enabled/default
sudo ln -sf /etc/nginx/sites-available/<your-domain> /etc/nginx/sites-enabled/<your-domain>
sudo nginx -t
sudo systemctl reload nginx

Що роблять ці команди:

  • rm -f /etc/nginx/sites-enabled/default видаляє дефолтний сайт, щоб уникнути конфліктів із конфігурацією вашого домену.
  • ln -sf вмикає ваш сайт, створюючи (або замінюючи) симлінк із sites-available у sites-enabled, звідки Nginx завантажує активні virtual hosts.
  • nginx -t перевіряє синтаксис повної конфігурації Nginx і доступність згаданих файлів (включно із сертифікатами).
  • systemctl reload nginx застосовує нову конфігурацію без повного рестарту сервісу, тому активні з'єднання не перериваються.

5.4 Перевірка після розгортання (опційно)

Виконайте ці перевірки після перезавантаження Nginx:

curl -I http://<your-domain>
curl -I https://<your-domain>
curl -sS https://<your-domain>/api/v2/health
docker compose ps

Очікувані результати:

  • http:// відповідає 301-редіректом на https://.
  • https:// відповідає 200 і повертає валідний ланцюжок TLS-сертифіката.
  • /api/v2/health повертає статус healthy.
  • docker compose ps показує контейнери backend, ui і mariadb у стані running або healthy.

6. Вхід у застосунок

Після завершення розгортання відкрийте браузер і перейдіть за адресою:

  • https://<your-domain>

Увійдіть, використовуючи облікові дані зі змінних середовища бекенда:

  • Username: значення BASIC_AUTHENTICATION_USERNAME
  • Password: значення BASIC_AUTHENTICATION_PASSWORD