Concepts
Project, domain, proxy, certificate authority, process and service: Joppa's building blocks and how they fit together.
Overview
Browser ── https://app.myproject.test ──▶ Joppa proxy (:443, TLS)
│ certificate signed by the local CA
├──▶ localhost:5173 dev server (Vite)
└──▶ localhost:8000 API (Laravel)
│
▼
PostgreSQL / Redis / Mailpit…
(Docker or Podman containers)Project
A project is a folder on your disk that Joppa knows about: a name, an icon, domains, and optionally processes, environment variables and pinned versions. The name is the base for its domains: the kinosante project gets kinosante.test and its subdomains.
Removing a project from Joppa never deletes its folder.
Domain
A domain maps an https://…test address to a local port: https://api.kinosante.test → localhost:8000. A project has as many as it has dev servers. Each domain can be disabled without being deleted.
The .test TLD is reserved by the IETF for testing: it will never be assigned on the internet, so it can’t conflict with a real site.
Proxy
The proxy is an HTTPS reverse proxy built into Joppa. It listens on ports 443 and 80 of 127.0.0.1, picks the right certificate from the requested name, then forwards the request to the domain’s port. It handles HTTP/2, WebSockets (HMR) and Server-Sent Events. See HTTPS proxy.
Certificate authority
The local certificate authority (CA) signs a certificate for each domain on the fly. Once your system trusts it, every current and future domain is trusted. See Certificates.
Process
A process is a command Joppa runs for a project: a dev script from package.json or a service from the project’s Docker Compose file. Joppa knows their order and their port, and relaunches the ones that crash. See Processes.
Service
A service is a shared server that Joppa runs in a container: PostgreSQL, MySQL, MariaDB, Redis, Valkey, Mailpit, Typesense or Meilisearch. One server serves all your projects; for databases, each project gets its own database. Linking a service to a project writes its variables to the .env. See Services.
Container runtime
The runtime is the tool that runs the services’ containers: OrbStack, Docker Desktop, Colima or Podman. You only need it for services. See Container runtimes.
The app, the terminal and assistants
The desktop app is the heart of Joppa: it runs the proxy and holds the state. The joppa command, its TUI and the MCP server talk to the running app through a local API; they do the same things as the window.