OpenShip Self-Hosted Deployment Tutorial: Building a CI/CD Platform with CLI and Docker

OpenShip is an open source, self-hosted application deployment platform with built-in CI/CD and offers a desktop app, web console, and CLI. Its goal is to allow developers to automatically identify the technology stack, build containers, configure services and complete releases after connecting the code warehouse to the server, reducing the work of handwriting pipelines and deploying YAML.

The project covers Node.js, Python, Go, Rust, PHP, Ruby, Java, .NET, Docker and monorepo, and also puts database, domain name, TLS certificate, CDN, email, backup and monitoring in the same interface. It can either connect to OpenShip Cloud or be deployed to your own Linux VPS or dedicated server.

Quick Answer

Install the CLI using npm:

1

npm i -g openship

Start the OpenShip background service:

1

openship up

Open the management interface:

1

openship open

Enter the project directory to be deployed, initialize and publish:

1
2
3

cd your-project
openship init
openship deploy

openship init is used to connect the current directory to the OpenShip project, and openship deploy triggers build and deployment. Before using it on a production server for the first time, it is recommended to use a non-critical item to verify the persistent directory, domain name resolution, certificate, backup and rollback process.

What problem does OpenShip solve?

Manually deploying a web project usually requires handling Git pull, image building, reverse proxy, TLS, environment variables, database, logs, backup and release rollback separately. OpenShip centralizes these tasks into a single deployment platform.

It’s closer to a lightweight PaaS or self-hosted deployment control panel than a standalone CI Runner. Deployment results use standard Docker containers for easy migration between different servers and vendors.

Preparation before installation

If you only have local experience, you can install the CLI on the development machine. When preparing for long-term self-hosting, it is recommended to use a standalone Linux server and confirm in advance:

1. The server can access the code warehouse and mirror source;
2. DNS records can point to the server’s public network address;
3. HTTP, HTTPS and the ports actually required by the platform have been allowed in the firewall;
4. Disk space can accommodate mirrors, databases, persistent volumes and backups;
5. Administrator authentication, key storage and off-site backup have been planned.

OpenShip has access to source code, deployment credentials, environment variables, and databases, so unprotected consoles should not be exposed directly to the public network. Before officially going online, you should read the current version documentation and security instructions, and first verify the upgrade and recovery in an isolated environment.

Method 1: Install via CLI

Official quick start using npm global installation:

1

npm i -g openship

The official also provides Shell installation entrance:

1

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

Before executing a remote script on the server, it is recommended to download and review the script content. After the installation is complete, start the background service:

1

openship up

This command will install OpenShip as a background service and configure startup and automatic restart on exceptions. Need to run when observing the startup log in the foreground:

1

openship up --foreground

Open the console:

1

openship open

Stop the background service:

1

openship stop

Foreground running is more suitable for first-time troubleshooting; after confirming that the configuration and data directory are correct, switch to background service mode.

Method 2: Use Docker Compose

When you want explicit control over containers, networks, and volumes, you can launch the Compose stack from the official repository:

1
2
3
4

git clone https://github.com/oblien/openship.git
cd openship
cp .env.example .env
docker compose up -d

Do not boot to the public network immediately after copying .env.example. First open .env, check all passwords, keys, external addresses, ports, and persistence configurations, replace the example values, and then run Compose.

View service status and logs:

1
2

docker compose ps
docker compose logs -f

Stop the service but keep the volume data:

1

docker compose down

Don’t just add -v without a backup, as it will delete the Compose-managed volume. Before upgrading, you should record the current image or version, export the database, and back up the persistent volume to ensure that you can return to the verified version.

Deploy the first project

Enter the local project directory:

1
2

cd your-project
openship init

The initialization process is used to create or select an OpenShip project and associate the current directory with the project. Trigger deployment after completion:

1

openship deploy

The platform will try to identify the technology stack, build the application and configure the running environment. Even though the official emphasis is on reducing configuration files, the following information should still be clarified before deployment:

• Application listening port and health check path;
• Build commands, startup commands and runtime versions;
• Required environment variables and Secrets;
• Directory that needs to be saved persistently;
• When database migration should be performed.

Auto-detection is suitable for regular projects, but should not replace an understanding of the application startup process. When encountering a build failure, first confirm from the real-time build log whether the detected language, version and command are correct.

Deploy Docker Compose project

OpenShip official instructions can deploy existing Compose files as they are. For projects that include web services, workers, databases, and Redis, this is usually more straightforward than reconfiguring all services.

Check the Compose file before committing for deployment:

1

docker compose config

Local startup verification:

1
2

docker compose up -d
docker compose ps

Special inspection is required:

1. Do not bring the bind mount of the development environment directly to the production environment;
2. Databases and caches should not expose host ports without authentication;
3. Secret should not be hard-coded into compose.yaml;
4. Services should have reasonable health checks and restart strategies;
5. Persistent volumes should be included in backup and recovery testing.

