Edge & monitoring

The edge is the OpenResty reverse proxy Openship runs on ports :80/:443. It terminates TLS, routes each hostname to the right container, enforces per-route rules (rate limits, bans, geo/CIDR access), and — because it already sees every request — counts the traffic that feeds the Monitoring tab. openship edge is the terminal surface for all of that: stand it up, take over a proxy that's already on those ports, manage domains and rules, and read the analytics it produces.

When to use it

• Something else already owns :80/:443. You have nginx / Apache / Caddy on the box and want Openship's edge to take over — either importing its existing sites (migrate) or just claiming the ports (takeover).
• Route a hostname to a port without building a full project — edge domains add app.example.com --port 8080 registers the host, points it at 127.0.0.1:8080, and issues a certificate.
• Protect a route with a rate limit, an IP/country ban, or a CIDR allow-list — edge rules add.
• Read what the edge is seeing from the terminal: a traffic overview, per-domain analytics (visitors, countries, top paths), or the recent raw request log — edge traffic / edge analytics / edge logs.

Every reporting command also honours the global --json flag, so the same data pipes into jq or a script.

Command summary

openship edge — the interactive panel

Run openship edge with no arguments on a terminal to open a looping panel. It shows the edge's current state (installed? serving? how many domains) and offers the right actions for where you are: browse domains, register one, view a traffic overview, bring up or repair the edge, migrate or take over another proxy, scan for importable sites, and — if there's no server yet — enable monitoring. Pick an action, do it, and land back on the menu; Quit exits.

The panel is a trusted local tool. On a desktop / loopback box the API is zero-auth, so it just makes the call — no token needed. It only asks you to openship login if a call actually comes back unauthorized (a real self-hosted server with an admin), and tells you plainly when the API isn't reachable rather than showing a dead-end login screen.

openship edge

openship edge up

Ensures the edge container is up and serving :80/:443, repairing it if it isn't. With --monitoring it also stands up the built-in Openship server (a bare install with an embedded database) so the traffic the edge counts has somewhere to land and the traffic / analytics commands have something to read. On a box that already has Openship installed, --monitoring is a no-op — monitoring is already available through the running instance.

# Just make sure the edge is serving
openship edge up

# Serve, and on a port conflict import the existing proxy's sites
openship edge up --migrate

# Also turn on monitoring (installs the built-in server + analytics DB)
openship edge up --monitoring --admin-email [email protected]

Taking over an existing proxy

If nginx, Apache, or Caddy already holds :80/:443, the edge can't bind them until they're freed. These commands resolve that — and the whole operation is journaled and rollback-safe: if a step fails, it unwinds cleanly rather than leaving you with neither proxy serving.

# Take over AND bring the old proxy's sites across (recommended)
openship edge migrate

# Just free the ports — the old proxy is stopped and its sites drop
openship edge takeover

# See what would be imported before committing
openship edge sites

# Diagnose why the edge isn't serving; attempt a fix
openship edge repair --fix          # defaults to migrate
openship edge repair --fix --takeover

migrate reads the existing proxy's virtual hosts, registers each one on the edge (so it keeps serving), and only then frees the ports. takeover skips the import and just stops the occupant.

openship edge domains

Domains routed through the edge. add registers a hostname and points it somewhere: attach it to an existing project with --project (uses that project's port) or bind a brand-new tracked project to a port with --port (exactly one of the two). Registering also verifies DNS and issues a Let's Encrypt certificate unless you pass --no-verify.

# Route a host straight at a local port (creates a tracked project)
openship edge domains add app.example.com --port 8080

# Attach a host to an existing project
openship edge domains add www.example.com --project prj_123 --primary

# List / remove
openship edge domains list -p prj_123
openship edge domains rm app.example.com -p prj_123

For the full custom-domain / DNS / certificate workflow, see the project-level openship domain command — edge domains is the edge-scoped view of the same routing.

openship edge rules

Per-route edge rules — rate limits, bans, and access control — applied by the proxy before a request ever reaches your app. Scope a rule to the whole project, one domain (--domain), or a path prefix (--path). Pass at least one rule flag; combine as many as you like into a single rule.

# 20 req/s 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 an abusive IP, returning 403
openship edge rules add -p prj_123 --ban-country RU,CN --ban-ip 203.0.113.7 --block-status 403

# Allow-list an office CIDR — everything else is denied
openship edge rules add -p prj_123 --allow-cidr 198.51.100.0/24

openship edge rules list -p prj_123
openship edge rules rm <ruleId> -p prj_123

Viewing monitoring data

This is what makes the edge a product you watch, not just plumbing. The proxy counts every request in shared memory (costing the visitor nothing — the work happens after the response is sent), a scheduled job moves those aggregates into the database every 30 minutes, and these commands read them back. All three take -p, --project and accept --json.

# Traffic overview: requests, bandwidth, and hourly periods
openship edge traffic -p prj_123

# Per-domain analytics: visitors, countries, top paths
openship edge analytics -p prj_123 --domain app.example.com

# Recent raw request log, and follow it live
openship edge logs -p prj_123 --limit 100
openship edge logs -p prj_123 --follow

Where to next