Servers

The Servers section is where you connect the machines Openship deploys to. You give Openship SSH access to a box you already own — a VPS, a bare-metal server, a VM — and it installs and checks everything a deployment needs (Docker, OpenResty, Git). Once a server is connected, you can pick it as a deploy target from the deploy flow and manage it from its own detail screen.

The Servers list

This screen (/servers) shows every server you've connected. The header reads Servers with the subtitle "Manage your deployment servers and infrastructure", and an Add Server button sits top-right.

Each server appears as a card showing its name (or host if unnamed), a Connected / Error status pill, and the user@host:port it dials. Click a card to open that server's detail screen.

On the right, a Quick Info panel tallies Total Servers, Connected, and Errors.

If you have no servers yet, the empty state explains what an auto-setup configures, with an Add Your First Server button and four cards under "What gets configured":

Adding a server

Press Add Server to reach /servers/new. The page title is Add Server with the subtitle "Enter your server details and choose an auth method", and a Getting Started panel on the right lists what you need: a server with SSH access (Ubuntu, Debian, or similar) and an SSH key or password.

The SSH Connection form

The Authentication control is a three-way toggle:

• Password — enter the server password.
• SSH Key — give a Key Path (e.g. ~/.ssh/id_rsa) and an optional Passphrase.
• Agent — connects using the host machine's ssh-agent (like VS Code); no password or key is entered here. The machine running Openship must already have access to the server.

Under Advanced you can add a Jump Host (e.g. user@bastion.example.com) and Extra SSH Arguments (e.g. -o StrictHostKeyChecking=no).

Two buttons finish the form:

• Test Connection — dials the server with the details you entered and reports success or the failure reason, without saving anything.
• Save & Continue to Setup — saves the server and moves straight into the component setup flow. (When you're editing an existing server, this button reads Save Changes instead.)

The setup flow

After you save a new server, Openship walks you through installing its prerequisites. You first choose how to run it:

• Automatic Setup — "Check requirements and install everything automatically. One click — Openship handles Docker, OpenResty, and Git."
• Step-by-Step Setup — review each component and its detailed status before installing.

The flow then moves through Connect → Check → Install: Openship opens the SSH connection, runs health checks, and installs whatever's missing. Progress streams live, per component (Waiting → Installing → Installed, or Failed), with an expandable Install Logs panel. When it finishes you can jump to the server's detail screen; if anything failed, Retry Failed re-runs just those components.

The server detail screen

Opening a server (/servers/<serverId>) shows its name with a Healthy or Issues badge and the user@host:port beneath it. Top-right are three controls:

• Migrate Docker — opens the migration wizard to bring a running Docker or Compose deployment on that server into Openship.
• Edit — reopens the SSH Connection form (at ?edit=true) so you can change connection details.
• The ⋯ menu — holds Remove Server, which clears the stored SSH credentials and connection settings.

If Openship can't reach the server, a banner appears above the tabs explaining whether the box is unreachable, the credentials were rejected, or the config is incomplete — with a Retry and an Edit shortcut. A Connection panel on the right always shows the current Host, User, and Auth method.

The screen is organized into tabs. Overview, Components, Security, and Terminal always show; Ports appears only in the desktop app.

Overview tab

A live dashboard for the server. Four stat cards show CPU (with load averages), Memory, Disk (each with a usage bar that turns amber past 70% and red past 90%), and Uptime. Below them, a Components card lists each installed component with a Healthy / Unhealthy marker and version. The header summary reads "All systems operational" or "{n} of {m} unhealthy". See Logs & monitoring for more on reading these signals.

Components tab

Manage the software Openship relies on. The System Health card lists every required component and, under a Detected Infrastructure divider, any optional ones it found. Each row shows health, version, and a status message, with per-component actions:

Header buttons let you Install Missing ({count}) in one go, or Re-check to re-run the health checks. Installs and removals stream a progress card with component rows and an expandable logs panel, matching the setup flow.

Security tab (rate limiting)

This tab configures OpenResty request rate limiting for the server. The core control is Requests / second; Openship derives a burst allowance automatically (about 40% of the rate). Open Advanced to switch Burst mode to manual and set a custom Burst allowance.

Whitelisted IPs let you list addresses or CIDR ranges that bypass the limit (loopback 127.0.0.1 and ::1 are always whitelisted). Type an IP or CIDR and press Add.

Save with Apply rate limit (first time) or Save changes (when one already exists); Remove rate limit clears it, and Refresh re-reads the live config from OpenResty. A draft indicator at the bottom summarizes pending changes before you save.

Ports tab (port forwarding)

Desktop-only. Port forwarding exposes a remote server port as localhost:<port> on your own machine — like VS Code's port forwarding. Each forward is bound to loopback and is active only while running.

Existing forwards are listed with a running/stopped dot, the remote host:port, the local address, and per-forward controls: Start / Stop, Remove, and an Open on startup toggle. To add one, enter a Remote port (1–65535) and an optional Local (auto) port (0 for auto, or 1–65535), then press Add.

Terminal tab

A live SSH shell to the server, right in the browser, running over WebSocket. You can open up to 3 concurrent shells in tabs, and text is copied on select. The shell only stays open while this tab is active.

Editing and removing a server

To change connection details, press Edit on the detail screen (or Edit from a single-server list) — this reopens the same SSH Connection form with a Save Changes button. When editing, leaving the password or key blank keeps the stored secret; you only re-enter it when switching auth method.

To disconnect a server, use Remove Server from the ⋯ menu. This clears the SSH credentials and connection settings for that entry.

What next?