Автономная среда тестирования API и вебхуков Hoppscotch: развертывание на VDS в Docker Compose без облачных ограничений Postman

Корпоративные команды разработчиков и системных администраторов всё чаще сталкиваются с ограничениями коммерческих облачных платформ тестирования API. Популярный сервис Postman последовательно урезал бесплатный функционал для совместной работы (лимит до 3 участников в команде), закрыл автономный локальный режим Scratchpad и принудительно синхронизирует все коллекции запросов в зарубежное облако. Для проектов с чувствительными данными это создает критические риски: боевые JWT-токены, секретные API-ключи, внутренние микросервисные эндпоинты и структуры баз данных оказываются на сторонних серверах за пределами юрисдикции РФ.

Надежной и проверенной альтернативой выступает Hoppscotch — открытая (более 65 000 звёзд на GitHub), сверхбыстрая и легковесная платформа для отладки REST, GraphQL, WebSocket, Server-Sent Events (SSE) и MQTT. Развертывание Hoppscotch на собственном VDS в Docker Compose позволяет получить полноценный командный хаб тестирования API, где все коллекции и переменные окружения зашифрованы и хранятся в вашей собственной базе данных PostgreSQL без абонентской платы и риска блокировок.

1. Архитектурный реверс-инжиниринг: как устроен стек Hoppscotch

Чтобы грамотно развернуть и администрировать Hoppscotch в production, необходимо понимать его внутреннюю архитектуру. Платформа состоит из трех ключевых модулей:

• Hoppscotch Web App (Frontend): реактивное SPA-приложение на базе Vue 3 и Vite, предоставляющее интерактивный интерфейс отправки запросов, управления окружениями, генерации документации и мокирования ответов.
• Hoppscotch Backend API: серверная часть на фреймворке NestJS с Prisma ORM. Отвечает за аутентификацию пользователей, многопользовательские воркспейсы (Workspaces), управление правами, хранение истории запросов и предоставление GraphQL/REST API.
• Hoppscotch Admin Dashboard: выделенная веб-панель суперадминистратора для управления зарегистрированными пользователями, белыми списками доменов, SMTP-шлюзами и провайдерами OAuth.

Официальные разработчики предлагают два пути развертывания в Docker: запуск трех изолированных контейнеров с разделением по портам либо монолитный контейнер All-In-One (AIO). Инженеры SysKit рекомендуют именно AIO-образ с включенным Subpath Routing (ENABLE_SUBPATH_BASED_ACCESS=true). В этом режиме внутри контейнера работает оптимизированный прокси Caddy, который объединяет все сервисы под единым внешним доменом:

Такая архитектура устраняет необходимость открывать наружу три отдельных сетевых порта (3000, 3100, 3170), решает проблемы с междоменными запросами (CORS) и обеспечивает полную совместимость с официальным десктопным клиентом Hoppscotch Desktop App.

2. Подготовка инфраструктуры VDS и криптографических секретов

Для стабильной работы связки Hoppscotch и PostgreSQL подойдет виртуальный сервер с 1–2 vCPU и 1–2 ГБ оперативной памяти под управлением современной ОС (рекомендуется Ubuntu 24.04 LTS). Перед развертыванием контейнеров необходимо настроить базовую изоляцию и сгенерировать криптографические ключи.

Создадим выделенный каталог для конфигурационных файлов проекта:

sudo mkdir -p /opt/hoppscotch && cd /opt/hoppscotch

Hoppscotch требует обязательный 32-байтный ключ шифрования DATA_ENCRYPTION_KEY. Он используется алгоритмом шифрования в Prisma ORM для защиты конфиденциальных заголовков, секретов переменных окружения и токенов авторизации в таблицах базы данных. Сгенерируем ключ в шестнадцатеричном формате с помощью OpenSSL:

# Генерация 32-значного hex-ключа шифрования
openssl rand -hex 16

