Установка

Обновлено 2026-07-22

Эта инструкция рассчитана на то, что вы никогда раньше не разворачивали Docker-приложения и не администрировали Linux-сервер. Все команды даны в готовом для копирования виде.

Что понадобится

Linux-сервер (VPS/выделенный сервер) — подойдёт Ubuntu 22.04/24.04 или Debian 12. Требования к CPU/RAM/диску — в таблице ниже.
Docker и Docker Compose — единственная зависимость. Больше ничего (ни PHP, ни nginx, ни базы данных) устанавливать вручную не нужно — всё это уже упаковано в контейнеры.
Доступ к серверу по SSH.
(Не обязательно, но желательно для реальной эксплуатации) доменное имя, указывающее на IP сервера.

Системные требования

Gotcha поднимает на одном сервере три процесса: само приложение (Go), PostgreSQL и ClickHouse. Основной потребитель памяти и диска — ClickHouse, в котором хранится телеметрия (события, трейсы, метрики, профили), поэтому и требования определяются в первую очередь им.

	Минимум	Рекомендуется
CPU	2 vCPU	4 vCPU
RAM	2 ГБ	4 ГБ и больше
Диск	20 ГБ SSD	40 ГБ SSD и больше

ОС: Ubuntu 22.04/24.04 или Debian 12, архитектура x86-64 (amd64).
RAM. 2 ГБ — рабочий минимум для запуска и небольшой нагрузки (личные проекты, стейджинг). Для продакшена с реальным потоком событий закладывайте от 4 ГБ: под нагрузкой ClickHouse тем стабильнее, чем больше ему доступно памяти.
Диск. Растёт вместе с объёмом телеметрии и сроком её хранения (retention). 20 ГБ хватает, чтобы стартовать; при заметном трафике или длинном retention планируйте больше и следите за свободным местом. Диск обязательно SSD — и ClickHouse, и PostgreSQL чувствительны к его латентности.
CPU. Двух ядер достаточно; дополнительные ядра ускоряют приём всплесков событий и запросы ClickHouse.
Сеть. Наружу нужен только один порт приложения (по умолчанию 59080). PostgreSQL и ClickHouse наружу не выставляются — они доступны лишь внутри docker-сети.

Шаг 1. Проверьте, установлен ли Docker

Подключитесь к серверу по SSH и выполните:

docker --version
docker compose version

Если обе команды напечатали номер версии — Docker уже есть, переходите к шагу 2.

Если вы видите command not found, установите Docker официальным скриптом (работает на Ubuntu/Debian):

curl -fsSL https://get.docker.com | sudo sh

После установки добавьте своего пользователя в группу docker, чтобы не набирать sudo перед каждой командой, и перезайдите по SSH, чтобы это применилось:

sudo usermod -aG docker $USER
exit

Зайдите на сервер заново и повторите docker --version — должно сработать. Docker Compose (команда docker compose, с пробелом) устанавливается вместе с Docker этим скриптом, отдельно ставить не нужно.

Шаг 2. Скачайте код Gotcha

Если на сервере нет git — поставьте его (sudo apt update && sudo apt install -y git для Ubuntu/Debian). Дальше:

# gitflic (основной, анонимный HTTPS)
git clone https://gitflic.ru/project/otezvikentiy/gotcha.git
# GitHub (зеркало)
git clone https://github.com/OtezVikentiy/gotcha.git
# Контрибьюторы с SSH-доступом могут использовать:
# git clone git@gitflic.ru:otezvikentiy/gotcha.git
cd gotcha

В этой папке лежит docker-compose.yml — файл-рецепт, который описывает, какие три контейнера нужно поднять и как их связать между собой. Все дальнейшие команды выполняются из этой папки (gotcha/).

Шаг 3. Запустите контейнеры

docker compose up -d

Что произойдёт:

