organize deployment configs and documentation

docs/configuration.md

@@ -0,0 +1,44 @@
+# Configuration
+
+ushort accepts TOML and legacy JSON configuration files. TOML is preferred;
+[`config.example.toml`](../config.example.toml) is the maintained reference.
+
+```bash
+ushort config.toml
+ushort legacy-config.json
+```
+
+## Options
+
+| Key | Required | Default | Description |
+|---|---:|---:|---|
+| `base_url` | yes | — | Public URL. Its path becomes the routing prefix. |
+| `api_key` | yes | — | Secret used by list and delete operations. |
+| `host` | no | `0.0.0.0` | Bind address. |
+| `port` | no | `8080` | Bind port. |
+| `db_path` | no | `data/urlshort.db` | SQLite database path. |
+| `retention_days` | no | `0` | Default lifetime for new URLs; zero never expires. |
+| `min_short_length` | no | `6` | Initial generated code length. |
+| `max_short_length` | no | `32` | Maximum generated and accepted code length. |
+| `max_url_length` | no | `2048` | Maximum original URL length. |
+| `max_retention_days` | no | `3650` | Maximum per-URL retention value. |
+| `rate_limit_requests` | no | `60` | Requests allowed per client/window. |
+| `rate_limit_window` | no | `60` | Sliding-window length in seconds. |
+| `production` | no | `false` | Disable embedded frontend routes when a separate server provides them. |
+
+The legacy `short_length` option remains an alias for `min_short_length`.
+
+## Public URL layouts
+
+The same binary supports both common reverse-proxy layouts:
+
+- `base_url = "https://s.example.com"` serves everything at the subdomain
+  root and produces URLs such as `https://s.example.com/aB3xYz`.
+- `base_url = "https://example.com/go/links"` routes only under `/go/links`
+  and produces `https://example.com/go/links/aB3xYz`.
+
+A trailing slash on `base_url` is accepted and normalized. Requests outside a
+configured non-empty path prefix return 404.
+
+Keep real API keys only in the ignored deployment `config.toml`. Never commit
+them or include them in a container image.