openship README

The project's README from github.com/oblien/openship. As one markdown file: README.md.

Openship

Open-source, self-hostable deployment platform with built-in CI/CD.
Point it at a repo — it builds, ships, routes, and TLS-terminates your app. Drive it from a desktop app, web dashboard, or CLI.

Trendshift

npm version License Website

Quick Start · How It Works · Interfaces · Docs · Contributing

English العربية 简体中文 Español Français 日本語 Português Deutsch Türkçe 한국어

Openship dashboard

Quick Start

There's one decision to make first: how you run Openship itself (the control plane). Everything else is the same afterwards.

If you're… Run Openship as Where your apps run
Solo, one machine, no ops Desktop app A server you connect over SSH, or Openship Cloud
A team — or you want push-to-deploy / to host apps on your own box Self-hosted server (openship up) On that box (Compose mode) — or out to another server / Cloud (bare mode)
Not interested in running anything Openship Cloud Managed sandboxes, zero setup

[!TIP] Solo? Use the desktop app. It runs Openship's control plane on your own machine only while the app is open — nothing is left running on an always-on server, nothing is exposed publicly. You only need an always-on server install once you want push-to-deploy (CI/CD), team access, or to host apps on that box — the things that need a public, always-on endpoint.

Solo — desktop app

The control plane runs locally and drives your servers over SSH. No login, no terminal, no public surface — download, open, done:

Platform Download
macOS (Apple Silicon) Openship-arm64.dmg
macOS (Intel) Openship-x64.dmg
Windows Openship-win32-x64.zip
Linux Openship.AppImage

Linux: chmod +x Openship.AppImage && ./Openship.AppImage. Already have the CLI? openship install fetches and launches it. Links always point at the newest release.

From the desktop app you connect a server (SSH) or Openship Cloud and deploy to it — the app itself doesn't host public apps on your laptop.

Team / always-on — self-hosted server

Install the CLI (it bundles the API + dashboard), then run openship — an interactive wizard creates the first admin, wires your domain, and installs Openship as a boot service. Run it again anytime to manage the instance.

curl -fsSL https://get.openship.io | sh          # install  (or: npm i -g openship — needs Node 22+)
openship                                          # guided setup, then control panel

The install script brings its own Node when your system one is older than 22; a package-manager install runs on the Node you already have.

For CI / headless boxes, skip the wizard and drive openship up directly:

openship up                                       # install + start as a background service (boots + auto-restarts)
openship up --public-url https://openship.example.com   # + serve the dashboard on your domain (edge + TLS handled)

openship up picks how it runs for you:

A self-hosted instance always requires login (the admin you create in setup). openship open opens the dashboard · openship stop stops it · openship update upgrades · openship up --foreground runs attached.

Preview an unreleased build (dev). To run the CLI built straight from source — a branch, tag, or main ahead of the next release — install the from-source build:

curl -fsSL https://get.openship.io/dev | sh                  # main (default)
curl -fsSL https://get.openship.io/dev | OPENSHIP_REF=dev sh  # a branch/tag (var goes on sh, not curl)
openship-dev                                     # same CLI, built from source
openship-dev update                              # pull latest source + rebuild (no release needed)

It installs as a separate openship-dev command with its own isolated home (~/.openship-dev) and boot service, so your production openship and its data are never touched. Needs Bun + git; it's an unverified dev build (the dashboard compile wants real RAM/CPU) — not a production path.

Deploy a project:

cd your-project
openship init            # link this directory to a project
openship deploy

Full server guide + complete CLI reference: openship.io/docs.

Shell completion (bash/zsh/fish)

Two ways to enable Tab-completion for openship:

Setup Trade-off
Static file (recommended) openship completion <shell> > <path> Instant shell startup. Regenerate after upgrading to pick up newly added commands.
Live-sourced add source <(openship completion <shell>) to your shell config Always reflects the currently installed version. Adds a small delay to every new shell session.

Static file:

openship completion bash > /etc/bash_completion.d/openship
openship completion zsh  > ~/.zsh/completions/_openship
openship completion fish > ~/.config/fish/completions/openship.fish

Open a new terminal — done.

Live-sourced (zsh example):

echo 'source <(openship completion zsh)' >> ~/.zshrc
Self-host with raw Docker Compose (no CLI)