Убедитесь, что на сервере установлен актуальный Docker Engine с плагином Compose v2. Проверить доступность и корректность сетевых настроек хоста можно через сетевой инструмент онлайн сканер портов SysKit.

3. Боевой манифест docker-compose.yml с PostgreSQL и изоляцией ресурсов

Для развертывания сформируем два файла в каталоге /opt/hoppscotch: файл переменных окружения .env и оркестрационный манифест docker-compose.yml.

Создадим файл /opt/hoppscotch/.env. Обратите внимание: официальный загрузчик конфигураций Hoppscotch строго требует, чтобы значения переменных не оборачивались в кавычки (двойные или одинарные):

# База данных PostgreSQL
POSTGRES_USER=hoppscotch
POSTGRES_PASSWORD=SuperSecretPass_ChangeMe_982
POSTGRES_DB=hoppscotch

# URL подключения Prisma ORM (внутреннее имя сервиса hoppscotch-db)
DATABASE_URL=postgresql://hoppscotch:SuperSecretPass_ChangeMe_982@hoppscotch-db:5432/hoppscotch?connect_timeout=300

# 32-значный ключ шифрования секретов в БД (hex)
DATA_ENCRYPTION_KEY=a4f18c2d9e7b3014f52861073bca582e

# Включение единого субпутевого роутинга (Subpath Routing)
ENABLE_SUBPATH_BASED_ACCESS=true

# Базовые внешние URL сервиса (замените api-lab.example.com на ваш домен)
VITE_BASE_URL=https://api-lab.example.com
VITE_SHORTCODE_BASE_URL=https://api-lab.example.com
VITE_ADMIN_URL=https://api-lab.example.com/admin

# Эндпоинты бэкенда и сокетов для фронтенда
VITE_BACKEND_GQL_URL=https://api-lab.example.com/backend/graphql
VITE_BACKEND_WS_URL=wss://api-lab.example.com/backend/graphql
VITE_BACKEND_API_URL=https://api-lab.example.com/backend/v1

# Доверенные источники (CORS whitelist)
WHITELISTED_ORIGINS=https://api-lab.example.com,https://api-lab.example.com/admin,app://localhost_3200,app://hoppscotch

Теперь создадим файл /opt/hoppscotch/docker-compose.yml. В манифесте задействован стабильный образ PostgreSQL 16 Alpine с healthcheck-проверкой готовности сокета, а также актуальный production-образ hoppscotch/hoppscotch:2026.9.0. Для предотвращения неконтролируемого потребления оперативной памяти заданы жесткие лимиты mem_limit и cpus:

services:
  hoppscotch-db:
    image: postgres:16-alpine
    container_name: hoppscotch-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - hoppscotch_pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 10
    networks:
      - hoppscotch_internal
    mem_limit: 512m
    cpus: 1.0

  hoppscotch-aio:
    image: hoppscotch/hoppscotch:2026.9.0
    container_name: hoppscotch-aio
    restart: unless-stopped
    env_file:
      - .env
    depends_on:
      hoppscotch-db:
        condition: service_healthy
    ports:
      # Проброс внутреннего Caddy-прокси на localhost сервера
      - "127.0.0.1:3170:80"
    networks:
      - hoppscotch_internal
    mem_limit: 1024m
    cpus: 1.5

networks:
  hoppscotch_internal:
    driver: bridge

volumes:
  hoppscotch_pgdata:
    driver: local

4. Первичная инициализация схемы БД и первый запуск

Для первого запуска стека выполните команду подъема контейнеров в фоновом режиме:

docker compose up -d

Контейнер PostgreSQL автоматически инициализирует базу данных, после чего запустится сервис hoppscotch-aio. На этапе первого старта образ автоматически применяет миграции Prisma к чистой базе данных. Проверить статус запуска и отсутствие ошибок подключения к базе можно командой:

# Просмотр логов контейнера Hoppscotch
docker compose logs -f hoppscotch-aio