Docker соберёт образ приложения Gotcha (компилирует Go-программу в контейнере — при первом запуске это может занять пару минут).
Поднимутся три контейнера:
- gotcha — само приложение: HTTP-сервер, веб-интерфейс, приём событий от SDK, миграции схемы БД при старте.
- postgres (PostgreSQL 17) — хранит «обычные» данные: пользователей, организации, проекты, правила алертов, инциденты.
- clickhouse (ClickHouse 25.3) — хранит большие объёмы телеметрии: сами события об ошибках, трейсы, метрики, профили, результаты аптайм-проверок.
Флаг -d («detached») означает «запустить в фоне и вернуть терминал» — контейнеры продолжат работать после того, как вы закроете SSH-сессию.

Postgres и ClickHouse наружу (на хост-машину) не выставлены — до них можно достучаться только изнутри docker-сети, между контейнерами. Наружу торчит только порт приложения.

Проверьте статус:

docker compose ps

Все три строки должны показывать Up (у postgres и clickhouse — Up (healthy), у gotcha может уйти на подъём до минуты первый раз, пока применяются миграции).

Шаг 4. Проверьте, что всё поднялось

Приложение слушает порт 59080 на хосте по умолчанию (см. docker-compose.yml: "${GOTCHA_PORT:-59080}:8080" — это порт хоста слева, порт контейнера справа; выбран нестандартный 59080, чтобы не конфликтовать с другими сервисами на сервере). Проверьте health-эндпойнт:

curl -sf http://localhost:59080/healthz

Ответ вида {"clickhouse":"ok","postgres":"ok"} с HTTP-кодом 200 означает, что приложение живо и обе базы данных ему отвечают. Если curl завис или вернул ошибку — см. раздел «Устранение неполадок» ниже.

Готовые обёртки есть в Makefile, если вы предпочитаете make:

make up       # docker compose up -d
make ps       # docker compose ps
make health   # curl /healthz
make logs     # docker compose logs -f gotcha (Ctrl+C для выхода)

Откройте в браузере http://<IP-адрес-вашего-сервера>:59080 (или http://localhost:59080, если открываете с самого сервера/через SSH-туннель) — должна открыться страница входа Gotcha.

Шаг 5. Создайте первого пользователя

Откройте http://<адрес-сервера>:59080/register и зарегистрируйтесь.

Важно: первый пользователь на чистом инстансе регистрируется всегда, независимо от режима самостоятельной регистрации (GOTCHA_REGISTRATION), и автоматически получает права инстанс-администратора. Это «bootstrap» — так вы получаете первого админа на свежей установке без ручных манипуляций с базой. Все последующие регистрации уже подчиняются GOTCHA_REGISTRATION (подробнее — Конфигурация).

После входа: создайте организацию, затем проект внутри неё. На странице проекта «Подключение» (URL вида /projects/<id>/setup, также доступна кнопкой «Подключение SDK» в списке проектов) будет DSN — адрес, на который направляется SDK вашего приложения (Sentry SDK любого языка работает с Gotcha без изменений, так как используется тот же протокол приёма). Подробный разбор — Первые шаги и SDK и интеграции.

Шаг 6. Задайте секретный ключ (обязательно для реального сервера)

По умолчанию Gotcha использует GOTCHA_SECRET_KEY=insecure-dev-secret. Значение публично — оно лежит прямо в исходном коде на GitFlic, его знает кто угодно. Этим ключом подписываются сессионные cookie и OAuth state-cookie; если оставить дефолт на сервере, доступном по интернету, злоумышленник, знающий этот ключ, может подделать cookie и увести чужой аккаунт через OAuth-вход (account takeover).

Поэтому: если ваш GOTCHA_BASE_URL не localhost/127.0.0.1 (то есть у вас настоящий сервер, а не локальная разработка), приложение откажется стартовать в режимах web/all, пока вы не зададите свой ключ.

Сгенерируйте случайный ключ:

openssl rand -base64 32

Создайте (или отредактируйте) файл .env рядом с docker-compose.yml — Docker Compose читает его автоматически:

nano .env

и впишите (замените значение на то, что вывела команда выше):

