Add an app from the server

This path is for server operators and automation. Most people should start from the local project, which runs the same registration over SSH and then sets up deployment.

Before you start#

The repository needs a Compose file and a service with a loopback health endpoint. Point the domain at the server, directly or through Cloudflare.

Preview without changing the server#

shis add example.com --dry-run

Dry run checks DNS and Caddy, asks the normal questions, picks a port, and validates the checkout. It does not write config or secrets, run sudo, or change Caddy and systemd.

Register the app#

shis add example.com

Setup asks for the repository and checkout. It picks the first free port above 9000 and shows the Caddy change before applying it. It can clone public repositories.

For a private repository, give the deployment user non-interactive read access. GitHub CLI can set up HTTPS credentials:

gh auth login
gh auth setup-git
git ls-remote https://github.com/owner/private-repo.git

Run those commands as the same user that runs shibumi-server. A read-only SSH deploy key also works. Registration will fail until git ls-remote works without a prompt.

If Caddy already serves the domain, Shibumi leaves that upstream in place. It adds only the webhook route. You choose when to switch traffic after the first healthy deploy.

Automation#

shis add example.com \
  --repository github:owner/repository \
  --checkout /home/deploy/shibumi/example-com \
  --port 9100

A GitHub tree URL selects its branch:

shis add staging.example.com \
  --repository https://github.com/owner/repository/tree/shibumi \
  --checkout /home/deploy/shibumi/staging-example-com \
  --port 9101

The equivalent explicit option is --repository github:owner/repository --ref refs/heads/shibumi. Domain and branch names do not have to match. Each domain accepts webhooks only for its configured branch.

You can also set the Compose file, Compose command, service, and health path. Put an app-owned test command after --:

shis add example.com \
  --repository github:owner/repository \
  --checkout /home/deploy/shibumi/example-com \
  --port 9100 \
  -- bun test

Shibumi passes test arguments directly to the container. It does not build a shell command from them.

Running setup again#

Repeating the same registration keeps the checkout, webhook secret, and Caddy config, then restarts the service. Conflicting settings stop with an error instead of overwriting the app.