Документация

Три раздела: поставить приложение, подключить первый сервер, разобраться, если что-то пошло не так.

Установка приложения

Приложение работает на вашей машине — Windows, macOS или Linux. Оно не сервис и не облако: серверы клиентов оно держит в списке у вас на диске, а ключи и пароли — в хранилище секретов операционной системы.

Скачайте установщик со страницы загрузки.
Запустите его. Установщики пока не подписаны сертификатом разработчика, поэтому Windows покажет предупреждение SmartScreen, а macOS — Gatekeeper. Что нажимать, написано на странице загрузки.
Откройте приложение. Добавить сервер и проверить его готовность можно сразу, без регистрации.
Ставьте стек. Аккаунт для этого не нужен: установочный бандл раздаётся всем, лимита по числу серверов и сайтов не существует ни на каком тарифе, и всё бесплатное работает анонимно.
Аккаунт понадобится только для функций, которые физически не могут работать без нашей инфраструктуры, — сегодня это внешний аптайм-мониторинг и проверка доменов по чёрным спискам. Зарегистрироваться можно на сайте или прямо в приложении, а после регистрации подтвердить адрес по ссылке из письма: пока он не подтверждён, платные функции закрыты — нам некуда сообщить вам о беде с сервером.

Подключение сервера

Что нужно от сервера

VPS с Linux на systemd — проверялось на Debian и Ubuntu.
Доступ по SSH: пользователь root либо пользователь с sudo без пароля. Установка идёт без участия человека и на запросе пароля просто повиснет.
Один свободный порт — какой именно, выберет установка. Занятые 80 и 443 не помеха: мы их не отбираем, а встаём рядом с существующим веб-сервером клиента. Порт берётся из списка, совместимого с проксированием Cloudflare, и записывается в трекинг-код.
Около 2 ГБ свободного места и 1 ГБ памяти. Docker поставит сам установщик, если его нет.
Домен или поддомен для панели аналитики. Если 80 и 443 свободны, достаточно A-записи, указывающей на этот сервер. Если заняты, сертификат выпускается через DNS-01: понадобится либо API-доступ к вашему DNS (Cloudflare, Route 53, DigitalOcean), либо одна запись CNAME на наш запасной ответчик — приложение подскажет, какую.

Порядок действий

Добавьте сервер. Адрес, порт, пользователь и способ входа: приватный ключ (ed25519, RSA, ECDSA в формате OpenSSH, можно с парольной фразой) или пароль. Ключи в формате PuTTY .ppk не поддерживаются — сконвертируйте его в PuTTYgen через Conversions → Export OpenSSH key.
Проверьте связь. Это отдельная кнопка: приложение ничего не записывает на диск, пока вы не убедились, что доступ есть. При первом подключении оно запомнит отпечаток ключа сервера и дальше будет его сверять.
Запустите проверку готовности (dry-run). Она собирает факты о сервере — версия системы, свободное место, занятые порты, наличие Docker, работает ли sudo без пароля — и не оставляет на сервере ни одного файла. Скрипт уходит на стандартный ввод, а не во временный файл, именно поэтому.
Разберите отчёт. Блокирующие пункты придётся исправить: sudo с паролем, мёртвый демон Docker, нехватка места. Занятые 80 и 443 в этот список не входят — установка встанет на другой порт. Предупреждения — на ваше усмотрение.
Поставьте стек. Укажите домен и, если нужно, разрешите открыть выбранный порт в файрволе — это единственное изменение за пределами нашего каталога и Docker, и откат его снимает. Приложение сгенерирует пароли (Postgres, ключ подписи сессий и пароль администратора панели аналитики), положит их в хранилище секретов вашей ОС и развернёт на сервере три контейнера: Umami, Postgres и Caddy. Прогресс идёт по шагам в реальном времени.

Начните с некритичного сайта. Мы ставим свой софт на чужой прод. Изоляция полная — своя сеть Docker, свои тома, существующий веб-сервер не трогается, — но первый прогон разумнее делать там, где цена ошибки ниже.

