Instalación

Descargar

Descarga la última versión desde la página de descarga:

Sistema	Archivo
macOS (Apple Silicon e Intel)	.dmg: arrastra Joppa a Aplicaciones
Linux x86_64	.AppImage (portable, hazlo ejecutable: chmod +x joppa-*-amd64.AppImage) o .deb (Debian, Ubuntu: sudo apt install ./joppa-*-amd64.deb)
Arch Linux x86_64	El paquete joppa-bin, construido por makepkg (en una carpeta vacía): curl -LO https://download.getjoppa.com/latest/PKGBUILD && makepkg -si. Vuelve a ejecutarlo para actualizar

Primera apertura en macOS

Joppa todavía no está firmado por Apple, así que macOS bloquea la primera apertura. Es normal, y solo lo pide una vez.

1. Abre Joppa desde Aplicaciones. macOS indica «No se ha abierto “Joppa”»: cierra el mensaje, sin elegir Trasladar a la papelera.
2. Abre Ajustes del Sistema › Privacidad y seguridad y baja hasta Seguridad.
3. Junto a «Se ha bloqueado “Joppa” para proteger tu Mac», haz clic en Abrir igualmente.
4. Confirma con Abrir igualmente y tu contraseña o Touch ID.

La página de descarga muestra estos pasos con imágenes.

En el primer arranque, Joppa crea su carpeta de configuración y su autoridad de certificación, e inicia el proxy HTTPS. También instala Vite+ con Node LTS y bun, en segundo plano, para los proyectos JavaScript (consulta Versiones de Node, bun y PHP). Después vive en la barra de menús: cerrar la ventana no lo detiene. En un Mac nuevo, git llega con las herramientas de línea de comandos de Apple: Instalar git, en la ventana Nuevo proyecto, las instala (consulta Nuevo proyecto desde una plantilla).

Aprobar el certificado

Joppa firma un certificado para cada dominio con una autoridad de certificación local (CA). Para que el navegador muestre el candado, tu sistema debe confiar en esta autoridad. Solo hay que hacerlo una vez, con tu contraseña.

En el primer arranque, Joppa la pide enseguida: escribe tu contraseña en la ventana del sistema. Eso es todo. Si la cancelas, un aviso en la parte superior de la ventana te lo recuerda: haz clic en Aprobar. Más tarde oculta el aviso hasta el próximo arranque; la casilla CA … no aprobada de la barra de estado abre el mismo botón con un clic, y Ajustes › Autoridad de certificación conserva Aprobar la autoridad.

En macOS, el botón añade la CA a tu llavero de sesión, con tus propios ajustes de confianza (los que leen Safari y Chrome); el comando de abajo la añade al llavero Sistema.

¿Prefieres el terminal? Los Ajustes también muestran el comando exacto para tu equipo, con un botón para copiarlo.

macOS

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

Joppa comprueba la confianza por sí mismo: la barra de estado pasa a CA ok en cuanto está hecho.

Linux

El botón Aprobar elige la carpeta correcta para tu distribución. A mano:

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

Los puertos 80 y 443

El proxy escucha en 127.0.0.1, puerto 443 (HTTPS) y 80 (redirección a HTTPS). Solo acepta conexiones de tu equipo.

• macOS: no hay que hacer nada.
• Linux: los puertos por debajo de 1024 requieren un permiso especial. Si Joppa no puede abrirlos, muestra el comando que debes ejecutar:

sudo setcap cap_net_bind_service=+ep /ruta/a/joppa

Si otro servidor ya ocupa el puerto (Lerd, Laravel Herd, Valet, Apache, DDEV, un contenedor…), el aviso rojo lo nombra y propone detenerlo limpiamente: consulta Puertos 80 y 443 ocupados. Si solo el puerto 80 no está disponible, el proxy funciona igualmente; simplemente se desactiva la redirección HTTP → HTTPS.

La resolución de los dominios .test

