Conceptos
Proyecto, dominio, proxy, autoridad de certificación, proceso y servicio: las piezas de Joppa y cómo encajan.
Visión general
Navegador ── https://app.miproyecto.test ──▶ Proxy Joppa (:443, TLS)
│ certificado firmado por la CA local
├──▶ localhost:5173 servidor de desarrollo (Vite)
└──▶ localhost:8000 API (Laravel)
│
▼
PostgreSQL / Redis / Mailpit…
(contenedores Docker o Podman)Proyecto
Un proyecto es una carpeta de tu disco que Joppa conoce: un nombre, un icono, unos dominios y, opcionalmente, procesos, variables de entorno y versiones fijadas. El nombre sirve de base para los dominios: el proyecto kinosante recibe kinosante.test y sus subdominios.
Quitar un proyecto de Joppa nunca elimina su carpeta.
Dominio
Un dominio conecta una dirección https://…test con un puerto local: https://api.kinosante.test → localhost:8000. Un proyecto tiene tantos como servidores de desarrollo. Cada dominio se puede desactivar sin eliminarlo.
El TLD .test está reservado por el IETF para pruebas: nunca se asignará en Internet, así que no puede entrar en conflicto con un sitio real.
Proxy
El proxy es un proxy inverso HTTPS integrado en Joppa. Escucha en los puertos 443 y 80 de 127.0.0.1, elige el certificado correcto según el nombre solicitado y reenvía la petición al puerto del dominio. Soporta HTTP/2, WebSockets (HMR) y Server-Sent Events. Consulta Proxy HTTPS.
Autoridad de certificación
La autoridad de certificación (CA) local firma al vuelo un certificado para cada dominio. Una vez aprobada por tu sistema, todos los dominios actuales y futuros son de confianza. Consulta Certificados.
Proceso
Un proceso es un comando que Joppa ejecuta para un proyecto: un script dev de package.json o un servicio Docker Compose del proyecto. Joppa conoce su orden y su puerto, y reinicia los que fallan. Consulta Procesos.
Servicio
Un servicio es un servidor compartido que Joppa ejecuta en un contenedor: PostgreSQL, MySQL, MariaDB, Redis, Valkey, Mailpit, Typesense o Meilisearch. Un servidor atiende a todos tus proyectos; en el caso de las bases de datos, cada proyecto tiene la suya. Vincular un servicio a un proyecto escribe sus variables en el .env. Consulta Servicios.
Runtime de contenedores
El runtime es la herramienta que ejecuta los contenedores de los servicios: OrbStack, Docker Desktop, Colima o Podman. Solo se necesita para los servicios. Consulta Runtimes de contenedores.
La app, la terminal y los asistentes
La app de escritorio es el núcleo de Joppa: ejecuta el proxy y guarda el estado. El comando joppa, su TUI y el servidor MCP hablan con la app en ejecución a través de una API local; hacen lo mismo que la ventana.