ntfy/docs/config-generator-plan.md

# Config Generator for ntfy Docs

## Context

The ntfy config page (`docs/config.md`) documents 60+ server configuration options across many sections. Users often struggle to assemble a working config file. An interactive config generator helps users build a `server.yml`, `docker-compose.yml`, or env vars file by answering guided questions, with real-time preview.

## Files Created

| File | Purpose |
|------|---------|
| `docs/static/js/config-generator.js` | All generator logic (vanilla JS, ~300 lines) |
| `docs/static/css/config-generator.css` | All generator styles (~250 lines) |

## Files Modified

| File | Change |
|------|--------|
| `docs/config.md` | Inserted `## Config generator` HTML block at line 137 (before `## Database options`) |
| `mkdocs.yml` | Added `config-generator.js` to `extra_javascript` and `config-generator.css` to `extra_css` |

## UI Layout

Two-panel side-by-side layout:

- **Left panel**: Collapsible accordion sections with form inputs for config options
- **Right panel** (sticky): Tabs for `server.yml` / `docker-compose.yml` / `Environment variables`, with a copy button. Updates in real-time as the user changes options.
- **Responsive**: Stacks vertically on screens < 900px

## Configuration Sections (Left Panel)

### 1. Basic Setup
- `base-url` (text, placeholder: `https://ntfy.example.com`)
- `listen-http` (text, placeholder: `:80`)
- `behind-proxy` (checkbox)

### 2. Database
- Radio: SQLite (default) vs PostgreSQL
- SQLite → `cache-file` (text, placeholder: `/var/cache/ntfy/cache.db`)
- PostgreSQL → `database-url` (text, placeholder: `postgres://user:pass@host:5432/ntfy`)

### 3. Access Control
- "Enable access control" (checkbox) → shows:
  - `auth-file` (text, placeholder: `/var/lib/ntfy/auth.db`) — hidden if PostgreSQL
  - `auth-default-access` (select: `read-write`, `read-only`, `write-only`, `deny-all`)
  - `enable-login` (checkbox)
  - `enable-signup` (checkbox)
  - Provisioned users (repeatable rows): username, password hash, role (admin/user)
  - Provisioned ACLs (repeatable rows): username, topic pattern, permission (rw/ro/wo/deny)
  - Provisioned tokens (repeatable rows): username, token, label

### 4. Attachments
- "Enable attachments" (checkbox) → shows:
  - `attachment-cache-dir` (text, placeholder: `/var/cache/ntfy/attachments`)
  - `attachment-file-size-limit` (text, placeholder: `15M`)
  - `attachment-total-size-limit` (text, placeholder: `5G`)
  - `attachment-expiry-duration` (text, placeholder: `3h`)

### 5. Message Cache
- `cache-duration` (text, placeholder: `12h`)

### 6. Web Push
- "Enable web push" (checkbox) → shows:
  - `web-push-public-key` (text)
  - `web-push-private-key` (text)
  - `web-push-file` (text, placeholder: `/var/lib/ntfy/webpush.db`) — hidden if PostgreSQL
  - `web-push-email-address` (text)

### 7. Email Notifications (Outgoing)
- "Enable email sending" (checkbox) → shows:
  - `smtp-sender-addr` (text, placeholder: `smtp.example.com:587`)
  - `smtp-sender-from` (text, placeholder: `ntfy@example.com`)
  - `smtp-sender-user` (text)
  - `smtp-sender-pass` (text, type=password)

### 8. Email Publishing (Incoming)
- "Enable email publishing" (checkbox) → shows:
  - `smtp-server-listen` (text, placeholder: `:25`)
  - `smtp-server-domain` (text, placeholder: `ntfy.example.com`)
  - `smtp-server-addr-prefix` (text, placeholder: `ntfy-`)

### 9. Upstream Server
- "iOS users will use this server" (checkbox) → sets `upstream-base-url: https://ntfy.sh`

### 10. Monitoring
- "Enable Prometheus metrics" (checkbox) → sets `enable-metrics: true`

## JavaScript Architecture (`config-generator.js`)

Single vanilla JS file, no dependencies. Key structure:

