document deployment

.rdoc_options

@@ -0,0 +1 @@
+markup: markdown

config/environments/development.rb

@@ -37,6 +37,7 @@ Rails.application.configure do
   # Make template changes take effect immediately.
   config.action_mailer.perform_caching = false
 
+  # You can use Mailpit for SMTP in development - https://github.com/axllent/mailpit
   config.action_mailer.delivery_method = :smtp
   config.action_mailer.smtp_settings = {
     address: "localhost",

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.