Если связь оборвётся посреди установки, она всё равно дойдёт до конца на сервере: SSH без псевдотерминала не шлёт процессу сигналов. Приложение узнает, чем всё кончилось, когда вы вернётесь на экран сервера. А если установка упадёт, откат вернёт сервер в исходное состояние — включая снос Docker, если ставили его мы.

Сайты и аналитика

Нажмите «Найти сайты», если на сервере уже работает чужой веб-сервер: приложение прочитает его конфигурацию и покажет домены, которые он обслуживает. Только прочитает — ни байта в чужие конфиги, ни перезапуска, и установка от найденного не зависит. Список остаётся у вас: к нам ничего из него не уходит.
Добавьте сайт на сервере: домен и название. Лимита по числу сайтов нет ни на каком тарифе, а домен остаётся у вас: к нам он уезжает только тогда, когда вы подключаете сайт к платной функции.
Скопируйте трекинг-код и вставьте его в <head> сайта. Данные пойдут на сервер клиента, а не к нам.
Дашборд по сайту и сводка по всем серверам открываются в приложении. Панель аналитики наружу не смотрит: приложение ходит к ней через SSH-туннель, и локальный порт наружу тоже не отдаётся.
На вкладке сайта «Данные» добавьте read-only SQL-запрос к его базе — на самом сервере или в контейнере Docker по имени; MySQL, MariaDB, PostgreSQL или SQLite. Запрос идёт тем же туннелем и становится карточкой: числом, короткой фразой или небольшой таблицей, любого размера и в любом порядке. Подключению нужен пользователь только с правом SELECT — готовый GRANT покажет сам экран, а суперпользователя он не пустит вовсе. Ответ остаётся на этом экране: не сохраняется на диск и никуда не уходит, даже к нам.
На экране «Уведомления» задайте почту и, если нужно, Telegram. Письма шлёт агент с сервера клиента — в этом его смысл: он сообщает о беде, когда приложение закрыто.

Переход с другого сервиса мониторинга. Выгрузите мониторы из UptimeRobot или HetrixTools в CSV и загрузите файл на экране «Аптайм». Он читается на вашей машине: вы видите, что разобралось, отмечаете, что перенести, и к нам уезжает только отмеченное. Строки, которые мы не приняли, показываются с причиной. Ping и проверку порта мы не делаем вовсе; сигнал задачи делаем, но заводится он на экране «Задачи», а не переносом — ему нужен свой секретный адрес в вашем cron, и заведённый молча он объявил бы себя пропавшим в первую же ночь. Мониторов больше, чем даёт тариф, — обычный случай: принимаются все, по тарифу работают, остальные ждут приостановленными. Первый перенос включает Remote на 90 дней, один раз на аккаунт.

Агент следит за диском, памятью и процессором сервера, за сроками доменов и сертификатов. Тревожит только то, что само не рассосётся: кончающийся диск, истекающий сертификат, истекающий домен.

Внешние проверки и сторож задач

Они идут с нашей инфраструктуры, а не с сервера клиента, и в этом вся причина, по которой они платные: монитор, стоящий на наблюдаемой машине, умирает вместе с ней. Единица, которую считает тариф, — проверка, а не сайт: у сайта их бывает несколько — главная, /api/health, страница входа. Лимита на число сайтов и серверов нет ни на каком тарифе и не появится.

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

Страница — адрес отвечает кодом меньше четырёхсотого.
Текст — в ответе есть названная вами строка. Регистр важен: искать надо ровно так, как написано на странице.
JSON — ответ разобрался как JSON и названное поле не пусто. Значение не сравнивается: счётчик, который меняется сам по себе, поднимал бы тревогу каждый час.
Перенаправление — адрес перенаправляет, и тем кодом, которого вы ждёте. Куда именно — снаружи не проверяется: у условий Gatus нет доступа к заголовкам ответа. Цель сверяет локальная проверка агента, и на экране это сказано прямо: проверка, обещающая больше, чем делает, хуже отсутствующей.
DNS — домен разрешается в закреплённые вами адреса. Единственный профиль, которого у агента быть не может: изнутри VPS домен разрешается в себя же кем угодно. Тревога — после трёх кругов подряд: смена записи расходится по резольверам не мгновенно.

