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

Как это работает. От репозитория до стабильного прода.

Как подготовить проект, задеплоить его, подключить базу, откатить неудачный релиз и понять, почему что-то упало.

01 / раздел

Быстрый старт

От репозитория до работающего сервиса по HTTPS — четыре шага.

  1. 01

    Зарегистрируйтесь

    Через VK ID, Яндекс ID или по почте. Оплата — в рублях российской картой.

  2. 02

    Создайте проект и выберите репозиторий

    Подключите GitHub и укажите ветку. Тип приложения и стек определим по коду.

  3. 03

    Проверьте настройки

    Покажем, что нашли: порт, команду запуска, нужную базу. Переменные окружения можно загрузить из .env.

  4. 04

    Нажмите «Задеплоить»

    Соберём, развернём и дождёмся, пока приложение ответит. Дальше — обновление на каждый git push.

Задеплоить проект

02 / раздел

Подготовка проекта

Нужен репозиторий на GitHub. Dockerfile не обязателен: популярные стеки собираем сами.

СтекКак соберём
PythonFastAPI, Django, Flask и другие — по requirements.txt или pyproject.toml.
Node.jsNext.js, Nuxt, Express, NestJS и другие — по package.json, командами build и start.
GoGin, Echo, Fiber — по go.mod.
PHP, Java, Ruby, Rust и другиеLaravel, Spring, Rails и другие — тоже автоматически. Не собралось — добавьте Dockerfile или напишите нам.
Любой стек со своим DockerfileСобираем строго по нему — полный контроль над сборкой.
Готовый Docker-образМожно развернуть без сборки: выберите «Готовый образ» при создании проекта или укажите образ, добавляя сервис.

Порт и адрес

Приложение должно слушать 0.0.0.0 и порт, указанный в настройках сервиса (его покажем на шаге проверки). Этот порт приходит в переменной PORT — проще всего читать его оттуда. Если слушать 127.0.0.1, снаружи приложение будет недоступно, и статус «работает» не поставится.

FastAPI — команда запуска
uvicorn main:app --host 0.0.0.0 --port 8000
package.json — Next.js
{
  "name": "shop-web",
  "scripts": {
    "build": "next build",
    "start": "next start -H 0.0.0.0 -p 3000"
  }
}

Проверка здоровья

Сделайте маршрут, который отвечает 200, например /health, и укажите его в настройках сервиса. Релиз считается работающим, только когда этот маршрут ответил. Без него проверяем, что открыт порт.

main.py
# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/health")
def health():
    return {"ok": True}

Свой Dockerfile

Положите Dockerfile в корень сервиса — сборка пойдёт по нему, а не автоматически.

Dockerfile — Java
FROM eclipse-temurin:21-jre
WORKDIR /app
COPY target/app.jar app.jar
EXPOSE 8080
CMD ["java", "-jar", "app.jar"]

03 / раздел

Проекты и сервисы

Проект — изолированное окружение: своя закрытая сеть, свои базы, свои сервисы. Другие проекты не видят ни его сервисы, ни базу.

Сервис — одно приложение внутри проекта: сайт, API или фоновый воркер. Сервисы одного проекта могут жить в одном репозитории (разные папки) или в разных.

Публичные и приватные сервисы

Публичный сервис получает адрес в интернете с HTTPS. Приватный — только внутреннее имя вида worker:8000: к нему могут обращаться другие сервисы проекта, но не интернет. Переключается в меню «⋯» сервиса.

Адреса соседей

Каждый сервис получает адреса остальных сервисов проекта в переменных вида ИМЯ_URL: у сервиса shop-api это SHOP_API_URL. Свою переменную с тем же именем платформа не перезапишет.

Доступ для сотрудников

В «Настройках» проекта, раздел «Доступ», создайте ссылку-приглашение и отправьте её сотруднику или клиенту. Ссылка одноразовая и действует 7 дней. Платит за проект только владелец.

РольЧто может
НаблюдательСмотрит статус, релизы и логи. Секретов не видит, ничего не меняет.
РазработчикДеплоит, откатывает, перезапускает, правит переменные и настройки, подключает домены. Новый репозиторий подключает только владелец.
АдминистраторВсё, что разработчик, плюс удаление сервисов и баз, восстановление базы и приглашение разработчиков и наблюдателей.
ВладелецВсё, включая оплату, назначение администраторов и удаление проекта.

Управление

ДействиеЧто происходит
ЗадеплоитьСобирает свежий коммит ветки и разворачивает его новой версией.
ПерезапуститьПерезапускает сервис с текущим образом и актуальными переменными, без пересборки.
ПриостановитьОстанавливает сервис. Он не оплачивается и не занимает место в лимите тарифа; релизы, переменные и диск сохраняются.
ПереименоватьМеняет имя в панели. Адрес и внутреннее имя не меняются.
УдалитьУдаляет сервис, его адрес и историю релизов. Проект и базы остаются.

