document deployment

docs/DEPLOYMENT.md

@@ -0,0 +1,75 @@
+# Deployment (Kamal)
+
+We deploy with Kamal. You do NOT need to manually set up web servers or Docker
+on the VM. `kamal setup` provisions everything.
+
+## Requirements
+
+### Local machine
+- Ruby + Bundler
+- Docker (for building images)
+- SSH key access to the VM
+- Registry credentials (see `config/deploy.yml`)
+
+### Remote VM
+- Bare VM with SSH access
+- Open ports: 22, 80, 443
+- A domain name pointing at the VM (for SSL)
+
+## Configure
+
+Update `config/deploy.yml`:
+
+```yaml
+service: sanasto-wiki
+image: your-registry/sanasto-wiki
+
+servers:
+  web:
+    - your-server-ip
+
+proxy:
+  ssl: true
+  host: sanasto.example.com
+
+registry:
+  server: ghcr.io
+  username: your-github-username
+
+ssh:
+  user: deploy
+```
+
+Set the registry password:
+
+```bash
+export KAMAL_REGISTRY_PASSWORD="your-token"
+```
+
+Make sure `config/master.key` is present locally.
+
+## First deploy
+
+```bash
+bundle exec kamal setup
+```
+
+## Regular deploys
+
+```bash
+bundle exec kamal deploy
+```
+
+## Useful commands
+
+```bash
+bundle exec kamal app logs --follow
+bundle exec kamal app details
+bundle exec kamal app exec --interactive --reuse "bin/rails console"
+bundle exec kamal rollback
+```
+
+## Initial app setup
+
+Visit `https://your-domain/setup` once after the first deploy to create the
+admin account.