The self-hosted stack lives in docker/docker-compose.yml and pulls published images from GitHub Container Registry (ghcr.io/oblien/*) — no build tooling, no monorepo compile. Run it from the repo root:

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

The stack is postgres + redis + api + dashboard + edge. The edge is OpenResty on :80/:443 as a container (network_mode: host) — routing + Let's Encrypt, no bare host install. Linux only (host networking); on mac/win use openship up (bare). The api container mounts the host Docker socket so the control plane can build + run your apps as host containers — it's host-privileged through the socket, so run it only on a trusted host.

Upgrade: pin OPENSHIP_VERSION in .env for reproducible pulls, then docker compose --env-file .env -f docker/docker-compose.yml pull && … up -d. openship update only reconciles a stack the CLI installed, and openship up would adopt this one — don't reach for either here. Build from source instead: add -f docker/docker-compose.build.yml … up -d --build.

Host operations (:80/:443 takeover, the mail engine, host terminal/port scans) need the container→host SSH channel, which openship up provisions and this path does not — the five manual steps are in .env.example under Host operations from the container, and the failure it produces is Troubleshooting → Host control channel. Everything else, including deploys, works without it.

The root docker-compose.yml is a different file: it's the SaaS / from-source control plane (builds from source, ships the marketing site, no edge/socket). It does not self-host your apps — use docker/docker-compose.yml above or openship up.

How It Works

Point Openship at a source — a GitHub repo, a local folder, or a prebuilt artifact — and it runs one pipeline end to end:

  1. Detect. It reads your package.json, framework config, lockfiles, and any docker-compose.yml / openship.json to work out the stack, package manager, build/start commands, and port. Zero config files required; an openship.json overrides the guesses if you want control.
  2. Build. On the target server or locally on the orchestrator, into a Docker image or a bare release. The resolved config is frozen into a snapshot, so redeploys and rollbacks re-run exactly what shipped.
  3. Run. As a container (published on loopback only — never a public port) or a supervised host process.
  4. Route + secure. The OpenResty edge writes a reverse-proxy vhost to your domain and issues a Let's Encrypt certificate (HTTP-01). Because routing and TLS happen after the app is up, a DNS or cert hiccup surfaces as "action required" — it never fails the deploy or takes your app down.
  5. Push-to-deploy. A GitHub webhook re-runs the pipeline on every push to the tracked branch — rebuilding only the services a monorepo push actually touched.

Databases, domains, SSL, CDN, mail, and backups are managed from the same place. (Push-to-deploy and public domains need an always-on server or Cloud — a desktop/loopback instance has no public endpoint to receive webhooks.)

Interfaces

Three ways to drive the same backend:

An MCP endpoint (for AI agents) and a REST API round it out for automation. Only routes that opt in are exposed as MCP tools, every call re-checks your permissions, and credential/token routes can never become tools. Full reference at openship.io/docs.

[!NOTE] The docs are actively being filled out. If something's missing or unclear, contributions are hugely welcome.

Features
Built-in CI/CD Push-to-deploy, preview environments, staging/prod flows, rollbacks
Any stack Node, Python, Go, Rust, PHP, Ruby, Java, .NET, Docker, monorepos
Full backend Postgres, MySQL, MongoDB, Redis, workers, WebSockets, storage
Domains & SSL Automatic Let's Encrypt, wildcards, unlimited domains, auto-renewal
CDN Edge caching, HTTP/3, Brotli compression, instant purge
Mail server Built-in SMTP with DKIM/SPF/DMARC — no Mailgun or SES needed
Backups Scheduled, databases + volumes, one-click restore, export anytime
Real-time monitoring Live build logs, container metrics, visitor geography and per-code response mix — ~1.4 µs per request, zero DB writes per request
Scaling Auto-scaling on cloud, multi-node ready on self-hosted
Portability Standard Docker containers — move between providers freely
Docker Compose Deploy existing compose files as-is

Deploy Anywhere

Same interface regardless of where you deploy.

Status

Production-ready core, actively developed. Self-hosting is free (no billing).

Coming next: multi-node clusters, load-balancing UI, private networking, advanced monitoring, and visual CI/CD pipelines.

Contributing

See CONTRIBUTING.md.

Security

Found a vulnerability? We welcome your report — please disclose it privately, never in a public issue, PR, or discussion.

Good-faith security research is authorized under our safe-harbor policy, and we're happy to credit valid first reports.

License

Openship is open-source software, licensed under the Apache License 2.0.

You may use, run, modify, self-host, and distribute it — including in commercial and closed-source products — under the terms of the Apache 2.0 license. See LICENSE for the full text.

openship (oblien/openship)

Searching Database…

14.8K ·GitHub
Openship
Что это такое?Openship — это open-source платформа для развёртывания, которую можно разместить у себя, со встроенным CI/CD: укажите на репозиторий, и она соберёт, задеплоит, настроит маршрутизацию и TLS для вашего приложения — управлять можно из десктоп-приложения, веб-панели или через CLI.
Это десктоп-приложение или то, что я разверну на своём сервере?И то и другое, плюс управляемое облако. Вы сами выбираете, где будет control plane: десктоп-приложение запускает его локально и управляет вашими серверами по SSH, 'openship up' разворачивает постоянно работающий сервер у вас, а Openship Cloud работает вообще без настройки.
Как его запустить?Для себя: скачайте десктоп-приложение (macOS dmg, Windows zip, Linux AppImage) — ни логин, ни терминал не нужны. Для команды или постоянно работающего инстанса: установите CLI и выполните 'openship up'; мастер создаст первого администратора, привяжет ваш домен и добавит автозапуск-сервис.
Что нужно установить заранее?Node 22+ (если системная версия старше, установочный скрипт поставит свою). На Linux с Docker он запускается в режиме Compose — Postgres, Redis, API, панель и OpenResty на границе сети на :80/:443; без Docker используется bare-режим со встроенной базой данных.
Есть ли подводные камни, о которых стоит знать?Десктоп-приложение не может хостить публичные приложения — push-to-deploy и публичные домены требуют постоянно работающего сервера или Cloud. Самостоятельный хостинг на чистом Docker Compose работает только на Linux, а его API-контейнер имеет привилегии хоста через Docker socket, поэтому запускайте только на доверенной машине.
Где могут работать мои приложения?Где угодно: Openship Cloud, любой VPS (Hetzner, DigitalOcean, Linode, OVH и другие), выделенные серверы или домашние лаборатории, а также конфигурации из нескольких серверов. Приложения деплоятся как обычные Docker-контейнеры, так что вы свободно переходите между провайдерами.
Это бесплатно? А использовать в коммерческих целях можно?Свой хостинг бесплатный (без биллинга). Лицензия Apache 2.0 разрешает использовать, изменять, размещать у себя и распространять — в том числе в коммерческих и закрытых продуктах.
Как выглядит деплой от начала до конца?Запускается один пайплайн: определяет стек (Node, Python, Go, Rust, PHP, Ruby, Java, .NET, Docker, монорепозитории — без всякой настройки; openship.json переопределяет), собирает Docker-образ или bare-релиз, запускает контейнер, доступный только на loopback, и маршрутизирует ваш домен через OpenResty на границе сети с TLS от Let's Encrypt. GitHub-вебхук передеплоивает при каждом пуше в отслеживаемую ветку.
Чем ещё он управляет, кроме самого приложения?Всем бэкендом: Postgres, MySQL, MongoDB, Redis, воркеры, WebSockets и хранилище, плюс домены и wildcard SSL с автопродлением, CDN (HTTP/3, Brotli, мгновенная очистка кеша), встроенный SMTP-сервер для почты с DKIM/SPF/DMARC, бэкапы по расписанию с восстановлением в один клик, а также логи и метрики в реальном времени.
Могут ли им управлять ИИ-агенты или скрипты?Да — есть MCP-эндпоинт для ИИ-агентов плюс REST API. В MCP-инструменты превращаются только те маршруты, которые явно разрешены, каждый вызов повторно проверяет ваши права, а маршруты с учётными данными и токенами инструментами стать не могут.
Что запланировано на будущее?Кластеры из нескольких нод, интерфейс балансировки нагрузки, приватная сеть, продвинутое мониторинг и визуальные CI/CD-пайплайны. Ядро готово к продакшену и активно развивается.
What are similar projects?dokploy, caprover, hivepaas, all-in-one, azerioid-stack-manager, Tracely-ai, coolify, trueforge
Which topics is it in?paas, letsencrypt, ci-cd, reverse-proxy, deployment, tls, redis, postgresql, docker-compose, monitoring, agents, devops
Creator
oblien
Size
143.3 MB
Stars
14.8K
Updated
CommitOct 17Releasev0.9.2Oct 16
Age
7mo
Commits · 90 Days