El navegador tiene que saber que miproyecto.test apunta a tu equipo. Joppa se encarga de ello: incluye un pequeño servidor DNS que responde 127.0.0.1 (y ::1) para todos los nombres en .test, en 127.0.0.1:15353, y solo para ellos. Solo queda decirle al sistema que le envíe esos nombres, con un archivo, colocado una vez con tu contraseña.

En el primer arranque, si .test todavía no resuelve, Joppa lo pide enseguida, después de la aprobación del certificado: escribe tu contraseña en la ventana del sistema. Si la cancelas, un aviso te lo recuerda (Configurar), la casilla .test no resuelve de la barra de estado abre el mismo botón, y Ajustes › Resolución de .test lo conserva.

Sistema	Archivo que escribe Joppa
macOS	/etc/resolver/test: nameserver 127.0.0.1 y port 15353
Linux con systemd-resolved (Ubuntu, Fedora…)	/etc/systemd/resolved.conf.d/joppa.conf: DNS=127.0.0.1:15353 y el dominio de enrutamiento ~test
Linux con NetworkManager y dnsmasq	/etc/NetworkManager/dnsmasq.d/joppa.conf: server=/test/127.0.0.1#15353

Después, Joppa vacía la caché DNS del sistema (o recarga systemd-resolved / NetworkManager). Solo los nombres en .test pasan por él: el resto de tu DNS no se toca.

¿Prefieres el terminal? Ajustes › Resolución de .test muestra los comandos exactos para tu equipo, con un botón para copiarlos. En 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

En Linux sin systemd-resolved ni NetworkManager con dnsmasq, Joppa no sabe configurar el resolvedor: añade cada dominio a /etc/hosts (127.0.0.1 miproyecto.test).

Un runtime de contenedores (opcional)

Los dominios y el HTTPS no necesitan nada más. Para los servicios (PostgreSQL, Redis, Mailpit…), instala uno de estos runtimes: OrbStack, Docker Desktop, Colima o Podman. Consulta Runtimes de contenedores.

Comprobar

La barra de estado de la parte inferior de la ventana lo resume todo:

joppa   proxy :443   CA joppa ok   .test ok   2/2 dominios en línea   1/1 servicio

Ya puedes pasar a los primeros pasos.

Actualizar

Joppa busca una nueva versión al arrancar, cada vez que vuelves a abrir su ventana y luego cada seis horas, y la descarga en segundo plano. Aparece entonces una tarjeta verde abajo en la barra lateral: «Joppa x.y.z está listo». Haz clic en Actualizar ahora: Joppa instala la nueva versión y se reinicia.

Cada descarga se comprueba con la firma de Joppa antes de sustituir la app. Para elegir cuándo se descarga, desactiva Descargar automáticamente las nuevas versiones en Ajustes › Actualizaciones: la tarjeta ofrece entonces Descargar e instalar. Buscar actualizaciones, en el mismo sitio, comprueba al momento.

En Linux, la AppImage se actualiza igual. Una instalación desde el .deb o el paquete de Arch no puede sustituirse a sí misma: la tarjeta abre la página de descarga. En Arch, vuelve a ejecutar curl -LO https://download.getjoppa.com/latest/PKGBUILD && makepkg -si en la misma carpeta.

Desinstalar

Joppa se desinstala desde la app o desde el terminal; en ambos casos eliges qué se elimina, y tus proyectos no se tocan.

• Desde la app: Ajustes › Desinstalar › Desinstalar Joppa…, marca lo que se elimina y luego Desinstalar y salir.
• Desde el terminal:

joppa uninstall --dry-run   # lo que se eliminaría
joppa uninstall             # pide confirmación

Se eliminan: el comando joppa, el servidor MCP de los asistentes, los bloques PHP y Node del perfil del shell, los contenedores de los servicios, la aprobación de la CA y el archivo de resolución de .test (tu contraseña), la licencia (se libera el puesto de este Mac), la carpeta de Joppa y la propia app. Los datos de los servicios (bases de datos, correos) solo se eliminan si los marcas, o con --volumes. El detalle: Archivos y carpetas › Quitarlo todo y El comando joppa › Desinstalar.