Match the signed commit.
The webhook must match its secret, repository, branch, and full SHA. Replayed requests do not deploy.
Self-hosted deploys
Deploy exact
images.
Build committed code on your computer. The server verifies and runs that image on your VPS.
Open source · v0.11.0
›
渋み ship
1 commit ready to push
test passed
check passed
Built and uploaded a1b2c3d (45 MiB, 7818747847bb)
Deployment complete
Checks run before replacement
The server runs these checks even when the app has no test command.
- Verify the webhook, repository, branch, and commit.
- Check free memory and disk space.
- Validate the Compose configuration.
- Verify the uploaded image and run any optional app tests in a temporary container.
- Replace the old container, check the new one's local health endpoint, keep the previous successful image for rollback for up to 12 hours, and remove older or superseded tags.
App tests are optional. Add a command such as bun test only when the project has its own test suite.
Deployment model
One service behind
your existing Caddy.
bun ship builds committed HEAD for the server's Linux platform and uploads it through SSH before pushing Git. The current app stays up during commit, image, platform, and Compose checks. The server retains one previous image for up to 12 hours.
Check host capacity.
Images build on the client. The server still checks available memory and disk before deployment.
Check identity and health.
A mismatched image, invalid Compose config, failed app test, or failed health request stops replacement.
MCPVault
A failed build changed the design.
I maintain MCPVault, an MCP bridge for Obsidian. I started moving its Astro site after Astro 7 changed the Cloudflare path from Pages to Workers.
The first VPS build exhausted memory before health checks ran. That failure moved image builds to the client and added memory, disk, timeout, and systemd limits.
Visit MCPVault →Install
Prepare your
server.
Use a Linux VPS or homelab server reachable over SSH. Project setup can install the server after confirmation, or you can install it directly.
›
渋み shis (shibumi-server)
Install shibumi-server on this server?Yes
Installed shibumi-server 0.11.0
Launcher: ~/.local/bin/shis
From project root: curl -fsSL https://shibumistack.dev/install/ship.sh | sh
The installer checks the host, then stages one release with lockfile-pinned production dependencies. Interactive commands suggest shis update when npm reports a newer stable version. serve skips that check, and registry failures do not block local commands.
shibumi-server uninstall removes the service and installed code while preserving config and secrets. Add --purge to remove those too after confirmation. App checkouts, containers, Caddy, and GitHub settings stay untouched.
Project
Connect from
your project.
Run the installer from the local Git root. It reads the domain, repository, branch, Compose service, and health path, then registers the app through SSH. When container files are missing, setup can generate a Bun Dockerfile, loopback-only compose.yaml, and .dockerignore.
›
渋み ship setup
SSH target (user@server or alias)deploy@example-vps
App domainsub.example.com
PlanConnect to deploy@example-vps, save target for this project
Install or upgrade shibumi-server (sudo password once)
Register sub.example.com
Commit and push deployment files
Deploys run on: bun ship
Install or upgrade shibumi-server (sudo password once)
Register sub.example.com
Commit and push deployment files
Deploys run on: bun ship
Run setup?Yes
Registered sub.example.com, Caddy route live
Deployment setup ready for sub.example.com
Setup asks two questions, then prints a plan it runs on a single confirm. Nothing is written before you accept the plan, and if DNS is not ready, setup keeps the generated files and prints the command needed to resume. Deploys run on bun ship; bun ship:webhook switches to push-to-deploy later if you want it.
shis add sub.example.com remains available for server operators and automation. Add --dry-run to preview setup without writing config or secrets, invoking sudo, or changing Caddy or systemd. shis set-repository <app> <repository> repoints an already-registered app: the old checkout moves to .bak and the new repository is cloned in its place.
Ship
Build locally,
then upload.
The project owns its Ship client:
bun shipSetup registers the app through confirmed SSH and writes commit-safe shibumi-server.json. GitHub CLI is used only for creating a missing repository, or when bun ship:webhook opts the project into push-to-deploy.
Normal runs check Git, run project checks, build committed HEAD for the server platform, and upload the labeled image. Ship pushes Git after upload and follows deployment status. Caddy retries the loopback upstream for up to 20 seconds during replacement. After a server update, shis caddy-refresh <app-id> adds this retry budget to an existing managed route without replacing its other Caddy settings. Existing domains keep their old upstream until the first deployment passes health and the user approves cutover.
Ship can run newer reviewed client source for the current deployment. It saves that source to tracked scripts/ship.ts only after success. Network errors keep the installed client, and local edits are never replaced.
Use bun ship --rebuild for a no-cache build, bun ship:logs for the latest deployment log, or bun ship --rollback to restore the retained image. Add Ship to an existing project.
Linux host
Install on your server.
Requires Linux with Bun, Git, rootless Podman, Caddy, and systemd. On macOS or Windows, SSH into your Linux VPS or homelab server first.