Заголовка во внешней проверке нет никогда, и это отказ, а не недоделка. Следующий шаг после «мне нужен путь и строка» — «мне нужен заголовок Authorization», и, приняв его, мы стали бы хранилищем токенов от API ваших клиентов. У локальных проверок агента заголовки есть: они живут на сервере клиента, в файле с правами 640, и токен там его собственный.

Сторож задач следит за тем, что не отвечает вовсе, — за ночным бэкапом, синхронизацией, выгрузкой. Задача отчитывается на свой секретный адрес; вы задаёте период и окно допуска, а мы пишем, когда отчёта не было. Расписание — это период плюс окно, а не cron-выражение: cron бессмысленен без часового пояса машины, на которой задача выполняется, а мы не знаем даже, что это за машина. Две беды разведены, потому что первый шаг у них разный: «сообщила об ошибке» ведёт в лог задачи, «сигнала нет» — в cron. Задача, не отчитавшаяся ни разу, тревогу поднимает: ровно этот случай сторож и ловит. Кто знает адрес, тот может слать «всё хорошо» — для мониторинга это приемлемо, но сказать об этом надо прямо.

Окно обслуживания. Перед обновлением стека откройте окно: оно гасит письмо, а не проверку. Инцидент всё равно записывается, и экран всё равно показывает правду. Беда, пережившая окно, дойдёт письмом после работ; беда, кончившаяся внутри него, — нет, потому что сообщать уже не о чем.

Почта домена

У домена сайта появляется вкладка «Почта». Она включает переадресацию почты Cloudflare Email Routing для этого домена и позволяет заводить адреса — например, support@, — пересылающие на уже существующий ящик. Это бесплатно и не требует у нас аккаунта: приложение зовёт API Cloudflare напрямую, ключом, который остаётся на этом компьютере, а почта никогда не проходит через нашу инфраструктуру — она идёт от Cloudflare прямо в выбранный ящик.

Домен должен быть делегирован на серверы имён Cloudflare, а его DNS должен обслуживать Cloudflare целиком — частичное подключение (только через CNAME) не поддерживает Email Routing. Почта принадлежит домену, а не сайту и не серверу: удаление того или другого из приложения её не касается, а shop.example.com и example.com делят одну и ту же почту, потому что делят один и тот же домен.

Как создать ключ

В приложении откройте раздел Cloudflare в настройках и нажмите «Создать ключ в Cloudflare». Откроется страница создания токена в Cloudflare с уже отмеченными правами — остаётся выбрать аккаунт и домены клиента, нажать «Создать» и вставить полученный ключ обратно в приложение. Ключ хранится только в защищённом хранилище этого компьютера: он никогда не уходит к нам и не показывается второй раз после того, как вы его вставили. Заводите отдельный аккаунт Cloudflare на каждого клиента, где это возможно, — ключ общего аккаунта видит все ящики, подключённые к нему, а не только домен, с которым вы сейчас работаете.

Включение почты на домене

Откройте вкладку «Почта» сайта. Приложение читает DNS домена и отвечает одним из трёх способов:

Можно включить. Показывает, что добавит Cloudflare; вы подтверждаете, и через минуту-две домен готов.
Сначала один шаг в Cloudflare. Обычный случай, если сайт уже отправляет письма — например, подтверждения заказов. Приложение готовит ровно ту строку, которая вливается в существующую запись SPF, не ломая её, — вы вставляете её в Cloudflare и нажимаете «Проверить».
Здесь уже работает другая почта. Google Workspace, Яндекс 360, свой почтовый сервер клиента. Приложение ничего не меняет и объясняет почему: включение увело бы почту из этих ящиков.

Заведение адреса — одна форма: имя и куда пересылать. Если на этот ящик ещё не приходила почта через данный аккаунт Cloudflare, Cloudflare пришлёт ему письмо со ссылкой подтверждения — адрес будет помечен «ждёт подтверждения», пока по ней не перейдут, а потом начнёт работать сам.

