Skip to Content
Task guides

Operate a self-hosted installation

Manage the control-plane service, restrict host access, automate installation, and remove it safely.

View Markdown

This guide applies to the self-hosted control plane. Applications deployed to connected servers have separate lifecycles. Start with installation for initial setup.

Service lifecycle

CommandResult
openship upStart the supported background service.
openship up --foregroundRun in the terminal; stop when the process exits.
openship stopStop OpenShip while retaining installation data.
openship statusInspect the selected instance's health and mode.
openship doctorDiagnose configuration, connectivity, and runtime setup.

Background service support depends on the host:

  • Linux: systemd, with a system unit or user unit and linger as appropriate.
  • macOS: a launchd agent, reloaded at login.
  • Windows: a Scheduled Task at logon, where supported. Use foreground mode or Desktop when service registration is unavailable.

On a Linux host without systemd, use a supervised foreground process or the Compose stack.

Host control (hardening)

The Compose installer configures an SSH channel from the API container to the host through host.docker.internal. Host operations include port takeover, configuration, and the host terminal. The channel requires a reachable SSH daemon and firewall rules that permit container-to-host traffic.

openship up probes this channel and offers the needed rule. openship doctor checks it later. A healthy container stack does not prove that host operations work. See host-channel diagnostics for repair.

For a control plane that only manages remote servers:

openship up --no-host-control

This disables the generated host key and host operations, and removes This Server as a deployment target. It is a CLI installation option, not a dashboard toggle.

Docker access remains privileged

The API still mounts the host Docker socket when using that installation mode. Access to the socket can control the host. Disabling host control does not isolate a compromised control plane.

Use caseHost-control setting
Control plane also deploys to its own hostLeave enabled for required host operations.
Control plane manages only remote serversDisable with --no-host-control.
Host also runs sensitive workloadsPrefer a separate control-plane host and restrict access.

Use private connectivity or a trusted authenticated proxy when the dashboard should not be public. OPENSHIP_BIND_ADDR controls the bind address for supported installations.

Fully unattended install (headless)

Supply OPENSHIP_ADMIN_PASSWORD through a protected environment, then use --non-interactive (alias --yes) and the required administrator/domain options. Avoid putting passwords in command-line arguments, shell history, logs, or source control.

For a private Compose installation:

openship up --non-interactive \
  --admin-email [email protected] --admin-name "Platform team" \
  --domain-kind none

For a custom hostname with managed TLS:

openship up --non-interactive \
  --admin-email [email protected] --admin-name "Platform team" \
  --domain-kind custom --hostname ops.example.com \
  --acme-email [email protected] --edge migrate

Add --bare to use the bare installation path. Both installation modes support administrator bootstrap and the domain modes below.

Domain modeRequirements
noneNo public domain; use private access.
byoYour reverse proxy; provide --hostname or --public-url.
custom--hostname, ACME contact, reachable ingress, and a decision about existing port ownership.
freeA Cloud-connected instance and --slug; the initial free-domain connection requires an interactive browser step.

--edge migrate imports supported existing proxy sites before takeover. --edge takeover stops the existing proxy, so its sites stop serving unless they are configured elsewhere. --edge cancel declines takeover. Review this choice before automating it on a shared host.

Administrator bootstrap is idempotent: rerunning it can reset the existing administrator's password. Missing/invalid required input exits non-zero. Certificate issuance is best-effort: setup may complete while TLS remains pending, with a reported reason and subsequent retries. Verify the hostname after setup.

Use openship up --dry-run to inspect the planned installation without provisioning it.

Preserve installation secrets

Keep the original installation user's ~/.openship directory and a protected copy of its configuration. For Compose installations, database and encryption secrets are stored in ~/.openship/compose/.env. Do not regenerate them against an existing database.

If startup refuses to regenerate secrets, follow the recovery procedure. An application backup and a control-plane backup protect different data; plan for both.

Removing Openship

Read the command's confirmation before continuing:

openship uninstall
OptionEffect
--keep-dataRetain the database and certificates while removing the running stack.
--keep-imagesRetain OpenShip container images.
--yesSkip confirmation; use only after checking the intended installation.

Uninstall removes OpenShip's stack and selected installation data. Deployed applications are not deleted as part of control-plane removal, and unrelated Docker resources are not pruned. Delete projects explicitly first if their workloads should also be removed.

If OpenShip previously took over ports 80/443, you may need to re-enable the previous reverse proxy manually. Removing the edge can interrupt public routes even while application containers keep running.

Next steps

Help improve this page Edit on GitHubReport an issue

On this page