04 / раздел

API и CLI — быстрый старт

Всё, что панель делает с проектами и деплоями, можно делать из терминала и CI: командой prichal или HTTP-запросами. Полный список запросов с параметрами и примерами ответов — справочник API.

  1. 01

    Выпустите токен

    «Настройки → Интеграции → API-токены». Для CI — право «деплой и настройки», один проект, срок 90 дней. Токен показываем один раз: сразу положите его в менеджер паролей или в секреты CI.

  2. 02

    Установите CLI

    Один файл на Python 3.9+ без зависимостей и без sudo — в ~/.local/bin.

  3. 03

    Задеплойте

    prichal deploy проект сервис --wait собирает свежий коммит ветки, выкатывает и ждёт исхода.

  4. 04

    Подключите CI

    Деплой на каждый push после зелёных тестов — готовый workflow для GitHub Actions ниже.

Установка CLI

Терминал: macOS или Linux
mkdir -p ~/.local/bin
curl -fsSL https://prichal.tech/cli/prichal.py -o ~/.local/bin/prichal
chmod +x ~/.local/bin/prichal
prichal --version

Если в ответ command not found — каталог ~/.local/bin не в PATH. Добавьте его один раз:

Терминал
# macOS (zsh); в Linux с bash — ~/.bashrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
exec $SHELL

На Windows скачайте prichal.py по той же ссылке и запускайте через Python: python prichal.py projects. Раз в сутки CLI проверяет, не вышла ли новая версия, и пишет об этом в терминал; в CI (есть переменная CI) и при PRICHAL_NO_UPDATE_CHECK=1проверки нет. Обновление — та же команда curl.

Первый деплой

Терминал
prichal login                      # вставьте токен pat_…
prichal projects                   # id, имя, статус последнего деплоя
prichal services shop              # сервисы проекта shop
prichal deploy shop api --wait     # собрать, выкатить и дождаться исхода
prichal logs shop api --tail 200

Проект и сервис указываются именем или числовым id. Вместо prichal login можно задать переменнуюPRICHAL_TOKEN — так токен передают в CI. С --wait команда завершается с кодом 1, если сборка или запуск не удались или миграции ждут подтверждения в панели, — шаг CI упадёт вместе с деплоем.

Другие команды
prichal deploy shop                # все сервисы проекта
prichal env pull shop api > .env   # переменные в формате .env
prichal env set shop api SENTRY_DSN=https://…
prichal rollback shop api          # на прошлый здоровый релиз
prichal rollback shop api --to 41  # на конкретный релиз

Деплой из GitHub Actions

Положите файл в .github/workflows/ своего репозитория, добавьте секрет PRICHAL_TOKEN в «Settings → Secrets and variables → Actions» и замените shop и api на свои имена.

Выключите у сервиса «Автообновление» (сервис → «Настройки»). Иначе каждый push деплоится дважды: сразу самим Prichal и ещё раз этим workflow после тестов.
.github/workflows/prichal-deploy.yml
# Деплой в Prichal после зелёных тестов, на каждый push в main.
# Положите файл в .github/workflows/prichal-deploy.yml своего репозитория.
#
# 1. Prichal: «Настройки → Интеграции → API-токены» — токен с правом записи,
#    ограниченный этим проектом.
# 2. GitHub: Settings → Secrets and variables → Actions → New repository secret,
#    имя PRICHAL_TOKEN, значение — токен.
# 3. Prichal: сервис → «Настройки» → выключите «Автообновление». Иначе push
#    задеплоит дважды: сам Prichal сразу и этот workflow после тестов.
#
# Замените shop и api на имена своего проекта и сервиса (`prichal services shop`).
name: Деплой в Prichal

on:
  push:
    branches: [main]

# Два push подряд не деплоят наперегонки: второй ждёт первый.
concurrency:
  group: prichal-deploy
  cancel-in-progress: false

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # Здесь ваши тесты, например:
      # - run: pip install -r requirements.txt && pytest
      - run: echo "тесты прошли"

  deploy:
    needs: test
    runs-on: ubuntu-latest
    timeout-minutes: 35
    env:
      PRICHAL_TOKEN: ${{ secrets.PRICHAL_TOKEN }}
    steps:
      - name: Установить CLI
        run: curl -fsSL https://prichal.tech/cli/prichal.py -o prichal && chmod +x prichal
      # --wait: шаг упадёт, если сборка или запуск не удались.
      - name: Деплой
        run: ./prichal deploy shop api --wait

Без CLI

CLI — тонкая обёртка над HTTP. Любой запрос из справочника можно отправить сам, с токеном в заголовке Authorization: Bearer pat_…:

Терминал
curl -X POST -H "Authorization: Bearer $PRICHAL_TOKEN" \
  https://prichal.tech/api/projects/12/services/34/deploy

05 / раздел

Безопасность токена

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

НастройкаЧто даёт
Права«Только чтение» — только просмотр (GET): статусы, логи, релизы. «Деплой и настройки» — ещё деплой, переменные, откат. Для дашбордов и мониторинга хватает чтения.
ПроектТокен одного проекта не видит остальные: для него их нет (ответ 404), в списках их нет. Для CI конкретного репозитория — всегда так.
Срок30 дней, 90 дней, год или бессрочно. Истёкший токен получает 401 — CI упадёт с понятной ошибкой, выпустите новый.
ОтзывКнопка «Отозвать» в «Настройки → Интеграции» действует со следующего запроса. В списке видно, когда токен использовали в последний раз, — так заметно и забытые, и чужие.

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

Мы храним только хеш токена — показать его повторно нельзя, потерянный придётся перевыпустить. Не кладите токен в репозиторий и в prichal.json: только в секреты CI или в prichal login (файл~/.config/prichal/config.json с доступом только для вас). Утёк — сразу отзовите и выпустите новый.

06 / раздел

prichal.json — проект в репозитории

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

prichal.json
{
  "services": [
    {
      "name": "web",
      "port": 8000,
      "size": "standard",
      "healthcheck": "/healthz",
      "migrate": "alembic upgrade head",
      "disk": { "gb": 5, "path": "/data" },
      "env": { "LOG_LEVEL": "info" },
      "cron": [{ "name": "cleanup", "schedule": "@daily", "command": "python cleanup.py" }]
    },
    { "name": "worker", "path": "worker", "public": false }
  ],
  "databases": [{ "type": "postgresql", "size": "db-micro", "storage_gb": 5 }]
}

Секретов в файле быть не должно — он лежит в git. В env — только несекретные значения; ключи с «secret», «token», «password» платформа отклонит. Ошибку в файле покажем на шаге подтверждения, а сервисы определим как без него.

07 / раздел

Переменные окружения

Переменные хранятся зашифрованными и передаются только вашему приложению. В панели значения скрыты, пока вы не нажмёте «показать»; из логов секреты вырезаются перед показом.

Изменения применяются при следующем развёртывании или перезапуске — панель покажет, какие сервисы нужно перезапустить.

Что подставляет платформа

ПеременнаяКогда
DATABASE_URLК проекту подключён PostgreSQL.
REDIS_URLПодключён Redis.
AMQP_URLПодключён RabbitMQ.
ИМЯ_URLАдреса других сервисов проекта.
PYTHONUNBUFFERED=1Python-сервисы: чтобы логи появлялись сразу.

Общие переменные и ссылки

В настройках проекта есть общие переменные: они уходят во все сервисы, а переменная с тем же именем в сервисе важнее общей. Значение может ссылаться на другую переменную: ${{shared.SENTRY_DSN}} — общую, ${{api.TOKEN}} — переменную сервиса api, ${{api.URL}} — его внутренний адрес (есть ещё HOST, PORT, PUBLIC_URL). Ссылку без значения панель покажет при сохранении. Имя shared занято общими переменными: на сервис с таким именем сослаться нельзя.

Откат возвращает переменные самого сервиса. Общие переменные и значения по ссылкам остаются текущими.

Копия проекта для staging

В настройках проекта есть «Сделать копию»: новый проект с теми же сервисами, размерами и настройками, при желании — на другой ветке. Базы в копии пустые и со своими паролями, данные и диски не копируются, задачи по расписанию и свои домены — тоже. Переменные копируются только по галочке, токен бота — никогда.

08 / раздел

Базы данных и бэкапы

К проекту можно подключить PostgreSQL, Redis, RabbitMQ и Kafka. База доступна только сервисам этого проекта — адреса в интернете у неё нет. Размер базы и диска меняется на её странице.

Подключение из Python
import os
import psycopg

# DATABASE_URL подставляет платформа, когда к проекту подключён PostgreSQL.
conn = psycopg.connect(os.environ["DATABASE_URL"])

Бэкапы

Дампы PostgreSQL снимаются каждый час и хранятся у другого провайдера — не там же, где база. Почасовые копии живут двое суток, по одной копии в день — 30 дней. Каждый день платформа поднимает свежую копию во временной базе и проверяет, что она восстанавливается. Журнал проверок — когда, за сколько секунд, сколько таблиц и строк вернулось — виден на странице базы.

Бэкап, который никто не восстанавливал, — надежда, а не бэкап. Поэтому зелёная отметка ставится только после проверки восстановлением.

Диск сервиса архивируется раз в сутки и хранится 30 дней; архив можно скачать на обзоре сервиса. Это копия файлов работающего приложения: база SQLite, в которую в этот момент шла запись, может оказаться несогласованной.

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