Перенос почты к другому сервису

Этот перенос приложение не делает само: Email Routing пересылает почту, а не хранит её, поэтому переносить из неё нечего. Чтобы перейти на другой сервис вручную, начните в Cloudflare с раздела Email → Email Routing → Settings: записи MX, SPF и DKIM, которые добавил Email Routing, заблокированы, и страница DNS не даст их изменить, пока вы не выключите там Email Routing для домена или не разблокируете его записи. Затем удалите оставшиеся записи Email Routing, укажите MX нового провайдера и замените в записи SPF наш include на тот, который он просит. После того как новые записи разойдутся по DNS, проверьте доставку почты на домен и с него ещё раз.

Потеряли этот компьютер? Ключ лежит только в его хранилище секретов. Отзовите его в панели Cloudflare (My Profile → API Tokens) — у приложения нет отдельного способа его выключить, а поддержка никогда не спросит у вас этот ключ: кроме Cloudflare и приложения на вашей собственной машине, он никому не нужен.

Обновления, бэкап, удаление

Обновление стека. Перед тем как что-то менять, снимается дамп базы и копия конфигов. Если обновление не заладится, вернётся и то и другое.
Бэкап. Кнопка «Выгрузить бэкап» собирает дамп Postgres и конфигурацию стека в архив и скачивает его. В архиве есть пароли — храните соответственно.
Удаление. Два разных действия. «Убрать из приложения» забывает сервер у вас. «Снести с VPS» уничтожает стек вместе со всей аналитикой клиента за всё время, и это необратимо.
Обновление приложения. Приходит само и проверяется по подписи. Неподписанное обновление приложение отвергнет.

Работа командой

Несколько человек агентства могут вести один и тот же сервер клиента каждый со своей копии приложения — без общего кабинета и без синхронизации через нашу инфраструктуру. Границей доступа служит то, чем вы и так пользуетесь: SSH.

Что для этого нужно

Каждому участнику — доступ к серверу по SSH: root либо пользователь с sudo без пароля, то же самое, что нужно для установки. У кого есть такой доступ, тот и так может прочитать на сервере пароли стека, — приложение не даёт новых прав, а только показывает то, что этому человеку уже доступно. Закрыть доступ — значит закрыть SSH, это агентство умеет и без нас.
Одна версия приложения у всей команды. Копия постарше не умеет читать состав проектов и настройки с сервера и перепишет их своими, устаревшими. Приложение замечает след такой копии и предупреждает об этом на главном экране.
Один аккаунт vpsFocus на агентство — но только если вы пользуетесь внешним аптаймом: это единственная функция, которой вообще нужен аккаунт. Установка, аналитика, сайты и почта домена работают без него у любого числа участников.

Как это устроено

Разработчик добавляет сервер в свою копию приложения обычным способом. Если стек на сервере уже стоит, приложение видит это само и забирает с сервера пароли — переустанавливать ничего не надо, и на сервере при этом ничего не меняется. Дальше он видит ровно то же самое, что и тот, кто стек ставил: аналитику, свод, проверки, логи, SEO.

Общее хранится на сервере и одинаково у всех: состав проектов, ключевые адреса, настройки уведомлений — почта, Telegram, окно обслуживания, — и пароли стека. Правка одного видна остальным при следующем открытии экрана.

Личное остаётся на компьютере каждого и по команде не расходится: лента собственных действий, подключения к базам сайтов на вкладке «Данные», ключ Cloudflare для почты домена, отметка «когда я в последний раз забирал копию».

Кто правит последним, тот и побеждает — но не везде одинаково. Списки, которые экран каждый раз заново читает у агента, — страницы замеров, пути к логам, ключевые адреса, — ведут себя ровно так: правки редки, и последняя сохранённая побеждает. Состав проектов и настройки уведомлений устроены осторожнее: правка применяется поверх того, что в момент сохранения реально лежит на сервере, а не поверх того, что было открыто у вас час назад. Если коллега успел поменять значение, которое вы не трогали, ваше сохранение его не заденет, а экран покажет, что именно осталось как было.

