Connect a project

Each project owns its deployment setup: a checked-in scripts/ship.ts client and a commit-safe shibumi-server.json file.

Add Ship to the project#

From the local Git root:

curl -fsSL https://shibumistack.dev/install/ship.sh | sh

The installer refuses to run outside a Git root. It never overwrites local edits to scripts/ship.ts. Setup can install or upgrade shibumi-server, register the app, and configure GitHub through SSH. You do not need to run shis add first.

If the repository has no tracked Compose file, setup can generate Dockerfile, compose.yaml, and .dockerignore from standard Bun scripts. Review, commit, and push those files. Then run bun ship:setup again. Existing files stay untouched.

Run first setup#

bun ship:setup

Use the user@server target or SSH alias you already use. Password login works. Enter the password once per run, and Ship reuses the temporary SSH connection.

SSH targets stay in ~/.config/shibumi/config.json, or $XDG_CONFIG_HOME/shibumi/config.json, with mode 0600. They are not committed. Projects with one saved server reuse it; projects with several saved servers show a picker. Setup runs ~/.local/bin/shibumi-server remotely and writes only sanitized project config.

Choose Run bun ship or Deploy every GitHub push.

• Run bun ship builds locally, uploads the image, and asks the server to deploy over SSH. If GitHub CLI is signed in, setup disables the matching webhook. GitHub access never blocks shipping.
• Deploy every GitHub push switches the server to build mode and creates, repairs, enables, and tests the webhook. Its secret stays in memory and on the server.

The committed shibumi-server.json has the deployment trigger, app ID, repository, branch, webhook URL, service, app port, health path, and server hostname. It has no secrets, checkout paths, SSH users, aliases, or credentials.

Ship#

Local prebuilt shipping needs Colima, Docker CLI, Docker Compose, and Buildx. On macOS:

brew install colima docker docker-compose docker-buildx
colima start
docker info
docker compose version
docker buildx version

Then ship from the project root:

bun ship

Ship checks the build tools, Git state, and project checks before asking for confirmation. If Docker config names an unavailable credential helper, it offers to remove that stale reference after writing a mode-0600 backup. Non-interactive runs print manual recovery steps instead.

Ship creates its build context from committed HEAD with git archive. Local files, ignored files, credentials, and machine-built node_modules stay out. It builds for the server's Linux platform, labels the image with repository, app, commit, Git tree, and platform, then uploads it over SSH. Git push happens only after upload succeeds.

In direct mode, Ship asks the server to deploy the exact commit and follows its status. In GitHub mode, it waits for the webhook after a new push. If HEAD is already pushed, either mode can redeploy it directly.

Docker keeps layer cache. Use bun ship --rebuild for a no-cache build. Git submodules fail closed because git archive cannot prove their nested content.

Agents can run bun ship -y when the routine confirmation is safe to accept. Clean-tree checks, project checks, image verification, and failures still run. Missing SSH, GitHub, domain, registration, or cutover prerequisites stop and tell the agent to ask you.

Change setup later#

bun ship:setup

This updates project config or changes the deployment trigger. Automation can choose directly:

bun ship:setup --trigger ship
bun ship:setup --trigger github-push

Change the SSH target with git config --local shibumi.server user@server.

Update the client#

Before each deploy, Ship checks the mutable latest pointer against its reviewed immutable source. When a newer client exists, it offers to run that version now. After a successful deployment, it updates tracked scripts/ship.ts and leaves the change unstaged for review. bun ship -y accepts that update automatically.

Network failures keep the current client. Unknown local edits are never overwritten. Server setup, webhook, SSH target, and shibumi-server.json stay unchanged.

Manual update:

bun ship:update