Openship GitHub Repository: Architecture and Deployment Guide

Openship is a self-hostable, open-source deployment platform that provides a unified control-plane through a CLI, desktop GUI, and web dashboard to automate application deployment via Docker or bare-metal processes.

The oblien/openship repository hosts the complete source code for an end-to-end deployment system designed to run locally, on a self-hosted server, or in the managed Openship Cloud. The project is structured as a Turbo monorepo, utilizing workspaces defined in package.json to manage a shared backend API, multiple frontend interfaces, and an edge routing layer.

Monorepo Architecture and Key Components

The Openship project follows a monorepo structure where each application resides under the apps/ directory and shares code via a centralized build system.

• CLI (apps/cli/): The command-line interface that handles installation, initialization, and deployment orchestration. Built using Bun via bun run --cwd apps/cli build.
• Desktop App (apps/desktop/): An Electron-based GUI that runs the control-plane locally and connects to remote servers via SSH.
• Web Dashboard (apps/dashboard/): A React/Next.js interface that runs on the same backend as the CLI, intended for team collaboration.
• API Server (apps/api/): The central REST and MCP endpoint that implements the deployment pipeline, webhook handling, and resource management. Containerized via apps/api/Dockerfile.
• Edge Router: An OpenResty (nginx + Lua) container defined in docker/docker-compose.yml that terminates TLS, routes traffic, and handles Let’s Encrypt certificate provisioning.
• Data Stores: PostgreSQL for metadata, users, and projects, and Redis for queues and caching, both defined in the compose file.

Deployment Modes: Compose vs. Bare

Openship supports two distinct runtime modes selected automatically or forced via flags.

Compose (Docker) Mode

This is the default on Linux systems with Docker installed. The control-plane launches the full stack—including Postgres, Redis, the API, Dashboard, and Edge router—using the orchestration file at docker/docker-compose.yml.

In this mode, applications are built as Docker containers on the host, and the Edge router forwards traffic to the container’s loopback port. This mode is ideal for "all-in-one" self-hosted servers.

Bare Mode

Designed for macOS, Windows, or Linux without Docker, this mode runs a single lightweight process using openship up --bare. It embeds a SQLite database and directly spawns the application’s start command on the host OS rather than inside a container. The CLI and Dashboard UIs function identically in both modes.

The Deployment Pipeline and Configuration

The core deployment logic follows a four-stage pipeline implemented in the API server, specifically within apps/dashboard/src/lib/api/deploy.ts.

1. Detect: Scans the repository for framework clues (e.g., package.json, lockfiles).
2. Build: Creates a Docker image or a bare release snapshot.
3. Run: Launches the container or host process.
4. Route + Secure: The OpenResty edge router writes a vhost for the domain and obtains a Let’s Encrypt certificate using HTTP-01 validation.

You can override auto-detection by placing an openship.json file in the project root:

{
  "name": "my-app",
  "runtime": "node",
  "build": "npm run build",
  "start": "node server.js",
  "port": 8080
}

Installing and Using the Openship CLI

Install the CLI globally to manage deployments from your terminal.

# Install via install script

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

# Or install via npm

npm i -g openship

Key commands include:

• openship init: Links the current folder to a new Openship project.
• openship deploy: Triggers the Detect → Build → Run pipeline.
• openship up: Starts the local control-plane (uses --compose or --bare automatically).
• openship open: Launches the Web Dashboard in your browser.
• openship stop: Halts the running control-plane.

Self-Hosting with Docker Compose

For a fully self-hosted instance without using the CLI wizard, clone the repository and use the provided compose definition.

git clone https://github.com/oblien/openship.git && cd openship
cp .env.example .env

# Edit .env to set your domain and secrets

docker compose --env-file .env -f docker/docker-compose.yml up -d

This command starts the postgres, redis, api, dashboard, and edge services. The edge service runs OpenResty in host network mode to bind directly to ports 80 and 443.

Summary

• Openship provides a unified control-plane accessible via CLI (apps/cli/), Desktop (apps/desktop/), and Web Dashboard (apps/dashboard/).
• It supports two primary runtime modes: Compose (Docker-based, using docker/docker-compose.yml) and Bare (lightweight, SQLite-backed).
• The deployment pipeline logic resides in apps/dashboard/src/lib/api/deploy.ts, routing traffic via the OpenResty edge router defined in the compose file.
• The project is organized as a Turbo monorepo, with workspace configuration in package.json and container definitions in apps/api/Dockerfile.

Frequently Asked Questions

What is the Openship GitHub repository?

The oblien/openship repository is the official source code for Openship, an open-source platform that lets you run a control-plane to automate building, running, and routing traffic to your applications. It includes the CLI, Electron desktop app, Next.js dashboard, and API server.

How do I run Openship without Docker?

You can run Openship in Bare Mode by using the --bare flag with the CLI, such as openship up --bare. According to the source code in apps/cli/, this mode initializes a SQLite database and spawns application processes directly on the host instead of building Docker containers.

Where is the API server logic located?

The backend API is primarily located in the apps/api/ directory. The deployment endpoint handling project creation is implemented in apps/api/src/routes/projects.ts, while the core pipeline logic used by both the API and UI is found in apps/dashboard/src/lib/api/deploy.ts.

Can I configure custom build commands?

Yes. If the automatic detection of package.json scripts is insufficient, you can define a custom openship.json file in your project root. This file allows you to specify explicit build and start commands, the port, and the runtime environment, which the pipeline will use instead of inferred defaults.

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