GOTCHA_SECRET_KEY=вставьте-сюда-случайную-строку-из-openssl

Примените изменение (пересоздаёт контейнер gotcha с новой переменной окружения):

docker compose up -d

Шаг 7. Укажите публичный адрес (`GOTCHA_BASE_URL`)

GOTCHA_BASE_URL — это адрес, по которому пользователи и SDK на самом деле обращаются к вашему инстансу. Из него строятся: DSN проектов (то, что вы вставляете в код приложений), ссылки в письмах-приглашениях, ссылки на инциденты в алертах (Telegram/webhook/email). Если значение не совпадает с реальным адресом — ссылки будут вести не туда.

Допишите в тот же .env:

GOTCHA_BASE_URL=https://gotcha.example.com

(или http://<IP-сервера>:59080, если пока без домена и без HTTPS — но см. чек-лист ниже, почему HTTPS важен). Примените:

docker compose up -d

Минимальный чек-лист для продакшена

Прежде чем давать доступ реальным пользователям/направлять на инстанс реальный трафик приложений, убедитесь:

GOTCHA_SECRET_KEY — задан свой случайный ключ (шаг 6), не дефолтный.
GOTCHA_BASE_URL — указывает на реальный публичный адрес.
HTTPS — Gotcha сам TLS не терминирует, поставьте перед ним reverse-proxy:
- nginx: конфиг с proxy_pass http://127.0.0.1:59080; и сертификатом от Let’s Encrypt (certbot --nginx).
- Caddy: ещё проще, HTTPS настраивается автоматически — в Caddyfile достаточно строки gotcha.example.com { reverse_proxy localhost:59080 }.
Без HTTPS сессионные cookie идут по сети открытым текстом — сервер даже предупредит об этом в логах (GOTCHA_BASE_URL is non-local plain HTTP).
SMTP — без него не работают письма-приглашения и email-канал алертов. Настройка — в Конфигурации.
Резервное копирование — настройте до того, как в базе появятся важные данные. См. Резервное копирование и восстановление.
Квоты — если DSN проекта может утечь публично (например, фронтенд-JS), задайте GOTCHA_DEFAULT_*_QUOTA (по умолчанию в oss-редакции — безлимит). См. Конфигурацию.

Устранение неполадок

Контейнеры не стартуют / падают. Посмотрите логи:

docker compose logs -f gotcha
docker compose logs -f postgres
docker compose logs -f clickhouse

Частая причина — сообщение об ошибке конфигурации (например, требование задать GOTCHA_SECRET_KEY, см. шаг 6) прямо в логе gotcha.

Порт уже занят (bind: address already in use). На сервере что-то уже слушает 59080. Задайте другой порт хоста через .env:

GOTCHA_PORT=8081

и docker compose up -d. Приложение внутри контейнера по-прежнему слушает 8080 — меняется только то, на какой порт хоста он «пробрасывается».

Не открывается веб-интерфейс, хотя контейнеры Up.

Проверьте firewall на сервере: sudo ufw status — при включённом ufw разрешите порт: sudo ufw allow 59080/tcp.
Если сервер у облачного провайдера/хостинга — проверьте Security Group / файрвол в панели управления хостингом отдельно от ufw (часто трафик режется именно там).
Проверьте curl -sf http://localhost:59080/healthz с самого сервера — если это работает, а снаружи нет, проблема сетевая (firewall/провайдер), а не в Gotcha.

/healthz отвечает 503 со статусом unavailable у postgres/clickhouse. Значит приложение живо, но не может достучаться до одной из баз. Обычно это означает, что база ещё не поднялась (первый запуск ClickHouse может занимать до минуты) — подождите и повторите. Если не проходит долго — смотрите docker compose logs postgres / docker compose logs clickhouse.

Что дальше

Конфигурация — полный список переменных окружения.
Резервное копирование и восстановление.
Обновление.
Первые шаги — создание проекта и первое событие.
SSO — вход через OIDC/Yandex ID/VK ID.