Если в логах появится сообщение о необходимости ручного наката миграций (Database migration not found), выполнить синхронизацию схемы таблиц можно буквально одной командой через встроенный пакетный менеджер контейнера:

# Ручной накат миграций Prisma ORM при необходимости
docker compose exec hoppscotch-aio pnpm exec prisma migrate deploy

Убедиться, что порт 3170 успешно слушает локальные входящие соединения на сервере, можно с помощью команды curl -I http://127.0.0.1:3170. Сервис должен вернуть ответ со статусом HTTP 200.

5. Настройка Nginx с поддержкой WebSocket, GraphQL и авто-SSL Let's Encrypt

Для публикации сервиса в интернет и обеспечения защищенного HTTPS-соединения настроим обратный прокси-сервер Nginx. Поскольку Hoppscotch активно использует постоянные соединения для WebSocket и Server-Sent Events (подписки GraphQL, стриминг ответов), Nginx требует специальной конфигурации директив апгрейда протокола.

Создадим базовую конфигурацию для первичного выпуска SSL-сертификата в файле /etc/nginx/sites-available/hoppscotch.conf:

server {
    listen 80;
    server_name api-lab.example.com;

    location / {
        proxy_pass http://127.0.0.1:3170;
        proxy_http_version 1.1;
        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;
    }
}

Активируем сайт символической ссылкой, проверим синтаксис и перезагрузим веб-сервер:

sudo ln -s /etc/nginx/sites-available/hoppscotch.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Теперь выпустим бесплатный SSL-сертификат Let's Encrypt с автоматической настройкой HTTPS-перенаправления с помощью утилиты Certbot:

# Выпуск сертификата с автоматическим редиректом на HTTPS
sudo certbot --nginx -d api-lab.example.com --redirect --non-interactive --agree-tos -m admin@example.com

После успешного получения сертификата Certbot автоматически добавит SSL-директивы. Дополним блок server параметрами проксирования веб-сокетов, увеличенными таймаутами и поддержкой передачи объемных тел запросов (JSON/файлов до 64 МБ). Итоговый production-конфиг Nginx должен выглядеть следующим образом:

server {
    listen 80;
    server_name api-lab.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name api-lab.example.com;

    ssl_certificate /etc/letsencrypt/live/api-lab.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api-lab.example.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    # Максимальный размер загружаемых данных в запросах
    client_max_body_size 64M;

    location / {
        proxy_pass http://127.0.0.1:3170;
        proxy_http_version 1.1;

        # Поддержка WebSocket и Server-Sent Events (SSE)
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        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;

        # Таймауты для длительных стримов и сокетов
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
        proxy_buffering off;
    }
}

Примените обновленную конфигурацию командой sudo nginx -t && sudo systemctl reload nginx. Проверить валидность цепочки сертификатов и корректность редиректов можно через утилиты платформы: онлайн проверка SSL-сертификата и диагностика редиректов 301/302. А если вы используете веб-сервер Caddy вместо Nginx, воспользуйтесь готовым pSEO-конфигуратором Caddy с авто-SSL.

6. Системные требования к VDS и выбор конфигурации

Платформа Hoppscotch написана на оптимизированном стеке (Node.js, Vue 3, Caddy, Go), поэтому в сравнении с тяжелыми решениями (Postman Enterprise, Insomnia Cloud) потребляет минимум ресурсов сервера. Однако для комфортной работы команды разработчиков с объемными коллекциями и частыми запусками автоматических тестов важно учесть несколько факторов:

