joppa.toml

joppa.toml в корне проекта описывает всё, что нужно проекту в Joppa: его домены, сервисы и базу данных, версии, что Joppa делает с его worktree и его процессы. Закоммитьте его: коллега, который клонирует репозиторий и добавит его в Joppa, получит всё готовым в один клик, после того как подтвердит, что Joppa собирается сделать.

Все разделы необязательны. Файл, в котором есть только [[process]] (как в первых версиях Joppa), остаётся допустимым.

Как его записать

На странице проекта: меню Действия (⋯) › Поделиться конфигурацией в joppa.toml или одноимённая ссылка под списком процессов. Joppa показывает файл в том виде, в каком он будет записан (а если он уже существует, — что изменится), затем Записать joppa.toml сохраняет его в корне репозитория. Joppa записывает туда:

• имя проекта;
• его домены — метками под этим именем (домен, который не находится под именем проекта, пропускается, и Joppa об этом сообщает);
• связанные сервисы с их версией, базой данных и расширениями этой базы;
• что Joppa делает с worktree, если это настроено;
• процессы.

Раздел [runtime] и разделы, которых эта версия Joppa не знает, сохраняются как есть. Файл можно написать и вручную.

Флажок Записать joppa.toml в репозиторий для команды в анализе процессов записывает только [[process]]: остальные разделы файла не меняются.

Пример

[project]
name = "acme"

# app.acme.test → процесс web; acme.test → порт 49100
[[domain]]
label = "app"
process = "web"

[[domain]]
label = ""
port = 49100

[[service]]
engine = "postgres"
version = "17"
extensions = ["postgis", "vector"]
database = "acme"
env = { DATABASE_URL = "url", DATABASE_APP_URL = "role:acme_app" }
setup = "pnpm run db:reset"

[[service]]
engine = "redis"
env = false

[runtime]
node = "22"
packageManager = "[email protected]"

[worktrees]
auto = true
database = "empty"

[[process]]
name = "postgres"
kind = "compose"
service = "db"

[[process]]
name = "api"
kind = "script"
dir = "apps/api"
command = "pnpm run dev"
port = 8000
dependsOn = ["postgres"]
probe = "/health"
healthcheck = "/health"

[process.env]
PORT = "8000"

[[process.actions]]
name = "migrate"
command = "pnpm run db:migrate"

[[process.actions]]
name = "test"
command = "pnpm test"

[[process]]
name = "web"
kind = "script"
dir = "apps/web"
command = "pnpm run dev"
port = 48100
dependsOn = ["api"]

[[process]]
name = "worker"
kind = "script"
command = "bun run queue"
enabled = false

[[service]]

Каждый [[service]] — это сервис Joppa, который использует проект: один сервер на движок на компьютере и одна база данных на проект.

Поле	Тип	Назначение
engine	строка	postgres, mysql, mariadb, redis, valkey, mailpit, typesense, meilisearch или reverb
version	строка	Нужная основная версия ("17"), используется, если Joppa создаёт сервер
extensions	список	Расширения PostgreSQL для базы данных
database	строка	Имя базы данных (по умолчанию — имя проекта)
env	логическое значение или таблица	Что Joppa записывает в .env (см. ниже). По умолчанию true
setup	строка	Команда, которая выполняется в папке проекта сразу после создания базы данных (см. ниже)

env: переменные .env

• env = true (по умолчанию): Joppa записывает переменные, которые проект уже использует (в .env или .env.example), или переменные его фреймворка.
• env = false: проект связан с сервисом, но .env не трогается.
• env = { … }: Joppa записывает ровно эти переменные, каждую с запрошенным значением. Полезно, когда у проекта несколько URL для одного сервера, например один для администратора и один для роли приложения:

[[service]]
engine = "postgres"
env = { DATABASE_URL = "url", DATABASE_APP_URL = "role:acme_app" }

