Установка

Скачать

Скачайте последнюю версию на странице загрузки:

Система	Файл
macOS (Apple Silicon и Intel)	.dmg: перетащите Joppa в «Программы»
Linux x86_64	.AppImage (портативный, его нужно сделать исполняемым: chmod +x joppa-*-amd64.AppImage) или .deb (Debian, Ubuntu: sudo apt install ./joppa-*-amd64.deb)
Arch Linux x86_64	Пакет joppa-bin, собираемый makepkg (в пустой папке): curl -LO https://download.getjoppa.com/latest/PKGBUILD && makepkg -si. Для обновления выполните команду снова

Первый запуск на macOS

Joppa пока не подписан Apple, поэтому macOS блокирует его первое открытие. Это ожидаемо, и спрашивается только один раз.

Быстрее всего через терминал: после того как Joppa перетащен в «Программы», эта команда снимает блокировку, и дальше Joppa открывается как обычно.

xattr -dr com.apple.quarantine /Applications/Joppa.app

Предпочитаете интерфейс?

1. Откройте Joppa из «Программ». macOS покажет сообщение о том, что «Joppa» не открыт: нажмите Готово, а не Переместить в Корзину.
2. Откройте Системные настройки › Конфиденциальность и безопасность и прокрутите до раздела Безопасность.
3. Напротив сообщения о том, что «Joppa» заблокирован для защиты вашего Mac, нажмите Всё равно открыть.
4. Подтвердите кнопкой Всё равно открыть, затем паролем или Touch ID.

На странице загрузки эти шаги показаны на картинках.

При первом запуске Joppa создаёт свою папку конфигурации и свой центр сертификации и запускает HTTPS-прокси. Ещё он в фоне устанавливает Vite+ с Node LTS и bun для JavaScript-проектов (см. Версии Node, bun и PHP). Дальше он живёт в строке меню: закрытие окна его не останавливает. На новом Mac git поставляется вместе с инструментами командной строки Apple: кнопка Установить git в окне Новый проект устанавливает их (см. Новый проект из шаблона).

Одобрить сертификат

Joppa подписывает сертификат для каждого домена своим локальным центром сертификации (CA). Чтобы браузер показывал замок, ваша система должна доверять этому центру. Это делается один раз, с вашим паролем.

Joppa не спрашивает об этом при запуске. Пока это не сделано, запуск проекта, добавление проекта или домена и открытие https-адреса показывают окно Сначала настройте HTTPS со списком того, чего не хватает (центр сертификации и разрешение .test, см. ниже). Нажмите Настроить: система запросит ваш пароль, по одному разу для каждого пункта, и действие продолжится. Отмена отменяет его. Баннер вверху окна также предлагает Одобрить; Позже скрывает его до следующего запуска. Ячейка CA … не доверенный в строке состояния открывает ту же кнопку одним щелчком, а в Настройки › Центр сертификации остаётся кнопка Одобрить центр сертификации.

На macOS кнопка добавляет CA в связку ключей вашей учётной записи с вашими собственными настройками доверия (их читают Safari и Chrome); команда ниже добавляет его в системную связку ключей.

Предпочитаете терминал? В Настройках также показана точная команда для вашего компьютера с кнопкой копирования.

macOS

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain \
  "$HOME/Library/Application Support/joppa/ca/rootCA.pem"

Joppa сам проверяет доверие: строка состояния переходит в CA Joppa в порядке, как только всё сделано.

Linux

Кнопка Одобрить выбирает нужную папку для вашего дистрибутива. Вручную:

Debian, Ubuntu:

sudo cp ~/.config/joppa/ca/rootCA.pem /usr/local/share/ca-certificates/joppa-rootCA.crt
sudo update-ca-certificates

Arch, Manjaro:

sudo cp ~/.config/joppa/ca/rootCA.pem /etc/ca-certificates/trust-source/anchors/joppa-rootCA.crt
sudo update-ca-trust

Fedora:

sudo cp ~/.config/joppa/ca/rootCA.pem /etc/pki/ca-trust/source/anchors/joppa-rootCA.crt
sudo update-ca-trust

Порты 80 и 443

Прокси слушает 127.0.0.1, порты 443 (HTTPS) и 80 (перенаправление на HTTPS). Он принимает только подключения с вашего компьютера.

• macOS: ничего делать не нужно.
• Linux: для портов ниже 1024 нужно особое право. Если Joppa не может их открыть, он покажет команду, которую нужно выполнить:

sudo setcap cap_net_bind_service=+ep /путь/к/joppa

Если порт уже занят другим сервером (Lerd, Laravel Herd, Valet, Apache, DDEV, контейнер…), красный баннер называет его и предлагает корректно его остановить: см. Порты 80 и 443 заняты. Если недоступен только порт 80, прокси всё равно работает; просто отключается перенаправление HTTP → HTTPS.

Разрешение доменов .test

Браузер должен знать, что myproject.test — это ваш компьютер. Joppa берёт это на себя: в нём встроен небольшой DNS-сервер, который отвечает 127.0.0.1 (и ::1) на все имена в .test, на 127.0.0.1:15353, и только на них. Остаётся лишь сказать системе отправлять ему эти имена — с помощью одного файла, который устанавливается один раз с вашим паролем.

Joppa не спрашивает об этом при запуске: пока .test не разрешается, перед запуском проекта, добавлением проекта или домена и открытием адреса показывается окно Сначала настройте HTTPS, и Настроить устанавливает этот файл (сразу после CA, если не хватает и его). Об этом также напоминает баннер (Настроить), ячейка .test не разрешается в строке состояния открывает ту же кнопку, а в Настройки › Разрешение .test она остаётся.

Система	Файл, который пишет Joppa
macOS	/etc/resolver/test: nameserver 127.0.0.1 и port 15353
Linux с systemd-resolved (Ubuntu, Fedora…)	/etc/systemd/resolved.conf.d/joppa.conf: DNS=127.0.0.1:15353 и домен маршрутизации ~test
Linux с NetworkManager и dnsmasq	/etc/NetworkManager/dnsmasq.d/joppa.conf: server=/test/127.0.0.1#15353

Затем Joppa сбрасывает DNS-кеш системы (или перезагружает systemd-resolved / NetworkManager). Через него проходят только имена в .test: остальной DNS не затрагивается.

Предпочитаете терминал? Настройки › Разрешение .test показывают точные команды для вашего компьютера с кнопкой копирования. На macOS:

sudo mkdir -p /etc/resolver
printf '# Joppa\nnameserver 127.0.0.1\nport 15353\n' | sudo tee /etc/resolver/test
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

В Linux без systemd-resolved и без NetworkManager с dnsmasq Joppa не может настроить резолвер: добавьте каждый домен в /etc/hosts (127.0.0.1 myproject.test).

Среда выполнения контейнеров (необязательно)

Доменам и HTTPS больше ничего не нужно. Для сервисов (PostgreSQL, Redis, Mailpit…) установите одну из этих сред выполнения: OrbStack, Docker Desktop, Colima или Podman. См. Среды выполнения контейнеров.

Проверка

Строка состояния внизу окна показывает всё сразу:

joppa   прокси :443   CA Joppa в порядке   .test ок   2/2 домена в сети   1/1 сервис

Можно переходить к первым шагам.

Обновление

Joppa проверяет наличие новой версии при запуске, каждый раз, когда вы снова открываете его окно, а затем каждые шесть часов, и скачивает её в фоне. Тогда внизу боковой панели появляется зелёная карточка: «Joppa x.y.z готов». Нажмите Обновить сейчас: Joppa установит новую версию и перезапустится.

Каждая загрузка проверяется подписью Joppa, прежде чем заменить приложение. Чтобы самим выбирать момент загрузки, выключите Скачивать новые версии автоматически в Настройки › Обновления: тогда карточка предложит Скачать и установить. Кнопка Проверить обновления там же проверяет сразу.

В Linux AppImage обновляется так же. Установка из .deb или пакета Arch не может заменить сама себя: карточка открывает страницу загрузки. В Arch снова выполните curl -LO https://download.getjoppa.com/latest/PKGBUILD && makepkg -si в той же папке.

Удаление

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

• Из приложения: Настройки › Удаление › Удалить Joppa…, отметьте, что удалить, затем Удалить и выйти.
• Из терминала:

joppa uninstall --dry-run   # что будет удалено
joppa uninstall             # запрашивает подтверждение

Удаляются: команда joppa, MCP-сервер ассистентов, блоки PHP и Node в профиле оболочки, контейнеры сервисов, доверие к CA и файл разрешения .test (с вашим паролем), лицензия (место этого Mac освобождается), папка Joppa и само приложение. Данные сервисов (базы данных, письма) удаляются, только если вы их отметите, или с --volumes. Подробнее: Файлы › Удалить всё и Команда joppa › Удаление.