Installation

Télécharger

Récupérez la dernière version sur la page de téléchargement :

Système	Fichier
macOS (Apple Silicon et Intel)	.dmg : glissez Joppa dans Applications
Linux x86_64	.AppImage (portable, à rendre exécutable : chmod +x joppa-*-amd64.AppImage) ou .deb (Debian, Ubuntu : sudo apt install ./joppa-*-amd64.deb)
Arch Linux x86_64	Le paquet joppa-bin, construit par makepkg (dans un dossier vide) : curl -LO https://download.getjoppa.com/latest/PKGBUILD && makepkg -si. Relancez-la pour mettre à jour

Premier lancement sur macOS

Joppa n’est pas encore signé par Apple : macOS bloque donc sa première ouverture. C’est attendu, et il ne le demande qu’une fois.

1. Ouvrez Joppa depuis Applications. macOS affiche « « Joppa » n’a pas été ouvert » : cliquez sur Terminé, pas sur Placer dans la corbeille.
2. Ouvrez Réglages Système › Confidentialité et sécurité et descendez jusqu’à Sécurité.
3. En face de « « Joppa » a été bloqué pour protéger votre Mac », cliquez sur Ouvrir quand même.
4. Confirmez avec Ouvrir quand même, puis votre mot de passe ou Touch ID.

La page de téléchargement montre ces étapes en images.

Au premier lancement, Joppa crée son dossier de configuration, son autorité de certification et démarre le proxy HTTPS. Il installe aussi Vite+ avec Node LTS et bun, en arrière-plan, pour les projets JavaScript (voir Versions de Node, bun et PHP). Il vit ensuite dans la barre des menus : fermer la fenêtre ne l’arrête pas. Sur un Mac neuf, git arrive avec les outils de ligne de commande d’Apple : Installer git, dans la fenêtre Nouveau projet, les installe (voir Nouveau projet depuis un modèle).

Approuver le certificat

Joppa signe un certificat pour chaque domaine avec une autorité de certification locale (CA). Pour que le navigateur affiche le cadenas, votre système doit faire confiance à cette autorité. C’est à faire une seule fois, avec votre mot de passe.

Au premier lancement, Joppa le demande tout de suite : saisissez votre mot de passe dans la fenêtre du système. C’est tout. Si vous l’annulez, un bandeau en haut de la fenêtre le rappelle : cliquez sur Approuver. Plus tard masque le bandeau jusqu’au prochain lancement ; la case CA … non approuvée de la barre d’état ouvre le même bouton d’un clic, et Réglages › Autorité de certification garde Approuver l’autorité.

Sur macOS, le bouton ajoute la CA à votre trousseau de session, avec vos propres réglages de confiance (ceux que lisent Safari et Chrome) ; la commande ci-dessous l’ajoute au trousseau Système.

Vous préférez le terminal ? Les Réglages affichent aussi la commande exacte pour votre machine, avec un bouton pour la copier.

macOS

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

Joppa vérifie la confiance tout seul : la barre d’état passe à CA ok dès que c’est fait.

Linux

Le bouton Approuver choisit le bon dossier pour votre distribution. À la main :

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

Les ports 80 et 443

Le proxy écoute sur 127.0.0.1, port 443 (HTTPS) et 80 (redirection vers HTTPS). Il n’accepte que les connexions de votre machine.

• macOS : rien à faire.
• Linux : les ports sous 1024 demandent un droit particulier. Si Joppa ne peut pas les ouvrir, il affiche la commande à lancer :

sudo setcap cap_net_bind_service=+ep /chemin/vers/joppa

Si un autre serveur tient déjà le port (Lerd, Laravel Herd, Valet, Apache, DDEV, un conteneur…), le bandeau rouge le nomme et propose de l’arrêter proprement : voir Ports 80 et 443 occupés. Si seul le port 80 est indisponible, le proxy tourne quand même ; la redirection HTTP → HTTPS est simplement désactivée.

La résolution des domaines .test