• Оперативная память (RAM): монолитный контейнер AIO стабильно укладывается в 300–450 МБ RAM в рабочем режиме. База данных PostgreSQL 16 для хранения коллекций потребляет около 100–150 МБ. Таким образом, сервера с 1 ГБ RAM достаточно для личного использования или команды из 2–4 разработчиков. Для команд от 5 человек рекомендуется выбирать тариф с 2 ГБ RAM.
• Процессор (vCPU): при выполнении параллельных коллекций тестов через CLI-раннер нагрузка на CPU кратковременно возрастает. Для комфортного отклика веб-интерфейса достаточно 1–2 ядер с современной тактовой частотой от 3.0 ГГц.
• Дисковая подсистема (NVMe): PostgreSQL активно сохраняет историю запросов, логи окружений и мок-серверы. Высокоскоростной NVMe-накопитель гарантирует мгновенный поиск по тысячам сохраненных эндпоинтов.

7. Панель администратора: настройка авторизации, командных воркспейсов и прав

После завершения настройки веб-сервера откройте в браузере адрес панели управления администратора: https://api-lab.example.com/admin. При первом переходе система предложит зарегистрировать учетную запись первичного суперадминистратора.

Hoppscotch поддерживает гибкие механизмы аутентификации:

• Email Magic Links (через SMTP): отправка одноразовых ссылок для входа на корпоративную почту без необходимости хранить и запоминать пароли.
• Корпоративный OAuth / SSO: бесшовная интеграция с GitHub, Google, Microsoft Azure AD, GitLab или собственным провайдером авторизации OIDC (например, Authelia или Authentik).
• Ограничение регистрации по домену: в настройках панели администратора (вкладка Configurations) можно задать белый список разрешенных почтовых доменов (например, разрешить вход только сотрудникам с почтой @company.ru), что предотвращает регистрацию посторонних пользователей в открытом интернете.

Переменные окружения (Environments) позволяют легко переключаться между тестовым контуром, предпродом и продакшеном. Все значения, помеченные как Secret, шифруются с использованием ключа DATA_ENCRYPTION_KEY и не отображаются в открытом виде даже при совместной демонстрации экрана.

8. Автоматизация в CI/CD: запуск коллекций тестов через Hoppscotch CLI

Главная сила Hoppscotch для DevOps-инженеров — возможность полностью автоматизировать регрессионное тестирование API в пайплайнах сборки без использования коммерческих облаков. Прямым аналогом Postman Newman выступает официальный CLI-раннер @hoppscotch/cli.

Утилита запускается на любом сборочном сервере или runner-агенте с поддержкой Node.js 18+:

# Глобальная установка CLI-раннера через npm
sudo npm install -g @hoppscotch/cli

# Проверка установленной версии
hopp --version

Внутри запросов Hoppscotch поддерживает мощные скрипты пост-обработки (Tests) на стандартном JavaScript. Синтаксис проверок интуитивно понятен:

// Проверка статус-кода ответа
hopp.expect(hopp.response.status).toBe(200);

// Проверка структуры JSON и времени отклика
const data = hopp.response.body;
hopp.expect(data.success).toBe(true);
hopp.expect(hopp.response.duration).toBeLessThan(500);

// Сохранение полученного JWT-токена в переменную окружения для следующих запросов
if (data.token) {
    hopp.env.set("AUTH_TOKEN", data.token);
}

Для запуска коллекции в автоматическом контуре CI/CD сгенерируйте Personal Access Token (PAT) в профиле пользователя Hoppscotch, после чего выполните команду прогона:

# Запуск тестов коллекции напрямую из собственного self-hosted инстанса
hopp test <COLLECTION_ID> \
  --token "hop_pat_your_secret_access_token" \
  --server "https://api-lab.example.com" \
  -e <ENVIRONMENT_ID> \
  --delay 100

CLI также умеет работать с локальными JSON-файлами коллекций, экспортированными из Hoppscotch или Postman (поддерживается нативный импорт Postman Collection v2.1):

# Запуск тестов из локального файла коллекции
hopp test ./my_api_collection.json -e ./staging_env.json

При обнаружении сбоев или непройденных ассертов команда завершается с ненулевым кодом выхода (exit code 1), что автоматически останавливает деплой некорректного релиза в GitHub Actions или GitLab CI.

9. Резервное копирование PostgreSQL и стратегия обновления