09 / раздел

Релизы и откат

Каждое развёртывание — версия: v1, v2, … Все они видны на ленте версий над вкладками сервиса. Текущая версия в проде подсвечена зелёным.

Откат

Кнопка «Откатить» возвращает прошлую версию целиком — код, переменные и размер — без пересборки, обычно быстрее 30 секунд. Откат не стирает историю: он создаёт новую версию, а на ленте видно, к какой вернулись.

Автооткат

Включается в настройках сервиса. Если новый релиз не стал здоровым за указанное время (по умолчанию 5 минут), платформа сама вернёт предыдущий здоровый. Причина пишется в журнал.

10 / раздел

Миграции базы

Укажите команду миграций в настройках сервиса, например alembic upgrade head. Она выполняется отдельным шагом до развёртывания, из нового образа. Перед ней снимается снапшот базы.

По умолчанию миграции ждут вашего подтверждения — сборка готова, но прод не трогается, пока вы не нажмёте «Применить».

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

11 / раздел

Задачи по расписанию

На вкладке «Расписание» сервиса задаются команды, которые платформа запускает сама: очистка, выгрузки, рассылки. Расписание — в формате cron (0 3 * * * — каждый день в 3:00) по московскому времени.

Задача выполняется в контейнере сервиса через sh -c — тем же образом и с теми же переменными, что и текущий релиз. Откатили сервис — задачи тоже идут из отката. Диск сервиса задаче не подключается.

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

12 / раздел

Наблюдение и уведомления

Статус «работает» означает, что приложение отвечает на проверку здоровья, а не что контейнер запущен. После деплоя платформа продолжает следить за каждым сервисом раз в минуту.

Что случилосьЧто делает платформа
Приложение упалоПерезапускает его автоматически.
Приложение зависло: работает, но не отвечаетЕсли молчит дольше трёх минут и это не медленный старт — перезапускает сервис. Не чаще раза в час.
Не отвечает дольше полутора минутПрисылает уведомление в панель и в Telegram — один раз на падение.
Снова отвечаетПрисылает «снова отвечает».
Сертификат не продлилсяПредупреждает за 14, 7, 3 и 1 день до истечения.

Уведомления в Telegram

  1. 01

    Откройте «Настройки → Профиль»

    В панели Prichal.

  2. 02

    Нажмите «Привязать Telegram»

    Откроется наш бот уведомлений.

  3. 03

    Отправьте боту /start

    Аккаунт привяжется автоматически; в панели появится отметка.

13 / раздел

Сеть и HTTPS

Публичный сервис получает адрес на домене платформы. HTTPS-сертификат выдаётся при развёртывании и продлевается сам; его состояние видно во вкладке «Сеть» сервиса.

Собственный домен

Во вкладке «Сеть» сервиса нажмите «Подключить домен» и добавьте у регистратора одну из записей, которые покажет панель:

ДоменЗапись
Поддомен (www.shop.ru, app.shop.ru)CNAME на уникальное имя вида d1a2b3….prichal.tech — своё для каждого домена.
Корень домена (shop.ru)A на IP платформы и TXT _prichal.shop.ru с кодом подтверждения.

DNS проверяется раз в минуту; как только записи появятся, домен подтвердится сам и получит HTTPS-сертификат. До 5 доменов на сервис и до 20 на аккаунт. Домен, не подтверждённый за 7 дней, освобождается.

Одной A-записи для подтверждения мало: домен, который уже смотрит на наш адрес, иначе мог бы «занять» любой клиент платформы. TXT-код или уникальный CNAME доказывают, что DNS правите именно вы.

Исходящие соединения и почта

Из приложения открыты соединения в интернет на порты 80, 443 и SMTP 465/587. Письма отправляйте через внешний SMTP-провайдер (Яндекс, Mail.ru, Unisender, SendPulse) на порт 465 или 587. Порт 25 закрыт: прямая отправка на почтовые серверы получателей недоступна.

14 / раздел

Частые ошибки

Причину падения платформа показывает человеческим языком вместе с последними строками лога. Самые частые:

Что видноПричинаЧто делать
Не отвечает на портПриложение слушает 127.0.0.1 или другой порт.Слушайте 0.0.0.0 и порт из настроек сервиса.
Не хватило памяти (OOMKilled)Приложению тесно в текущем размере.Увеличьте размер в один клик в меню «⋯».
ModuleNotFoundErrorЗависимость не указана в requirements.txt / package.json.Добавьте её и сделайте push.
Падает при стартеНет нужной переменной окружения или неверная команда запуска.Проверьте переменные и команду во вкладке «Настройки».
Сборка не прошлаСтек не распознан или ошибка в сборке.Откройте лог сборки; при необходимости добавьте Dockerfile.

Не получилось разобраться — напишите нам, поможем.