---
name: ship-binary
description: Upload and deploy a pre-built binary to a ship VPS. Handles port allocation, systemd service, env vars, Caddy config, and SQLite backup. Use when deploying a Go binary or other compiled executable.
argument-hint: "<path-to-binary> <app-name> [host-nickname]"
---

# ship-binary

Upload a pre-built binary and deploy it as a systemd service with Caddy reverse proxy.

## Read Config

```bash
python3 -c "
import json, os
cfg = json.load(open(os.path.expanduser('~/.config/ship/config.json')))
nick = '<nickname-or-default>'
h = cfg['hosts'].get(nick, cfg['hosts'][cfg['default']])
print(h['host'])
print(h['domain'])
"
```

## Inputs

- **Binary path** — local path to the compiled binary
- **App name** — short lowercase name, becomes the service name and subdomain (e.g. `foodtracker`)
- **Domain** — defaults to `<app-name>.<base-domain>` from config, ask if different
- **Env vars** — ask if there are any env vars to set (beyond PORT/SHIP_NAME/SHIP_URL)
- **Host** — use default unless specified

## Steps

### 1. Check if app already exists

```bash
ssh <host> "test -f /etc/ship/ports/<app-name> && echo exists || echo new"
```

This determines whether to allocate a new port or reuse the existing one.

### 2. Backup SQLite databases (if app exists)

Before touching anything, check for SQLite files in the app's data directory:

```bash
ssh <host> "find /var/lib/<app-name>/ -name '*.db' 2>/dev/null"
```

If any `.db` files are found, back them up:

```bash
ssh <host> "sudo mkdir -p /var/lib/<app-name>/backups && sudo cp /var/lib/<app-name>/data/<name>.db /var/lib/<app-name>/backups/<name>-\$(date +%Y%m%d-%H%M%S).db"
```

Tell the user what was backed up before proceeding.

### 3. Allocate or retrieve port

**New app** — find the highest port in use and add 1:
```bash
ssh <host> "sudo bash -c 'max=9000; for f in /etc/ship/ports/*; do p=\$(cat \$f 2>/dev/null); [ \"\$p\" -gt \"\$max\" ] && max=\$p; done; port=\$((max+1)); echo \$port | tee /etc/ship/ports/<app-name>; echo \$port'"
```

**Existing app** — reuse the existing port:
```bash
ssh <host> "cat /etc/ship/ports/<app-name>"
```

### 4. Upload binary

```bash
scp <binary-path> <host>:/tmp/<app-name>
ssh <host> "sudo mv /tmp/<app-name> /usr/local/bin/<app-name> && sudo chmod +x /usr/local/bin/<app-name>"
```

### 5. Create work directory and service user

```bash
ssh <host> "sudo mkdir -p /var/lib/<app-name>/data && sudo useradd -r -s /bin/false <app-name> 2>/dev/null || true && sudo chown -R <app-name>:<app-name> /var/lib/<app-name>"
```

### 6. Write env file

Build the env file content merging ship-managed vars with any user-provided vars.
If the file already exists, read it first and merge (new values win, old values survive):

```bash
ssh <host> "sudo cat /etc/ship/env/<app-name>.env 2>/dev/null"
```

Then write merged result:
```bash
ssh <host> "sudo tee /etc/ship/env/<app-name>.env > /dev/null << 'EOF'
PORT=<port>
SHIP_NAME=<app-name>
SHIP_URL=https://<domain>
<user-env-vars>
EOF
sudo chmod 600 /etc/ship/env/<app-name>.env"
```

### 7. Write systemd unit

```bash
ssh <host> "sudo tee /etc/systemd/system/<app-name>.service > /dev/null << 'EOF'
[Unit]
Description=<app-name>
After=network.target

[Service]
Type=simple
User=<app-name>
WorkingDirectory=/var/lib/<app-name>
EnvironmentFile=/etc/ship/env/<app-name>.env
ExecStart=/usr/local/bin/<app-name>
Restart=always
RestartSec=5s
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target
EOF"
```

### 8. Start or restart service

```bash
ssh <host> "sudo systemctl daemon-reload"
```

**New app:**
```bash
ssh <host> "sudo systemctl enable --now <app-name>"
```

**Existing app:**
```bash
ssh <host> "sudo systemctl restart <app-name>"
```

### 9. Write Caddy config

```bash
ssh <host> "sudo tee /etc/caddy/sites-enabled/<app-name>.caddy > /dev/null << 'EOF'
<domain> {
    reverse_proxy 127.0.0.1:<port>
}
EOF
sudo systemctl reload caddy"
```

### 10. Confirm

Tell the user:
- App name, URL, and port
- Whether it was a new deploy or update
- Any SQLite backups made
- Any env vars set

## Notes

- Always back up SQLite before swapping the binary
- Always merge env vars — never replace the whole file
- Use `systemctl restart` for existing apps, `enable --now` for new ones
- The data directory `/var/lib/<app-name>/data/` persists across deploys
- If the user doesn't specify env vars, ask if they need any before deploying