Le navigateur doit savoir que monprojet.test désigne votre machine. Joppa s’en charge : il embarque un petit serveur DNS qui répond 127.0.0.1 (et ::1) pour tous les noms en .test, sur 127.0.0.1:15353, et seulement pour eux. Il ne reste qu’à dire au système de lui envoyer ces noms, avec un fichier, posé une fois avec votre mot de passe.

Au premier lancement, si .test ne résout pas encore, Joppa le demande tout de suite, après l’approbation du certificat : saisissez votre mot de passe dans la fenêtre du système. Si vous annulez, un bandeau le rappelle (Configurer), la case .test ne résout pas de la barre d’état ouvre le même bouton, et Réglages › Résolution .test le garde.

Système	Fichier écrit par Joppa
macOS	/etc/resolver/test : nameserver 127.0.0.1 et port 15353
Linux avec systemd-resolved (Ubuntu, Fedora…)	/etc/systemd/resolved.conf.d/joppa.conf : DNS=127.0.0.1:15353 et le domaine de routage ~test
Linux avec NetworkManager et dnsmasq	/etc/NetworkManager/dnsmasq.d/joppa.conf : server=/test/127.0.0.1#15353

Joppa vide ensuite le cache DNS du système (ou recharge systemd-resolved / NetworkManager). Seuls les noms en .test passent par lui : le reste de votre DNS n’est pas touché.

Vous préférez le terminal ? Réglages › Résolution .test affiche les commandes exactes pour votre machine, avec un bouton pour les copier. Sur 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

Sous Linux sans systemd-resolved ni NetworkManager avec dnsmasq, Joppa ne sait pas configurer le résolveur : ajoutez chaque domaine à /etc/hosts (127.0.0.1 monprojet.test).

Un runtime de conteneurs (facultatif)

Les domaines et le HTTPS n’ont besoin de rien d’autre. Pour les services (PostgreSQL, Redis, Mailpit…), installez l’un de ces runtimes : OrbStack, Docker Desktop, Colima ou Podman. Voir Runtimes de conteneurs.

Vérifier

La barre d’état en bas de la fenêtre résume tout :

joppa   proxy :443   CA joppa ok   .test ok   2/2 domaines en ligne   1/1 service

Vous pouvez passer aux premiers pas.

Mettre à jour

Joppa cherche une nouvelle version au lancement, chaque fois que vous rouvrez sa fenêtre, puis toutes les six heures, et la télécharge en arrière-plan. Une carte verte apparaît alors en bas de la barre latérale : « Joppa x.y.z est prêt ». Cliquez sur Mettre à jour : Joppa installe la nouvelle version et redémarre.

Chaque téléchargement est vérifié avec la signature de Joppa avant de remplacer l’app. Pour choisir le moment du téléchargement, désactivez Télécharger automatiquement les nouvelles versions dans Réglages › Mises à jour : la carte propose alors Télécharger et installer. Rechercher les mises à jour, au même endroit, vérifie tout de suite.

Sous Linux, l’AppImage se met à jour de la même façon. Une installation depuis le .deb ou le paquet Arch ne peut pas se remplacer elle-même : la carte ouvre la page de téléchargement. Sur Arch, relancez curl -LO https://download.getjoppa.com/latest/PKGBUILD && makepkg -si dans le même dossier.

Désinstaller

Joppa se désinstalle depuis l’app ou depuis le terminal ; dans les deux cas, vous choisissez ce qui part, et vos projets ne sont pas touchés.

• Depuis l’app : Réglages › Désinstaller › Désinstaller Joppa…, cochez ce qui part, puis Désinstaller et quitter.
• Depuis le terminal :

joppa uninstall --dry-run   # ce qui partirait
joppa uninstall             # demande confirmation

Sont retirés : la commande joppa, le serveur MCP des assistants, les blocs PHP et Node du profil du shell, les conteneurs des services, l’approbation de la CA et le fichier de résolution .test (votre mot de passe), la licence (le poste de ce Mac est libéré), le dossier de Joppa et l’app elle-même. Les données des services (bases, mails) ne partent que si vous les cochez, ou avec --volumes. Le détail : Fichiers et dossiers › Tout retirer et La commande joppa › Désinstaller.