Local Compose can be started, which only proves that the basic configuration of the container is available. Domain names, TLS, external networks, resource limits, and production data migration still need to be independently verified in the OpenShip target environment.

Configure domain name and TLS

OpenShip supports domain name management, Let’s Encrypt, wildcard certificates, and automatic renewal. The general process is:

1. Resolve the domain name to the deployment server at the DNS service provider;
2. Bind the domain name in the OpenShip project;
3. Wait for the platform to apply for and configure the certificate;
4. Verify HTTP to HTTPS jump;
5. Check the certificate chain and renewal status from the external network.

When the certificate application fails, first check whether DNS has taken effect, whether ports 80 and 443 are occupied by other reverse proxies, and whether the CDN proxy mode affects ACME verification. Wildcard certificates generally also involve DNS validation, and the required permissions should be limited to the necessary domain names.

Database, Storage and Backup

Backend capabilities listed by the platform include Postgres, MySQL, MongoDB, Redis, Workers, WebSocket, and Storage. After creating the database, the connection information should be injected into the application through the platform’s Secret or environment variables to avoid submitting it to Git.

The backup function covers databases and volumes, but “scheduled tasks have been set” does not equal “can be restored”. Complete at least one recovery drill before going online:

1. Create a test data;
2. Generate backup manually or regularly;
3. Export the backup outside the server;
4. Restore in an isolated project or test database;
5. Verify that the data, permissions and application version are consistent.

If the backup is only saved on the same disk on the same server, it may still be lost if the hard drive fails or the host is invaded. Production environments should maintain off-site copies and configure encryption and access controls for backup files.

Push-to-deploy and rollback

OpenShip provides push-to-deploy, preview environments, staging/production processes, and rollback. When accessing the code repository, do not give the deployment token more organization or repository permissions than required.

It is recommended to set the production release process as:

1. Pull Request creates a preview environment;
2. Deploy staging after merging;
3. Complete health examinations and necessary tests;
4. Release to production after confirmation;
5. Monitor error rates, resources and key interfaces;
6. Roll back to the previous verified product in case of exception.

Database Schema changes may not be automatically undone as the container rolls back. When designing migrations, backward compatibility steps should be prioritized and the database recovery process should be verified separately from application rollback.

How to choose among the three management methods?

The project also provides REST API and MCP interfaces for integration with automation tools or AI Agents. When creating credentials for automation clients, use independent identities, minimal privileges, and revocable tokens; retain manual confirmation or approval for high-impact operations such as deployment, deletion, and recovery.

The current status and roadmap should be distinguished

The official README describes the core functionality as production-ready and under ongoing development, while making it clear that the documentation is still being refined. Multi-node clusters, load balancing interfaces, private networks, advanced monitoring and visual CI/CD pipelines are listed as follow-up plans.

Therefore, the evaluation should be based on the features actually available in the current release version, and do not treat the roadmap as delivered. For production migration, first verify the capabilities you really need, such as single-node failure recovery, upgrade compatibility, backup export, permission isolation, and audit logs.

FAQ

openship up The console cannot be opened after startup.

First use the foreground mode to observe errors:

1

openship up --foreground

Then check the port occupancy, firewall, service status and logs. If running on a remote server, the address opened by openship open also needs to be reachable from the management side network.

The automatic recognition is built incorrectly

Check the project root directory, lock file, Dockerfile, Compose file, and runtime version declaration. The monorepo also needs to confirm the actual application subdirectory and build context to prevent the platform from selecting the wrong entry in the warehouse root directory.

The domain name has been resolved but the certificate issuance failed.

Verify that DNS returns the target server address, that ports 80/443 are not in use by other services, that the cloud firewall allows external access, and that the CDN or reverse proxy blocks verification requests.

Can the existing production platform be replaced immediately?

Direct overall migration is not recommended. First select a low-risk project that can be rolled back, verify deployment, logs, monitoring, backup and recovery, version upgrades and fault handling, and then gradually expand the scope of use.

Who is OpenShip suitable for?

OpenShip is suitable for individual developers or small teams who want an all-in-one deployment experience on their own Linux servers, but don’t want to maintain CI, reverse proxies, certificates, and database scripts separately for each project. It’s also suitable for environments that want to retain basic portability via Docker.

If an organization already has mature Kubernetes, GitOps, identity governance, and observability systems in place, introducing a new deployment control plane may add duplication of management. This is where you start by comparing permission models, auditing, cluster capabilities, and existing pipeline integration costs.

Summary

OpenShip brings code building, container deployment, domain certificates, databases, backups and monitoring into the same platform and allows management via desktop, web, CLI, API and MCP. The fastest way to experience it is to install the CLI and run openship up. For production self-hosting, it is more suitable to start with an isolated test project, focusing on verifying Secrets, persistence, backup and recovery, upgrades and rollbacks.

Project address: oblien/openship

Official documentation: openship.io/docs