# Openship GitHub Repository: Architecture and Deployment Guide

> Explore the Openship GitHub repository to learn about its architecture and deployment guide. Automate application deployment with this unified, self-hostable platform via CLI, GUI, or web dashboard.

- Repository: [oblien/openship](https://github.com/oblien/openship)
- Tags: architecture
- Published: 2026-07-31

---

**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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/apps/dashboard/src/lib/api/deploy.ts).

1.  **Detect**: Scans the repository for framework clues (e.g., [`package.json`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/openship.json) file in the project root:

```json
{
  "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.

```bash

# 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.

```bash
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`](https://github.com/oblien/openship/blob/main/docker/docker-compose.yml)) and **Bare** (lightweight, SQLite-backed).
- The deployment pipeline logic resides in [`apps/dashboard/src/lib/api/deploy.ts`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/apps/dashboard/src/lib/api/deploy.ts).

### Can I configure custom build commands?

Yes. If the automatic detection of [`package.json`](https://github.com/oblien/openship/blob/main/package.json) scripts is insufficient, you can define a custom [`openship.json`](https://github.com/oblien/openship/blob/main/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.