Кто-то уходит из команды

Закрытого SSH достаточно, чтобы человек больше не мог подключиться к серверу — через приложение или как-то иначе. Но часть настроек в конфигурации агента общая на всё агентство, а не на один сервер: пароль исходящей почты, токен Telegram-бота, ключ Google, ключи хранилища резервных копий. Уходящий уносит их в памяти, поэтому при уходе человека:

закройте ему SSH-доступ к серверам;
если у него был свой вход в аккаунт vpsFocus, смените пароль аккаунта и нажмите «выйти везде»;
смените пароль исходящей почты, токен бота, ключ Google и ключи хранилища копий — обычным сохранением настроек на любом сервере команды: новое значение само разойдётся по остальным.

Восстановление копии на другой VPS

Переезд на новый сервер — обычное восстановление копии, описанное выше, плюс перенос внешних проверок на новый сервер там, где приложение это предложит: старый и новый сервер для нас — разные серверы, даже если это один и тот же клиент.

Клонирование VPS у провайдера — не то же самое, что переезд: снимок диска переносит и служебную отметку, по которой приложение узнаёт сервер. Если два сервера окажутся под одной отметкой, приложение распознаёт это по отпечатку SSH-ключа и спросит: это переустановленный тот же сервер или отдельная копия? Единственное, что так не распознать, — облачный образ, который при клонировании не создаёт сервером новый SSH-ключ.

Частые проблемы

На сервере уже есть веб-сервер клиента

Это штатный случай, а не помеха. Мы не трогаем чужой nginx, Apache или Caddy, не переконфигурируем его и не отбираем 80 и 443: стек встаёт на свободный порт и живёт рядом. Порт записывается в трекинг-код и при обновлениях не меняется никогда — он прописан на каждом сайте клиента.

«sudo требует пароль»

Установка идёт без участия человека и на запросе пароля повиснет. Дайте пользователю право sudo без пароля или подключайтесь под root.

Сертификат не выпускается

Сначала посмотрите, каким способом он выпускается у вас.

Через A-запись (порты 80 и 443 свободны): почти всегда причина одна — запись ещё не указывает на этот сервер или не разошлась по DNS. Проверьте, что домен резолвится в адрес сервера, и повторите.
Через DNS-01 с ключом провайдера (порты заняты): проверьте, что токен даёт право править записи именно этой зоны. Учётные данные лежат на сервере клиента в .env с правами 600 и к нам не уезжают.
Через наш запасной ответчик: убедитесь, что CNAME _acme-challenge вашего домена указывает на выданное приложением имя. Пока он не разошёлся, проверка не пройдёт.

Установку это не срывает: стек к этому шагу уже работает, приложение так и говорит — «стек работает, жду сертификат», — а Caddy продолжает попытки сам. У Let's Encrypt есть ограничение на число попыток в неделю, поэтому перезапускать установку десятки раз подряд не нужно.

«Ключ сервера изменился»

Отпечаток отличается от запомненного при первом подключении. Так бывает, когда сервер пересоздали или переустановили, — и ровно так же выглядит перехваченное соединение. Не продолжайте, пока не убедитесь, какой из двух случаев ваш.

Windows показывает предупреждение при установке

Установщики пока не подписаны сертификатом разработчика. Как пройти предупреждение, написано на странице загрузки.

«Подтвердите адрес почты»

Пока адрес не подтверждён, закрыто всё, что требует нашей инфраструктуры: регистрация серверов у нас, подключение сайтов к наблюдению, платные функции. Установка к этому списку не относится — бандл раздаётся всем, и стек ставится вообще без аккаунта. Письмо можно отправить заново из личного кабинета или с экрана аккаунта в приложении.

Панель аналитики не отвечает

После перезагрузки сервера контейнерам нужно время подняться. Если не помогло — откройте экран сервера: там видно, работает ли стек, и его версию.