The edge

Every request from the internet has to land somewhere first, before Openship knows which of your apps it's for. That somewhere is the edge — a reverse proxy that sits on ports 80 and 443 and acts as the front door for the whole box. It answers the connection, sorts out HTTPS, works out which app the hostname belongs to, forwards the request to that app's container, and counts it on the way past.

Most of the time you never think about it: openship up sets the edge up for you, and every deploy that has a domain wires that domain into it automatically. You start caring about the edge directly in a few specific moments — when you're moving an existing server across, when you want to route a bare hostname at a port, when you need to rate-limit or block something, or when you're asking "where is my traffic actually coming from?"

What the edge actually does

Four jobs, all on the request path:

• HTTPS for free. It terminates TLS and gets a Let's Encrypt certificate for each domain, so your apps are served over https:// without you managing certs.
• Routing. It maps each hostname to the right container — that's how ten apps share one server and one IP, each on its own domain.
• Protection. Per-route rules — rate limits, IP/country bans, CIDR allow-lists — are enforced here, before a request ever reaches your app.
• Traffic counting. Because it already sees every request, it tallies them (requests, bandwidth, countries, top paths) at essentially no cost, and that's what fills the analytics you'll see later.

Taking over a server that's already serving

This is the headline case. You have a server that's already running nginx, Apache, or Caddy on :80/:443 with real sites on it, and you want Openship to run the front door instead — without a flag day where nothing is served.

The edge does this as a migration: it reads the existing proxy's sites, registers each one on the edge so it keeps serving, and only then takes the ports. The whole thing is journaled and rolls back cleanly if a step fails, so you never end up with neither proxy up.

openship edge sites

openship edge migrate

Putting a domain on the edge

Once the edge is running, giving an app a public hostname is one command. You can point a domain at an existing project, or bind a fresh one straight to a local port:

# Point a host at a port on this box (creates a tracked project for it)
openship edge domains add app.example.com --port 8080

# Attach a host to an existing project (uses that project's port)
openship edge domains add www.example.com --project prj_123 --primary

Registering a domain also verifies its DNS and issues the HTTPS certificate for you. If DNS isn't pointing at the box yet, the command prints the records to add and you re-run verification once they've propagated. The full domain workflow — DNS records, verification, primary vs. redirect — lives in the Custom domains guide; openship edge domains is the edge-scoped view of it.

Protecting a route

Rules are applied by the edge itself, so an abusive request is turned away before it costs your app anything. Scope a rule to a whole project, one domain, or a path prefix, and combine as many conditions as you like into one rule:

# 20 requests/second per client IP on the login path, allowing short bursts
openship edge rules add -p prj_123 --path /login --rate-limit 20 --burst 40

# Block two countries and a bad IP, answering with 403
openship edge rules add -p prj_123 --ban-country RU,CN --ban-ip 203.0.113.7 --block-status 403

# Only let an office network in; deny everyone else
openship edge rules add -p prj_123 --allow-cidr 198.51.100.0/24

openship edge rules list -p prj_123

Watching your traffic

This is the part that makes the edge something you watch, not just plumbing. Because it counts every request as it passes, you get a traffic picture with no code and no cost to your visitors. There are two ways to see it.

In the dashboard, open the project's Overview tab for the rollup — Server Requests, Unique IPs, Avg Response, Bandwidth Out, a traffic chart, and Top Paths — and the Logs → Server sub-tab for the individual request lines. That's covered in Logs & monitoring.

From the terminal, the same numbers are three commands:

# Requests, bandwidth, and hourly periods
openship edge traffic -p prj_123

# Visitors, countries, and top paths for one domain
openship edge analytics -p prj_123 --domain app.example.com

# The recent raw request log — and follow it live
openship edge logs -p prj_123 --follow

Prefer the full command reference?

Everything here is a task-level walkthrough. For the complete list of openship edge subcommands and every flag — the interactive panel, up/repair, all the domain, rule, and analytics options — see the Edge & monitoring CLI reference.

What next?