Manual & development installation
Run the published Compose stack yourself or install an isolated development build.
For the standard guided installation, use Installation. This page covers installations where you manage the Compose configuration or build OpenShip from source.
Manual Docker Compose
Requirements: a Linux host with Docker and Docker Compose, Git, and appropriate permissions to manage the host Docker daemon. The edge uses host networking.
Obtain the self-hosted configuration
git clone https://github.com/oblien/openship.git
cd openship
cp .env.example .envUse docker/docker-compose.yml. The root docker-compose.yml is the from-source SaaS control plane;
it is not the self-hosted application stack.
Configure secrets and access
Edit .env before starting. Set the required secrets and retain a protected copy with your recovery
material. Pin OPENSHIP_VERSION to a published release for reproducible upgrades.
For remote access, configure OPENSHIP_PUBLIC_URL. Set TRUST_PROXY=true when using your trusted reverse
proxy. An incorrect public URL can allow the dashboard to load while authentication fails.
Start and verify
docker compose --env-file .env -f docker/docker-compose.yml up -dThe stack pulls published images and runs Postgres, Redis, the API (4000), dashboard (3001), and the
OpenResty edge (80/443). Open the configured dashboard URL and create the administrator account.
The API mounts the Docker socket. Treat access to the control plane as privileged host access.
Configure host operations
Manual Compose startup does not provision the container-to-host SSH channel. Follow Host operations
from the container in .env.example if you need host port takeover, the host terminal, mail, or other
host-level operations. Verify the channel using the
host-channel troubleshooting guide.
Update the manual stack
Back up control-plane data and preserve .env, then change the pinned version and run:
docker compose --env-file .env -f docker/docker-compose.yml pull
docker compose --env-file .env -f docker/docker-compose.yml up -dCheck service health and authentication after upgrading. Follow updates for the release and recovery process.
To build the stack from your checkout instead of pulling releases, add
-f docker/docker-compose.build.yml and use up -d --build.
Isolated development build
A development installation builds the CLI from source and creates a separate openship-dev command.
It requires Bun and Git, and enough CPU/memory to compile the dashboard.
curl -fsSL https://get.openship.io/dev | shChoose a branch or tag by setting OPENSHIP_REF on the shell running the script:
curl -fsSL https://get.openship.io/dev | OPENSHIP_REF=my-branch shopenship-dev
openship-dev up
openship-dev updateDevelopment installs use ~/.openship-dev, separate configuration and data, and their own service.
They are unverified source builds rather than signed release assets. Use a published release for production.