Jetty

Documentation for Jetty

Installation

Pick the install path that matches how you work locally. The user-facing CLI is jetty via Composer or PHAR (PHP 8.2+). You need a server name and token from Bridge (see Getting started in the app for copy-paste lines for this deployment).

Ingress (tunnel entry on your network) runs as a separate process — jetty-edge (Go binary from cli-v* GitHub Release assets jetty-cli-*, or build from this repo / Docker), not the same as the PHP jetty developer command. Operators deploy it behind TLS; see Network and edge deployment.

After install, configure the client, then share a local site—see Sharing local sites for port vs --site (local upstream) examples.

PHP: Composer (jetty/client) — recommended

Prefer a global install so jetty is on your PATH from any project:

composer global require jetty/client
jetty version

Add Composer’s global vendor/bin to your PATH if needed (location varies by OS; run composer global config bin-dir --absolute to print it). Example:

export PATH="$PATH:$(composer global config bin-dir --absolute)"

Optional — per-project (use ./vendor/bin/jetty from that app, or jetty install-client):

composer require jetty/client
./vendor/bin/jetty version

Configure (or set JETTY_SERVER / JETTY_TOKEN / JETTY_API_URL in the environment instead of the config file):

jetty config set server your-server-name
jetty config set token your-token-here

Then:

jetty share 8000

The client registers tunnels, connects the WebSocket agent to ingress (JETTY_EDGE_WS_URL on Bridge), and forwards HTTP to your local port. Use --skip-edge only for registration + heartbeats without forwarding.

PHP: PHAR

Single-file PHAR (PHP 8.2+, curl, openssl for wss://, zlib; the installer also needs Python 3 plus git when falling back to Composer). Releases ship jetty-php.phar on cli-v* GitHub Releases when you run the Release CLI workflow.

One-line install (from your Jetty app)

curl -fsSL "https://usejetty.online/install/jetty.sh" | bash

By default (--method auto, or set JETTY_INSTALL_METHOD=auto) the script:

  1. Tries the latest PHAR from GitHub Releases (same repo your app injects).
  2. If there is no PHAR yet, clones that repo and runs composer global require jetty/client:@dev using a path repository pointing at jetty-client/ (needs PHP 8.2+ and Composer).

Force one path explicitly:

curl -fsSL "https://usejetty.online/install/jetty.sh" | bash -s -- --method phar
curl -fsSL "https://usejetty.online/install/jetty.sh" | bash -s -- --method composer

Clone cache defaults to ~/.local/share/jetty/repo (JETTY_SRC_DIR to override).

When a PHAR is used, it is installed as jetty under ~/.local/bin (or /usr/local/bin with --sudo). The script can append the right bin directory to your ~/.zshrc or ~/.bashrc. Then reload your shell so PATH is picked up:

exec "$SHELL" -l

Configure and share:

jetty config set server your-server-name
jetty config set token your-token-here
jetty share 8000

Ingress binary (jetty-edge)

For self-hosted deployments, use the jetty-cli-* archives from your team’s GitHub cli-v* releases (contains jetty-edge only), build from the repository, or use cli/Dockerfile.

cd cli && go build -trimpath -ldflags="-s -w" -o jetty-edge ./cmd/jetty-edge

Use scripts/install-jetty-edge.sh (repo root) for systemd on a server (downloads from releases by default, or --bin). Run it with environment aligned to Bridge (JETTY_EDGE_SECRET, JETTY_LARAVEL_URL, JETTY_TUNNEL_HOST, listener address). On Debian/Ubuntu it installs Certbot and one apt plugin per JETTY_CERTBOT_DNS_PROVIDER in the env (nginx default; cloudflare, digitalocean, or all) when scripts/certbot-deps.inc.sh is present (same idea as scripts/jetty-edge-ssl.sh ensure-deps). It does not replace the PHP jetty CLI on developer machines — it terminates public HTTP and WebSockets from jetty share agents.

Docker (optional)

The repo includes cli/Dockerfile for building an image that runs jetty-edge (ingress). For developer machines, prefer Composer or PHAR for the jetty CLI.

docker build -f cli/Dockerfile -t jetty-edge ./cli

To reach a service on your host from inside the container, pass host.docker.internal with jetty share as --site=host.docker.internal (Docker Desktop). On Linux add --add-host=host.docker.internal:host-gateway.

Updates

PHAR: jetty update (alias self-update) — see jetty-client README. Set JETTY_CLI_GITHUB_REPO=owner/repo and optionally JETTY_PHAR_GITHUB_TOKEN for private repos.

Composer: composer update jetty/client in the owning project.

Next steps

  1. Open Bridge and go to Getting started for platform-specific downloads, env snippets, and jetty share examples wired to this deployment.
  2. Read Sharing local sites for --site, reserved labels, and local HTTPS (Valet) notes.