Все ценные данные инстанса (коллекции запросов, токены окружений, воркспейсы, история и учетные записи) хранятся в реляционной базе данных PostgreSQL. Потеря тома hoppscotch_pgdata приведет к безвозвратной утрате всех инженерных наработок команды. Настроим автоматическое горячее резервное копирование.

Дамп базы данных создается в сжатом виде без остановки сервиса с помощью стандартной утилиты pg_dump, запущенной внутри контейнера:

# Создание сжатого дампа базы данных PostgreSQL
docker compose -f /opt/hoppscotch/docker-compose.yml exec -T hoppscotch-db \
  pg_dump -U hoppscotch -d hoppscotch | gzip > /opt/hoppscotch/backups/hoppscotch_$(date +%Y%m%d_%H%M%S).sql.gz

Для автоматизации создадим простой скрипт резервного копирования с ротацией архивов старше 14 дней в файле /opt/hoppscotch/backup.sh:

#!/usr/bin/env bash
set -eo pipefail

BACKUP_DIR="/opt/hoppscotch/backups"
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
BACKUP_FILE="${BACKUP_DIR}/hoppscotch_${TIMESTAMP}.sql.gz"

mkdir -p "${BACKUP_DIR}"

# Снятие дампа
docker compose -f /opt/hoppscotch/docker-compose.yml exec -T hoppscotch-db \
  pg_dump -U hoppscotch -d hoppscotch | gzip > "${BACKUP_FILE}"

# Удаление бэкапов старше 14 дней
find "${BACKUP_DIR}" -type f -name "*.sql.gz" -mtime +14 -delete

echo "[$(date)] Резервная копия ${BACKUP_FILE} успешно создана."

Сделайте скрипт исполняемым командой chmod +x /opt/hoppscotch/backup.sh и добавьте его в системный планировщик crontab -e для ежедневного выполнения в 03:00 ночи: 0 3 * * * /opt/hoppscotch/backup.sh >> /var/log/hoppscotch_backup.log 2>&1. Для безопасного шифрования и выгрузки бэкапов в объектное S3-хранилище ознакомьтесь с готовым конфигуратором бэкапа PostgreSQL в S3.

Обновление сервиса до новых стабильных версий выполняется по стандартной процедуре с минимальным даунтаймом (менее 15 секунд):

cd /opt/hoppscotch
# Загрузка актуальных образов
docker compose pull
# Перезапуск стека с обновленными слоями
docker compose up -d

10. Траблшутинг частых неполадок и чек-лист готовности к production

В процессе эксплуатации self-hosted инстанса Hoppscotch системные администраторы могут столкнуться с тремя типовыми проблемами:

• Ошибка CORS или «Network Error» при отправке запросов: поскольку веб-клиент Hoppscotch выполняется непосредственно в браузере пользователя, браузер подчиняется стандартным политикам безопасности Same-Origin Policy (SOP). Если тестируемый API не отдает заголовок Access-Control-Allow-Origin, запрос будет заблокирован. Для обхода установите официальное расширение Hoppscotch Browser Extension в Chrome/Firefox либо включите встроенный прокси-сервис (Interceptor > Proxy) в настройках интерфейса.
• Ошибка 502 Bad Gateway в Nginx: свидетельствует о том, что контейнер hoppscotch-aio не успел подняться или аварийно завершил работу. Проверьте статус контейнеров через docker compose ps и изучите логи docker compose logs hoppscotch-aio. Чаще всего причина кроется в недоступности PostgreSQL или нехватке памяти (срабатывание OOM Killer на слабых VDS с объемом RAM менее 1 ГБ).
• Обрыв WebSocket или ошибки GraphQL Subscription: убедитесь, что в конфигурации Nginx присутствуют директивы proxy_set_header Upgrade $http_upgrade; и proxy_set_header Connection "upgrade";, а переменная VITE_BACKEND_WS_URL в файле .env начинается строго с протокола wss://.