Start

Install shibumi-server.

Prepare a Linux server and install one fixed release.

Install shibumi-server

Run the installer on the Linux account that will own your deployments.

Requirements#

Linux
Git
Caddy
rootless Podman
Podman Compose through podman compose or podman-compose
a systemd user session

The installer adds Bun if it is missing. On macOS or Windows, SSH into the Linux server first. Enter SSH and sudo passwords in your terminal, never on a website.

Prepare a fresh VPS#

Already have a hardened server with key-only SSH? Skip ahead.

First server? Rent, connect, and harden it step by step.

Rent a VPS. Any provider works (Hetzner, DigitalOcean, Vultr, a homelab box). 1 vCPU and 1 GB RAM run several small apps. Pick a current Debian or Ubuntu LTS image. If the provider asks for an SSH public key at creation, paste yours; that key becomes root's login.
Create a local SSH key if you have none:
sh
```
ssh-keygen -t ed25519
```
The public half is ~/.ssh/id_ed25519.pub. The private half never leaves your machine.
Create the deployment user. Log in as root once, then:
sh
```
adduser deploy
usermod -aG sudo deploy
```
Install your key for that user. From your machine:
sh
```
ssh-copy-id deploy@<server-ip>
```
Add an SSH alias in ~/.ssh/config on your machine. Better than an /etc/hosts entry: it also records the user and key, and Ship accepts the alias everywhere a target is asked.
text
```
Host myvps
  HostName <server-ip>
  User deploy
  IdentityFile ~/.ssh/id_ed25519
```
Now ssh myvps must log in without a password. Fix that before continuing.
Disable password and root login. On the server, edit /etc/ssh/sshd_config:
text
```
PasswordAuthentication no
PermitRootLogin no
```
Then sudo systemctl restart ssh. Keep your current session open and confirm a second ssh myvps still works before closing it.
Let user services survive logout. The deploy service runs in a systemd user session:
sh
```
sudo loginctl enable-linger deploy
```
Install the requirements. On Debian or Ubuntu:
sh
```
sudo apt update
sudo apt install -y git podman podman-compose
```
Caddy comes from its own repository; follow the official install steps.
Point DNS at the server. An A record for your app domain to the server IP, DNS-only (no proxy), so Caddy can issue its own certificate.

Run the installer#

curl -fsSL https://server.shibumistack.dev/install | bash

The installer checks the host before writing anything. It finds a working Compose command, installs one exact npm version from its production lockfile, and disables lifecycle scripts. It adds both command names:

text

~/.local/bin/shis
~/.local/bin/shibumi-server

The docs use shis. Existing scripts can keep using shibumi-server.

~/.local/bin alone isn't enough for non-interactive access: ssh host shis ... often runs without a login shell, so it never picks up ~/.local/bin from ~/.profile or ~/.bashrc. Setup also tries to symlink both commands into /usr/local/bin, asking sudo for a password only if that directory isn't already writable. When sudo isn't available, it appends ~/.local/bin to ~/.profile instead and says so plainly: that fallback only helps sessions the remote shell treats as a login shell, so some non-interactive ssh host shis ... calls still won't find it. Run the printed sudo ln -sf command yourself for a fix that always works.

Files on the server#

text

~/.config/shibumi-server/config.json
~/.config/shibumi-server/secrets.env
~/.config/systemd/user/shibumi-server.service
~/.local/share/shibumi-server/releases/<version>/
~/.local/share/shibumi-server/current

Config and secret files use mode 0600. The service runs the installed release. It does not download a package when it starts.

Check the install#

shis --version
systemctl --user status shibumi-server

A new install has no apps. Continue with Connect project, or use shis add on the server.

Update#

shis checks npm for newer stable releases and suggests this command when one exists:

shis update

Update installs that exact version through the existing setup. Config, secrets, checkouts, and running apps stay in place. A slow or unavailable npm registry does not block other commands. shis serve never checks npm.