summaryrefslogtreecommitdiffstats
path: root/DESIGN_SPEC.md
diff options
context:
space:
mode:
authorbndw <ben@bdw.to>2026-01-24 09:48:34 -0800
committerbndw <ben@bdw.to>2026-01-24 09:48:34 -0800
commit5861e465a2ccf31d87ea25ac145770786f9cc96e (patch)
tree4ac6b57a06b46d8492717b235909f9e0db0b4f22 /DESIGN_SPEC.md
parentef37850c7090493cf2b26d2e565511fe23cc9bfc (diff)
Rename project from deploy to ship
- Rename module to github.com/bdw/ship - Rename cmd/deploy to cmd/ship - Update all import paths - Update config path from ~/.config/deploy to ~/.config/ship - Update VPS env path from /etc/deploy to /etc/ship - Update README, Makefile, and docs
Diffstat (limited to 'DESIGN_SPEC.md')
-rw-r--r--DESIGN_SPEC.md16
1 files changed, 8 insertions, 8 deletions
diff --git a/DESIGN_SPEC.md b/DESIGN_SPEC.md
index e8bb197..51342d4 100644
--- a/DESIGN_SPEC.md
+++ b/DESIGN_SPEC.md
@@ -20,7 +20,7 @@ deploy init --host user@your-vps-ip
20# - Detect OS (Ubuntu/Debian supported) 20# - Detect OS (Ubuntu/Debian supported)
21# - Install Caddy from official repository 21# - Install Caddy from official repository
22# - Configure Caddy to import `/etc/caddy/sites-enabled/*` 22# - Configure Caddy to import `/etc/caddy/sites-enabled/*`
23# - Create `/etc/deploy/env/` directory for env files 23# - Create `/etc/ship/env/` directory for env files
24# - Create `/etc/caddy/sites-enabled/` directory 24# - Create `/etc/caddy/sites-enabled/` directory
25# - Enable and start Caddy service 25# - Enable and start Caddy service
26# - Verify installation 26# - Verify installation
@@ -40,7 +40,7 @@ deploy init --host user@your-vps-ip
40# This will SSH to the VPS and: 40# This will SSH to the VPS and:
41# - Install Caddy 41# - Install Caddy
42# - Configure Caddy to use sites-enabled pattern 42# - Configure Caddy to use sites-enabled pattern
43# - Create /etc/deploy/env/ directory for env files 43# - Create /etc/ship/env/ directory for env files
44# - Enable and start Caddy 44# - Enable and start Caddy
45# 45#
46# State is stored locally at ~/.config/deploy/state.json 46# State is stored locally at ~/.config/deploy/state.json
@@ -273,9 +273,9 @@ All deployment state stored locally at `~/.config/deploy/state.json`:
273``` 273```
274 274
275### Environment Files (VPS) 275### Environment Files (VPS)
276Environment variables written to `/etc/deploy/env/{appname}.env` on VPS for systemd to read: 276Environment variables written to `/etc/ship/env/{appname}.env` on VPS for systemd to read:
277```bash 277```bash
278# /etc/deploy/env/myapi.env (generated from state.json) 278# /etc/ship/env/myapi.env (generated from state.json)
279PORT=8001 279PORT=8001
280DB_HOST=localhost 280DB_HOST=localhost
281DB_PORT=5432 281DB_PORT=5432
@@ -297,7 +297,7 @@ ENVIRONMENT=production
297- Checks if Caddy is already installed (skip if present) 297- Checks if Caddy is already installed (skip if present)
298- Installs Caddy via official APT repository 298- Installs Caddy via official APT repository
299- Creates `/etc/caddy/Caddyfile` with `import /etc/caddy/sites-enabled/*` 299- Creates `/etc/caddy/Caddyfile` with `import /etc/caddy/sites-enabled/*`
300- Creates directory structure: `/etc/deploy/env/`, `/etc/caddy/sites-enabled/` 300- Creates directory structure: `/etc/ship/env/`, `/etc/caddy/sites-enabled/`
301- Enables and starts Caddy 301- Enables and starts Caddy
302- Runs health check (verify Caddy is running) 302- Runs health check (verify Caddy is running)
303- Initializes local state file at `~/.config/deploy/state.json` if not present 303- Initializes local state file at `~/.config/deploy/state.json` if not present
@@ -343,7 +343,7 @@ All steps executed remotely on VPS via SSH:
3434. Create system user (e.g., `myapp`) 3434. Create system user (e.g., `myapp`)
3445. Create working directory (`/var/lib/myapp`) 3445. Create working directory (`/var/lib/myapp`)
3456. Copy binary to `/usr/local/bin/myapp` 3456. Copy binary to `/usr/local/bin/myapp`
3467. Create env file at `/etc/deploy/env/myapp.env` with PORT and any user-provided vars 3467. Create env file at `/etc/ship/env/myapp.env` with PORT and any user-provided vars
3478. Set env file permissions (0600, owned by app user) 3478. Set env file permissions (0600, owned by app user)
3489. Generate systemd unit at `/etc/systemd/system/myapp.service` with EnvironmentFile 3489. Generate systemd unit at `/etc/systemd/system/myapp.service` with EnvironmentFile
34910. Generate Caddy config at `/etc/caddy/sites-enabled/myapp.caddy` pointing to localhost:port 34910. Generate Caddy config at `/etc/caddy/sites-enabled/myapp.caddy` pointing to localhost:port
@@ -376,7 +376,7 @@ All steps executed remotely on VPS via SSH:
376/var/lib/myapp/ # Working directory 376/var/lib/myapp/ # Working directory
377/etc/systemd/system/myapp.service # Systemd unit 377/etc/systemd/system/myapp.service # Systemd unit
378/etc/caddy/sites-enabled/myapp.caddy # Caddy config 378/etc/caddy/sites-enabled/myapp.caddy # Caddy config
379/etc/deploy/env/myapp.env # Environment variables (0600 permissions) 379/etc/ship/env/myapp.env # Environment variables (0600 permissions)
380 380
381/var/www/mysite/ # Static site files 381/var/www/mysite/ # Static site files
382/etc/caddy/sites-enabled/mysite.caddy # Caddy config 382/etc/caddy/sites-enabled/mysite.caddy # Caddy config
@@ -550,7 +550,7 @@ deploy list
550- Use systemd security hardening (NoNewPrivileges, PrivateTmp, ProtectSystem) 550- Use systemd security hardening (NoNewPrivileges, PrivateTmp, ProtectSystem)
551- Static sites served as www-data 551- Static sites served as www-data
552- Caddy automatically handles TLS cert management 552- Caddy automatically handles TLS cert management
553- Environment files stored at `/etc/deploy/env/{app}.env` with 0600 permissions 553- Environment files stored at `/etc/ship/env/{app}.env` with 0600 permissions
554- Env files owned by the app's system user 554- Env files owned by the app's system user
555- `deploy env` command masks sensitive values when displaying (shows `API_KEY=***`) 555- `deploy env` command masks sensitive values when displaying (shows `API_KEY=***`)
556- Consider using external secret management for production (out of scope for v1) 556- Consider using external secret management for production (out of scope for v1)