Документация
Как это работает. От репозитория до стабильного прода.
Как подготовить проект, задеплоить его, подключить базу, откатить неудачный релиз и понять, почему что-то упало.
01 / раздел
Быстрый старт
От репозитория до работающего сервиса по HTTPS — четыре шага.
- 01
Зарегистрируйтесь
Через VK ID, Яндекс ID или по почте. Оплата — в рублях российской картой.
- 02
Создайте проект и выберите репозиторий
Подключите GitHub и укажите ветку. Тип приложения и стек определим по коду.
- 03
Проверьте настройки
Покажем, что нашли: порт, команду запуска, нужную базу. Переменные окружения можно загрузить из .env.
- 04
Нажмите «Задеплоить»
Соберём, развернём и дождёмся, пока приложение ответит. Дальше — обновление на каждый git push.
02 / раздел
Подготовка проекта
Нужен репозиторий на GitHub. Dockerfile не обязателен: популярные стеки собираем сами.
| Стек | Как соберём |
|---|---|
| Python | FastAPI, Django, Flask и другие — по requirements.txt или pyproject.toml. |
| Node.js | Next.js, Nuxt, Express, NestJS и другие — по package.json, командами build и start. |
| Go | Gin, Echo, Fiber — по go.mod. |
| PHP, Java, Ruby, Rust и другие | Laravel, Spring, Rails и другие — тоже автоматически. Не собралось — добавьте Dockerfile или напишите нам. |
| Любой стек со своим Dockerfile | Собираем строго по нему — полный контроль над сборкой. |
| Готовый Docker-образ | Можно развернуть без сборки: выберите «Готовый образ» при создании проекта или укажите образ, добавляя сервис. |
Порт и адрес
Приложение должно слушать 0.0.0.0 и порт, указанный в настройках сервиса (его покажем на шаге проверки). Этот порт приходит в переменной PORT — проще всего читать его оттуда. Если слушать 127.0.0.1, снаружи приложение будет недоступно, и статус «работает» не поставится.
uvicorn main:app --host 0.0.0.0 --port 8000{
"name": "shop-web",
"scripts": {
"build": "next build",
"start": "next start -H 0.0.0.0 -p 3000"
}
}Проверка здоровья
Сделайте маршрут, который отвечает 200, например /health, и укажите его в настройках сервиса. Релиз считается работающим, только когда этот маршрут ответил. Без него проверяем, что открыт порт.
# main.py
from fastapi import FastAPI
app = FastAPI()
@app.get("/health")
def health():
return {"ok": True}Свой Dockerfile
Положите Dockerfile в корень сервиса — сборка пойдёт по нему, а не автоматически.
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.
- 01
Выпустите токен
«Настройки → Интеграции → API-токены». Для CI — право «деплой и настройки», один проект, срок 90 дней. Токен показываем один раз: сразу положите его в менеджер паролей или в секреты CI.
- 02
Установите CLI
Один файл на Python 3.9+ без зависимостей и без sudo — в
~/.local/bin. - 03
Задеплойте
prichal deploy проект сервис --waitсобирает свежий коммит ветки, выкатывает и ждёт исхода. - 04
Подключите CI
Деплой на каждый push после зелёных тестов — готовый workflow для GitHub Actions ниже.
Установка CLI
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 на свои имена.
# Деплой в 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/deploy05 / раздел
Безопасность токена
Токен — ключ к вашим проектам без пароля и второго фактора. Выдавайте каждому месту свой токен с минимальными правами — тогда утечка одного не задевает остальное, а отзыв не ломает соседние пайплайны.
| Настройка | Что даёт |
|---|---|
| Права | «Только чтение» — только просмотр (GET): статусы, логи, релизы. «Деплой и настройки» — ещё деплой, переменные, откат. Для дашбордов и мониторинга хватает чтения. |
| Проект | Токен одного проекта не видит остальные: для него их нет (ответ 404), в списках их нет. Для CI конкретного репозитория — всегда так. |
| Срок | 30 дней, 90 дней, год или бессрочно. Истёкший токен получает 401 — CI упадёт с понятной ошибкой, выпустите новый. |
| Отзыв | Кнопка «Отозвать» в «Настройки → Интеграции» действует со следующего запроса. В списке видно, когда токен использовали в последний раз, — так заметно и забытые, и чужие. |
Чего токен не может никогда, даже у администратора: менять пароль и email, выпускать токены, платить, заходить в админку. Права токена не шире ваших: если вас понизили в проекте до наблюдателя, токен тоже станет только читать.
Мы храним только хеш токена — показать его повторно нельзя, потерянный придётся перевыпустить. Не кладите токен в репозиторий и в prichal.json: только в секреты CI или в prichal login (файл~/.config/prichal/config.json с доступом только для вас). Утёк — сразу отзовите и выпустите новый.
06 / раздел
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=1 | Python-сервисы: чтобы логи появлялись сразу. |
Общие переменные и ссылки
В настройках проекта есть общие переменные: они уходят во все сервисы, а переменная с тем же именем в сервисе важнее общей. Значение может ссылаться на другую переменную: ${{shared.SENTRY_DSN}} — общую, ${{api.TOKEN}} — переменную сервиса api, ${{api.URL}} — его внутренний адрес (есть ещё HOST, PORT, PUBLIC_URL). Ссылку без значения панель покажет при сохранении. Имя shared занято общими переменными: на сервис с таким именем сослаться нельзя.
Откат возвращает переменные самого сервиса. Общие переменные и значения по ссылкам остаются текущими.
Копия проекта для staging
В настройках проекта есть «Сделать копию»: новый проект с теми же сервисами, размерами и настройками, при желании — на другой ветке. Базы в копии пустые и со своими паролями, данные и диски не копируются, задачи по расписанию и свои домены — тоже. Переменные копируются только по галочке, токен бота — никогда.
08 / раздел
Базы данных и бэкапы
К проекту можно подключить PostgreSQL, Redis, RabbitMQ и Kafka. База доступна только сервисам этого проекта — адреса в интернете у неё нет. Размер базы и диска меняется на её странице.
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 — тем же образом и с теми же переменными, что и текущий релиз. Откатили сервис — задачи тоже идут из отката. Диск сервиса задаче не подключается.
12 / раздел
Наблюдение и уведомления
Статус «работает» означает, что приложение отвечает на проверку здоровья, а не что контейнер запущен. После деплоя платформа продолжает следить за каждым сервисом раз в минуту.
| Что случилось | Что делает платформа |
|---|---|
| Приложение упало | Перезапускает его автоматически. |
| Приложение зависло: работает, но не отвечает | Если молчит дольше трёх минут и это не медленный старт — перезапускает сервис. Не чаще раза в час. |
| Не отвечает дольше полутора минут | Присылает уведомление в панель и в Telegram — один раз на падение. |
| Снова отвечает | Присылает «снова отвечает». |
| Сертификат не продлился | Предупреждает за 14, 7, 3 и 1 день до истечения. |
Уведомления в Telegram
- 01
Откройте «Настройки → Профиль»
В панели Prichal.
- 02
Нажмите «Привязать Telegram»
Откроется наш бот уведомлений.
- 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 дней, освобождается.
Исходящие соединения и почта
Из приложения открыты соединения в интернет на порты 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. |
Не получилось разобраться — напишите нам, поможем.