How to Install Openship: Desktop, Self‑Hosted, and Cloud Deployment Guide

Openship can be installed as a local desktop application for solo operators, deployed as a self‑hosted Linux server for teams via CLI or Docker Compose, or consumed as a fully managed SaaS through Openship Cloud. The installation path you choose determines whether the control plane runs on your local machine, a remote server with a public URL, or as a zero‑ops hosted service.

The oblien/openship repository provides detailed installation procedures in docs/installation.md and supporting automation scripts in the scripts/ and apps/cli/ directories. This guide covers all three deployment shapes—Desktop, Self‑Hosted, and Cloud—using commands and configuration files extracted directly from the source.

Choose Your Installation Shape

Openship is designed to run in three distinct operational modes:

• Desktop App: The control plane lives on your local machine and communicates with remote servers over SSH. Ideal for private workflows and single operators.
• Self‑Hosted Server: The control plane runs on a dedicated Linux box reachable via a public URL, gated by login and invites. Suitable for teams and CI/CD automation.
• Openship Cloud: A managed SaaS offering requiring no infrastructure setup.

The following sections detail the installation steps for the Desktop and Self‑Hosted options, as these require local setup.

Install the Desktop App (Recommended for Solo Use)

For individual operators who want to manage remote infrastructure without exposing public ports, the Desktop app provides a local control plane with minimal attack surface.

Download and install the binary for your platform using the built‑in installer:

openship install

This command fetches the desktop build appropriate for your operating system from the official release channel.

Once installed:

1. Launch the application.
2. Choose This Machine to manage the local host, or select Another Server to add a remote machine via SSH (providing host, user, and key).
3. Test the connection to verify SSH access.

The Desktop client then drives the control plane locally, keeping all sensitive operations on your workstation while executing commands on remote hosts.

Install a Self‑Hosted Server (Team or CI/CD)

For team environments or always‑on automation, you must deploy the control plane to a Linux server. The repository offers three methods to achieve this.

Option A: Install via the Desktop App

If you already have the Desktop app running:

1. Add the target Linux server as an SSH host in the Desktop interface.
2. Select "Install Openship on this server".
3. The app automatically copies binaries to the remote host and configures a system boot service.

This method is best for interactive setups where you prefer a GUI‑driven workflow.

Option B: Install via CLI (Headless/CI)

For servers without a GUI, automated pipelines, or infrastructure‑as‑code workflows, use the command‑line installer located in scripts/install.sh:

# One‑line installer (alternative: npm i -g openship)

curl -fsSL https://get.openship.io | sh

After installation, run the interactive wizard to create the first admin and attach your domain:

openship

For fully automated, non‑interactive deployments (common in CI/CD), use flags:

openship up --public-url https://ops.example.com \
            --managed-edge \
            --foreground

• openship up creates a persistent system service that starts on boot and auto‑restarts.
• --managed-edge provisions an OpenResty reverse proxy with a free Let's Encrypt TLS certificate, eliminating the need for an external load balancer.
• --foreground keeps the process attached to your shell (omit for background daemon mode).

Option C: Docker Compose

If you prefer a containerized, pull‑based deployment, use the compose definition in docker/docker-compose.yml:

git clone https://github.com/oblien/openship.git && cd openship
cp .env.example .env
docker compose --env-file .env -f docker/docker-compose.yml up -d

This stack brings up Postgres, Redis, the API service, the dashboard, and the OpenResty edge proxy on ports 80 and 443.

For reproducible builds, pin the OPENSHIP_VERSION variable in your .env file, or use the build‑variant compose file at docker/docker-compose.build.yml to compile from source.

Essential CLI Commands

The openship binary, implemented in apps/cli/src/index.ts and distributed via apps/cli/package.json, provides the following essential commands for managing your installation:

• openship up [--foreground]: Starts the Openship service as a background daemon or attached process.
• openship up --public-url <url> [--managed-edge]: Exposes the dashboard publicly with optional edge proxy installation.
• openship stop: Halts the running service.
• openship status [--json]: Returns health checks for ports and API status.
• openship install: Downloads the Desktop app for the current OS.
• openship reset-admin-password: Resets the local admin password without requiring sign‑in.
• openship doctor: Diagnoses CLI environment issues.

Summary

• Desktop App: Run openship install for local‑only control planes managed via GUI.
• Self‑Hosted CLI: Use curl -fsSL https://get.openship.io | sh followed by openship up --public-url <url> --managed-edge for headless Linux servers.
• Docker: Clone the repo and run docker compose -f docker/docker-compose.yml up -d for full containerization.
• Source of Truth: All installation logic resides in docs/installation.md, scripts/install.sh, and apps/cli/src/index.ts.

Frequently Asked Questions

What is the difference between the Desktop and Server installations?

The Desktop installation places the control plane on your local workstation, communicating with remote machines over SSH without opening public ports. The Server installation runs the control plane on a remote Linux host, exposing a web dashboard at a public URL for team access and webhook‑driven CI/CD.

How do I reset the admin password on a self‑hosted server?

Run the following command on the server where Openship is installed:

openship reset-admin-password

This executes a local password reset without requiring email authentication or existing credentials.

Can I install Openship without using Docker?

Yes. The native binary installation via curl -fsSL https://get.openship.io | sh or npm i -g openship installs the CLI directly on your Linux host, creating a systemd service without containerization. The Desktop app also runs natively without Docker.

Where is the installation documentation located in the repository?

The canonical user‑facing guide is at docs/installation.md. Implementation details for the installer script are in scripts/install.sh, while the CLI command logic is defined in apps/cli/src/index.ts and published through apps/cli/package.json.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}