Add an app from the server

This is the server-operator path, one domain and branch at a time. Most users should start from the local project instead, which calls this same registration command over SSH.

Before setup#

Your repository needs a Compose file and a service with a loopback health endpoint. Point domain DNS toward the server or use Cloudflare proxying.

Preview without changes#

shis add example.com --dry-run

Dry run performs DNS detection, prompts, port selection, checkout validation, and Caddy detection. It does not write config or secrets, invoke sudo, or change Caddy and systemd.

Register#

shis add example.com

Interactive setup asks for repository and checkout, assigns the first free port above 9000, and previews Caddy choices. Public repositories may be cloned.

Private repositories need non-interactive read access for the server deployment user. GitHub CLI can provide HTTPS credentials:

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

Run these commands on the server as the same user that runs shibumi-server. A repository-scoped read-only SSH deploy key also works. Verify git ls-remote succeeds before registration.

Existing domains preserve their current upstream by default. Shibumi adds only its webhook route until a healthy first deployment and explicit cutover.

If the checkout path already exists but its Git origin points at a different repository, add offers to move it to <checkout>.bak and clone the requested repository fresh instead of failing outright. --yes accepts that move; the offer is refused only when <checkout>.bak already exists. To repoint an app that is already registered, use shis set-repository rather than removing and re-adding it.

Automation#

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

A GitHub tree URL selects its branch directly:

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

Equivalent explicit form uses --repository github:owner/repository --ref refs/heads/shibumi. Domain and branch names remain independent. Each domain accepts webhooks only for its configured branch.

Other optional flags select Compose file, Compose frontend, service, and health path. Append an app-owned test command after --:

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

Test arguments execute directly in the service container. They are never interpreted as a shell string.

Run setup again#

Repeating the same registration validates stored settings, preserves checkout and webhook secret, skips Caddy mutation, and restarts the service. Conflicting settings fail closed.