Openship

--- ## 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](https://github.com/oblien/openship/releases/latest/download/Openship-arm64.dmg) | | **macOS** (Intel) | [Openship-x64.dmg](https://github.com/oblien/openship/releases/latest/download/Openship-x64.dmg) | | **Windows** | [Openship-win32-x64.zip](https://github.com/oblien/openship/releases/latest/download/Openship-win32-x64.zip) | | **Linux** | [Openship.AppImage](https://github.com/oblien/openship/releases/latest/download/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. ```bash curl -fsSL https://get.openship.io | sh # install (or: npm i 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: ```bash 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:** - **On Linux with Docker → Compose mode** (the default). Brings up the full stack — Postgres, Redis, API, dashboard, and a containerized **OpenResty edge on :80/:443** — from published images. This is the flavor that **hosts your deployed apps on the same box**, with automatic domains + Let's Encrypt TLS. Force it with `--compose`. - **Everywhere else → bare mode** (macOS, Windows, or Linux without Docker). A single lightweight process with an embedded database — an always-on control plane that **deploys apps out to a server (SSH) or Cloud**, like the desktop app but always on and login-required. Force it with `--bare`. 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: > > ```bash > 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:** ```bash cd your-project openship init # link this directory to a project openship deploy ``` Full server guide + complete CLI reference: **[openship.io/docs](https://openship.io/docs)**. Shell completion (bash/zsh/fish) Two ways to enable Tab-completion for `openship`: | | Setup | Trade-off | |---|---|---| | **Static file** (recommended) | `openship completion > ` | Instant shell startup. Regenerate after upgrading to pick up newly added commands. | | **Live-sourced** | add `source <(openship completion )` to your shell config | Always reflects the currently installed version. Adds a small delay to every new shell session. | **Static file:** ```bash 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): ```bash 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: ```bash 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](https://openship.io/docs/troubleshooting/host-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: - **Desktop app** — full GUI, real-time logs, one-click everything. Best for solo. - **Web dashboard** — the same UI in the browser, built for teams. - **CLI** — scriptable and CI-friendly; also how you install and manage a self-hosted instance. 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](https://openship.io/docs). > [!NOTE] > The docs are actively being filled out. If something's missing or unclear, [contributions](CONTRIBUTING.md) 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](docs/monitoring.md) | | **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 - **Openship Cloud** — managed, auto-scaling, zero setup - **Any VPS** — Hetzner, DigitalOcean, Linode, OVH, and the rest - **Dedicated servers** — bare metal, colo, homelab - **Multi-server** — spread workloads across machines 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](CONTRIBUTING.md). --- ## Security Found a vulnerability? We welcome your report — please disclose it **privately**, never in a public issue, PR, or discussion. - **Report it here (preferred):** [Report a vulnerability](https://github.com/oblien/openship/security/advisories/new) — a private GitHub advisory, visible only to you and the maintainers. - Scope, what to include, and our response/disclosure process: [SECURITY.md](SECURITY.md). Good-faith security research is **authorized** under our [safe-harbor policy](SECURITY.md#safe-harbor), and we're happy to credit valid first reports. ## License Openship is **open-source** software, licensed under the [Apache License 2.0](LICENSE). 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](LICENSE) for the full text.