1. **Config definitions array (`CONFIG`)**: Each entry has `key`, `env`, `type`, `def`, `section`. This is the single source of truth for all three output formats.

2. **`collectValues()`**: Reads all form inputs, returns an object of key→value, filtering out empty values. Handles repeatable rows for auth-users/access/tokens. Respects conditional visibility (skips hidden fields).

3. **`generateServerYml(values)`**: Outputs YAML with section comments. Provisioned users/ACLs/tokens rendered as YAML arrays.

4. **`generateDockerCompose(values)`**: Wraps values as env vars in Docker Compose format. Key transformations:
   - Uses `NTFY_` prefixed env var names from config definitions
   - File paths adjusted for Docker via `DOCKER_PATH_MAP`
   - `$` doubled to `$$` in bcrypt hashes (with comment)
   - Standard boilerplate: `services:`, `image:`, `volumes:`, `ports:`, `command: serve`
   - Provisioned users/ACLs/tokens use indexed env vars (e.g., `NTFY_AUTH_USERS_0_USERNAME`)

5. **`generateEnvVars(values)`**: Simple `export NTFY_KEY="value"` format. Single quotes for values containing `$`.

6. **`updateOutput()`**: Called on every input change. Runs the active tab's generator and updates the `<code>` element.

7. **`initGenerator()`**: Called on DOMContentLoaded, no-ops if `#config-generator` is missing. Sets up event listeners for tabs, accordions, repeatable row add/remove, conditional toggles, and special checkboxes (upstream, metrics).

### Conditional visibility
- Database = PostgreSQL → hide `cache-file`, `auth-file`, `web-push-file`; show `database-url`
- Access control unchecked → hide all auth fields
- Each "enable X" checkbox controls visibility of its section's detail fields via `data-toggle` attribute

### Docker Compose path mapping
- `/var/cache/ntfy/cache.db` → `/var/lib/ntfy/cache.db`
- `/var/cache/ntfy/attachments` → `/var/lib/ntfy/attachments`
- `/var/lib/ntfy/*` → unchanged
- Volume: `./:/var/lib/ntfy`

## CSS Architecture (`config-generator.css`)

Key aspects:

- **Flex layout** with `gap: 24px` for the two-panel layout
- **Sticky right panel**: `position: sticky; top: 76px; align-self: flex-start; max-height: calc(100vh - 100px); overflow-y: auto`
- **Dark mode**: Uses `body[data-md-color-scheme="slate"]` selectors (matching existing pattern in `extra.css`)
- **Accent color**: Uses `var(--md-primary-fg-color)` (`#338574`) for focus states, active tabs, and interactive elements
- **Responsive**: `@media (max-width: 900px)` → column layout, static right panel
- **Accordion**: `.cg-section-header` click toggles `.cg-section.open` which shows/hides `.cg-section-body`
- **Tabs**: `.cg-tab.active` gets accent color border-bottom highlight
- **Code output**: Dark background (`#1e1e1e`) with light text, consistent in both light and dark mode

## HTML Block (in config.md)

~250 lines of HTML inserted at line 137. Pure HTML (no markdown inside). Structure:

```
## Config generator
<div id="config-generator">
  <div id="cg-left">
    <!-- 10 accordion sections with form fields -->
  </div>
  <div id="cg-right">
    <!-- Tab bar + code output + copy button -->
  </div>
</div>
```

## Verification

The docs build was verified with `mkdocs build` — completed successfully with no errors. The generated HTML at `server/docs/config/index.html` contains the config-generator elements.

Manual verification checklist:
1. `cd ntfy && mkdocs serve` — open config page in browser
2. Verify all 10 sections expand/collapse
3. Fill in basic setup → check server.yml output updates
4. Switch tabs → verify docker-compose.yml and env vars render correctly
5. Toggle access control → verify auth fields show/hide
6. Add provisioned users/ACLs/tokens → verify repeatable rows work
7. Switch database to PostgreSQL → verify SQLite fields hide
8. Toggle dark mode → verify styles look correct
9. Resize to mobile width → verify column layout
10. Click copy button → verify clipboard content