diff options
| -rw-r--r-- | README.md | 59 |
1 files changed, 26 insertions, 33 deletions
| @@ -1,43 +1,39 @@ | |||
| 1 | # Ship | 1 | # Ship |
| 2 | 2 | ||
| 3 | Deploy Go binaries and static sites to a VPS with automatic HTTPS. No agent on the server — just SSH, systemd, and Caddy. | 3 | Deploy Go binaries and static sites to a VPS. Automatic HTTPS. No daemon. Just SSH, systemd, and Caddy doing their jobs. |
| 4 | 4 | ||
| 5 | ## How it works | 5 | ## How it works |
| 6 | 6 | ||
| 7 | Ship is a set of Claude skills. Instead of a rigid CLI that bakes in assumptions, Claude reasons about what to do using a family of narrow, composable skills. The server is the source of truth — no local state file that can go stale. | 7 | Ship is a set of Claude skills. Tell Claude what to deploy. Claude handles it. Server is source of truth — ask Claude what's running and it checks the server, not a file that lies to you. |
| 8 | 8 | ||
| 9 | ## Skills | 9 | ## Skills |
| 10 | 10 | ||
| 11 | | Skill | What it does | | 11 | | Skill | What it does | |
| 12 | |-------|-------------| | 12 | |-------|-------------| |
| 13 | | `/ship-setup` | One-time VPS config. Installs Caddy, creates directories, saves host to `~/.config/ship/config.json` | | 13 | | `/ship-setup` | One-time VPS setup. Installs Caddy, saves host config | |
| 14 | | `/ship-status` | Show all running apps, ports, domains, and disk usage — derived live from server | | 14 | | `/ship-status` | What's running, what port, how much disk. Asks server directly | |
| 15 | | `/ship-deploy` | Deploy a binary or static site — orchestrates the skills below | | 15 | | `/ship-deploy` | Deploy something. Claude asks what it needs to know | |
| 16 | | `/ship-binary` | Upload a pre-built binary, configure systemd + Caddy, back up SQLite | | 16 | | `/ship-binary` | Upload binary, wire up systemd + Caddy, back up SQLite first | |
| 17 | | `/ship-static` | Rsync a dist folder, configure Caddy to serve it | | 17 | | `/ship-static` | Rsync dist folder, Caddy serves it | |
| 18 | | `/ship-env` | Read/write env vars with merge semantics — never wipes existing vars | | 18 | | `/ship-env` | Read/write env vars. Never wipes what's already there | |
| 19 | | `/ship-caddy` | Manage per-app Caddyfile — validates before reloading | | 19 | | `/ship-caddy` | Manage per-app Caddy config. Validates before reloading | |
| 20 | | `/ship-service` | systemd control: start, stop, restart, logs | | 20 | | `/ship-service` | Start, stop, restart, logs | |
| 21 | 21 | ||
| 22 | ## Install | 22 | ## Install |
| 23 | 23 | ||
| 24 | Copy the `skills/` directory into `~/.claude/skills/`: | ||
| 25 | |||
| 26 | ```bash | 24 | ```bash |
| 27 | cp -r skills/ship-* ~/.claude/skills/ | 25 | cp -r skills/ship-* ~/.claude/skills/ |
| 28 | ``` | 26 | ``` |
| 29 | 27 | ||
| 30 | ## Quick start | 28 | ## Quick start |
| 31 | 29 | ||
| 32 | ### 1. Set up your VPS | 30 | ### 1. Set up VPS |
| 33 | 31 | ||
| 34 | ``` | 32 | ``` |
| 35 | /ship-setup | 33 | /ship-setup |
| 36 | ``` | 34 | ``` |
| 37 | 35 | ||
| 38 | Claude asks for SSH host, domain, and nickname. Saves to `~/.config/ship/config.json`. Installs Caddy on the server. | 36 | Claude asks for SSH host, domain, nickname. Done. Or skip Claude entirely: |
| 39 | |||
| 40 | Or run the script directly: | ||
| 41 | 37 | ||
| 42 | ```bash | 38 | ```bash |
| 43 | bash ~/.claude/skills/ship-setup/setup.sh ubuntu@1.2.3.4 example.com prod --default | 39 | bash ~/.claude/skills/ship-setup/setup.sh ubuntu@1.2.3.4 example.com prod --default |
| @@ -49,19 +45,17 @@ bash ~/.claude/skills/ship-setup/setup.sh ubuntu@1.2.3.4 example.com prod --defa | |||
| 49 | /ship-deploy | 45 | /ship-deploy |
| 50 | ``` | 46 | ``` |
| 51 | 47 | ||
| 52 | Claude asks what you're deploying (binary or static site), where it is, what to call it, and any env vars. Handles the rest. | 48 | Claude asks a few questions. Deploys. You go touch grass. |
| 53 | 49 | ||
| 54 | ### 3. Check status | 50 | ### 3. Check what's running |
| 55 | 51 | ||
| 56 | ``` | 52 | ``` |
| 57 | /ship-status | 53 | /ship-status |
| 58 | ``` | 54 | ``` |
| 59 | 55 | ||
| 60 | Shows all running apps, ports, URLs, and disk usage — no local state file, reads directly from server. | ||
| 61 | |||
| 62 | ## Config | 56 | ## Config |
| 63 | 57 | ||
| 64 | `~/.config/ship/config.json` — created by `/ship-setup`. Supports multiple hosts: | 58 | `~/.config/ship/config.json` — lives on your machine, created by `/ship-setup`. |
| 65 | 59 | ||
| 66 | ```json | 60 | ```json |
| 67 | { | 61 | { |
| @@ -79,27 +73,26 @@ Shows all running apps, ports, URLs, and disk usage — no local state file, rea | |||
| 79 | } | 73 | } |
| 80 | ``` | 74 | ``` |
| 81 | 75 | ||
| 82 | Deploy to a specific host: "deploy foodtracker to staging" | 76 | Multiple hosts supported. "Deploy to staging" just works. |
| 83 | 77 | ||
| 84 | ## Server layout | 78 | ## Server layout |
| 85 | 79 | ||
| 86 | ``` | 80 | ``` |
| 87 | /usr/local/bin/<name> # binary | 81 | /usr/local/bin/<name> # binary |
| 88 | /var/lib/<name>/ # work directory | 82 | /var/lib/<name>/data/ # persistent data (SQLite lives here) |
| 89 | /var/lib/<name>/data/ # persistent data (SQLite lives here) | 83 | /var/lib/<name>/backups/ # SQLite backups before each deploy |
| 90 | /var/lib/<name>/backups/ # SQLite backups (made before each binary swap) | 84 | /var/www/<name>/ # static site files |
| 91 | /var/www/<name>/ # static site files | 85 | /etc/systemd/system/<name>.service # systemd unit |
| 92 | /etc/systemd/system/<name>.service # systemd unit | 86 | /etc/caddy/sites-enabled/<name>.caddy # Caddy config |
| 93 | /etc/caddy/sites-enabled/<name>.caddy # per-app Caddy config | 87 | /etc/ship/env/<name>.env # env vars |
| 94 | /etc/ship/env/<name>.env # environment variables | 88 | /etc/ship/ports/<name> # allocated port |
| 95 | /etc/ship/ports/<name> # allocated port number | ||
| 96 | ``` | 89 | ``` |
| 97 | 90 | ||
| 98 | ## Requirements | 91 | ## Requirements |
| 99 | 92 | ||
| 100 | - VPS running Ubuntu 20.04+ or Debian 11+ | 93 | - Ubuntu 20.04+ or Debian 11+ |
| 101 | - SSH access | 94 | - SSH access |
| 102 | - Claude Code with skills support | 95 | - Claude Code |
| 103 | 96 | ||
| 104 | ## License | 97 | ## License |
| 105 | 98 | ||