Значение	Что записывает Joppa
url (или admin)	URL подключения с учётной записью сервера: postgresql://postgres:…@127.0.0.1:5432/acme. Для Redis — redis://127.0.0.1:6379
role:ИМЯ	Тот же URL с учётной записью ИМЯ (PostgreSQL, MySQL, MariaDB). Пароль, уже записанный для этой учётной записи в .env (или .env.example), сохраняется; иначе пароля нет
role:ИМЯ:ПАРОЛЬ	Тот же URL с этой учётной записью и этим паролем
db:N	Redis, Valkey: URL базы номер N (redis://127.0.0.1:6379/1)
host, port, database, user, password	Только одна часть: 127.0.0.1, 5432, acme…

Схема и параметры уже существующего URL сохраняются (postgres://…?schema=app). Joppa не создаёт роль: это задача setup.

setup: подготовка новой базы данных

[[service]]
engine = "postgres"
setup = "bun run db:reset"

Когда план создаёт базу данных (или сервер, для движка без баз), он добавляет шаг Выполнить «bun run db:reset» в папке проекта после записи .env: здесь проект создаёт свои роли, схему и данные. Как и любой шаг, его отмечаете вы; снимите флажок, чтобы ничего не запускать. Пока команда работает, её вывод показывается под шагом, и окно остаётся на нём до нажатия Закрыть. Если команда завершится с ошибкой, Joppa сообщит об этом и покажет её последние строки.

Уже существующая база данных никогда не готовится повторно: setup выполняется только один раз, при её создании.

[project]

Каждый [[process]] — это процесс.

Поле	Тип	Назначение
name	строка	Уникальное имя в проекте: web, api, postgres
kind	"script" или "compose"	Команда или сервис из Docker Compose проекта
port	число	Порт, на котором он отвечает, когда готов. Отсутствует у фоновой задачи
dependsOn	список	Процессы, которые запускаются (и становятся готовыми) до этого
enabled	логическое значение	Запускается по «Запустить всё» (по умолчанию true). При false запускается только отдельно
probe	строка	Сервер разработки: как Joppa узнаёт, что он готов. HTTP-путь ("/health"; по умолчанию /) или "tcp". См. Когда процесс готов
healthcheck	строка	Сервер разработки: путь, который Joppa запрашивает, пока он работает ("/api/health"). Процесс доступен, только если ответ 2xx; иначе он неисправен, с указанием кода. Требует port. См. Healthcheck
actions	список	Разовые команды, которые предлагаются рядом с процессом: [[process.actions]] с name и command. См. Действия

kind = "script"

Поле	Назначение
command	Команда, запускаемая в оболочке
dir	Папка относительно корня проекта (пусто — корень)
env	Добавляемые переменные окружения ([process.env])

kind = "compose"

Поле	Назначение
service	Имя сервиса в файле Docker Compose

Если файл существует, его процессы имеют приоритет над локальной конфигурацией.

Применение файла

Joppa никогда не применяет joppa.toml без вас. Сначала он показывает план, шаг за шагом, который вы подтверждаете:

• При добавлении проекта: окно Добавить проект берёт имя из файла, затем первый шаг анализа показывает его план: домены, создание или повторное использование сервера, создание базы данных с расширениями, связывание проекта, запись .env, закрепление версий, настройка worktree. Применить и продолжить выполняет отмеченные шаги.
• После git pull, который изменил файл: на странице проекта появляется «joppa.toml изменился» с тем, что изменилось с момента последнего применения на этом компьютере. Просмотреть открывает план; Применить выполняет отмеченные шаги; Игнорировать эту версию оставляет всё как есть до следующего изменения.

План:

• ничего не уничтожает: существующая база данных используется повторно, расширения только добавляются, .env записывается с diff (и копией старого), домен, уже занятый другим проектом, не трогается;
• соблюдает лицензию: движок, доступный только в Joppa Pro, не создаётся в версии Free, и шаг об этом сообщает;
• запускает setup сервиса только для базы данных, которую он только что создал, и только если шаг отмечен;
• не запускает ни одного процесса: процессы из joppa.toml, пришедшего с git pull, сохраняют своё одобрение (см. ниже).

Каждый шаг проверяется в момент применения: если файл или .env за это время изменились, шаг не выполняется, и Joppa просит открыть план заново.

Процессы из изменившегося файла

joppa.toml приходит с git pull: его команды могли измениться. Запускать при открытии Joppa запускает только те команды, которые этот компьютер уже запускал или сохранял; после изменения процессы ждут, пока вы один раз запустите их вручную.

Чего в нём нет

Запускать при открытии Joppa, Перезапускать после сбоя и Усыплять через … без запросов — это настройки каждого компьютера: они остаются в Joppa и никогда не записываются в joppa.toml.