Feature: Admin Onboarding Wizard & Configuration Improvements

## Summary

This issue proposes improvements to the first-time admin experience and configuration system, inspired by industry best practices and Community Solid Server (CSS). The primary goal is to make JSS more approachable for new administrators while maintaining flexibility for advanced users.

## Current State

JSS already has a solid configuration foundation:

| Layer | Method | Priority |
|-------|--------|----------|
| Defaults | Hardcoded in `src/config.js` | Lowest |
| Config file | `-c config.json` | Low |
| Environment variables | `JSS_*` prefix | Medium |
| CLI arguments | `--port`, `--idp`, etc. | Highest |

**Existing features:**
- `jss init` - Interactive CLI wizard for basic setup
- `--print-config` - Debug/inspect current configuration
- 30+ configurable options (port, SSL, IdP, quotas, federation, etc.)

**Current gaps:**
- No web-based first-run experience
- No preset configurations for common use cases
- No web-based configuration generator
- First-time users must use CLI before seeing any UI

---

## Proposal 1: Web-Based First-Run Onboarding Wizard (Primary)

### Problem

When a new admin starts JSS for the first time, they must:
1. Read documentation to understand options
2. Run `jss init` or manually create a config
3. Start the server
4. Then figure out how to create their first account/pod

Most modern self-hosted software detects first-run and presents a guided setup wizard in the browser.

### Proposed Solution

When the server starts and detects no existing setup (no accounts, no pods, or a missing `.setup-complete` marker), redirect all requests to `/setup` which presents a step-by-step wizard:

```
Step 1: Welcome
┌─────────────────────────────────────────────────────────┐
│   Welcome to JavaScript Solid Server                    │
│                                                         │
│   Let's configure your server in a few simple steps.   │
│                                                         │
│   [Get Started →]                                       │
└─────────────────────────────────────────────────────────┘

Step 2: Server Mode
┌─────────────────────────────────────────────────────────┐
│   How will you use this server?                         │
│                                                         │
│   ○ Personal server (single user, just for me)          │
│   ○ Multi-user server (allow registrations)             │
│   ○ Invite-only server (registration requires invite)   │
│                                                         │
│   [← Back]  [Next →]                                    │
└─────────────────────────────────────────────────────────┘

Step 3: Admin Account (if IdP enabled)
┌─────────────────────────────────────────────────────────┐
│   Create your administrator account                     │
│                                                         │
│   Username: [_______________]                           │
│   Email:    [_______________]                           │
│   Password: [_______________]                           │
│   Confirm:  [_______________]                           │
│                                                         │
│   [← Back]  [Next →]                                    │
└─────────────────────────────────────────────────────────┘

Step 4: Features (Optional)
┌─────────────────────────────────────────────────────────┐
│   Enable additional features:                           │
│                                                         │
│   ☐ WebSocket Notifications                            │
│   ☐ Content Negotiation (Turtle/RDF)                   │
│   ☐ ActivityPub Federation                             │
│   ☐ Nostr Relay                                        │
│   ☐ Git Backend                                        │
│                                                         │
│   [← Back]  [Next →]                                    │
└─────────────────────────────────────────────────────────┘

Step 5: Complete
┌─────────────────────────────────────────────────────────┐
│   ✓ Setup Complete!                                     │
│                                                         │
│   Your server is ready at: https://example.com          │
│   Admin account: admin@example.com                      │
│                                                         │
│   Configuration saved to: ./config.json                 │
│                                                         │
│   [Go to Dashboard →]                                   │
└─────────────────────────────────────────────────────────┘
```

### Detection Logic

```javascript
// In server.js onReady hook
const setupComplete = fs.existsSync(path.join(dataRoot, '.setup-complete'));
const hasAccounts = fs.existsSync(path.join(dataRoot, '.accounts'));
const hasPods = fs.readdirSync(dataRoot).some(f => !f.startsWith('.'));

if (!setupComplete && !hasAccounts && !hasPods) {
  // Redirect all non-setup routes to /setup
}
```

### Headless/Docker Override

For automated deployments, allow skipping the wizard via environment variable:

```bash
JSS_SKIP_SETUP_WIZARD=true
JSS_ADMIN_EMAIL=admin@example.com
JSS_ADMIN_PASSWORD=securepassword
```

### Industry Comparison

| Software | First-Run Experience |
|----------|---------------------|
| **Nextcloud** | Web wizard: admin account → database → data directory |
| **Jellyfin** | Web wizard: admin → libraries → metadata → remote access |
| **Coolify** | Web wizard: admin account → localhost/remote selection |
| **Portainer** | Web wizard: admin account → environment type |
| **Mastodon** | CLI wizard (`rake mastodon:setup`) |
| **CSS** | No wizard (relies on external config generator) |
| **JSS (current)** | CLI wizard only (`jss init`) |
| **JSS (proposed)** | Web wizard + CLI wizard + env var bootstrap |

---

## Proposal 2: Configuration Presets

### Problem

New users face 30+ configuration options without guidance on which combinations make sense for their use case.

### Proposed Solution

Add preset profiles that bundle sensible defaults for common scenarios:

```bash
# CLI usage
jss start --preset personal
jss start --preset community
jss start --preset federation

# Or in config file
{
  "preset": "personal",
  "port": 8443  // overrides still work
}
```

### Suggested Presets

#### `minimal` - Development/Testing
```json
{
  "port": 3000,
  "multiuser": false,
  "singleUser": true,
  "singleUserName": "me",
  "conneg": false,
  "notifications": false,
  "idp": false
}
```

#### `personal` - Single-User Production
```json
{
  "port": 443,
  "multiuser": false,
  "singleUser": true,
  "conneg": true,
  "notifications": true,
  "idp": true,
  "mashlib": true
}
```

#### `community` - Multi-User Server
```json
{
  "port": 443,
  "multiuser": true,
  "conneg": true,
  "notifications": true,
  "idp": true,
  "inviteOnly": false,
  "defaultQuota": "100MB"
}
```

#### `private` - Invite-Only Server
```json
{
  "port": 443,
  "multiuser": true,
  "conneg": true,
  "notifications": true,
  "idp": true,
  "inviteOnly": true,
  "defaultQuota": "1GB"
}
```

#### `federation` - Federated Social Server
```json
{
  "port": 443,
  "multiuser": true,
  "conneg": true,
  "notifications": true,
  "idp": true,
  "activitypub": true,
  "nostr": true
}
```

### Enhanced `jss init` with Presets

```
$ jss init

  JavaScript Solid Server Setup

? Choose a starting point:
  > Personal server (single user, simple setup)
    Community server (multi-user, open registration)
    Private server (multi-user, invite-only)
    Federation server (ActivityPub + Nostr)
    Minimal (development/testing)
    Custom (configure everything manually)

? Port (443): 
? Domain (localhost): example.com
...
```

---

## Proposal 3: Web-Based Configuration Generator

### Problem

CSS provides a web-based configuration generator that lets users click through options and download a config file. JSS lacks this, requiring users to read docs or use `jss init`.

### Proposed Solution

Create a static web page (can be hosted on GitHub Pages or docs site) that:

1. Presents all configuration options with descriptions
2. Shows real-time preview of generated config
3. Validates combinations (e.g., warns if IdP enabled without HTTPS)
4. Exports as JSON config file or docker-compose snippet

### Mockup

```
┌─────────────────────────────────────────────────────────────────┐
│  JSS Configuration Generator                                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  PRESET: [Personal ▼]                                          │
│                                                                 │
│  ─── Server ───                    ─── Preview ───             │
│  Port:     [3000    ]              {                           │
│  Host:     [0.0.0.0 ]                "port": 3000,             │
│  Data Dir: [./data  ]                "host": "0.0.0.0",        │
│                                      "root": "./data",          │
│  ─── Features ───                    "singleUser": true,        │
│  ☑ Single-user mode                  "idp": true,               │
│  ☑ Identity Provider                 "notifications": true      │
│  ☑ WebSocket Notifications         }                           │
│  ☐ Content Negotiation                                         │
│  ☐ ActivityPub                     [Copy] [Download]           │
│  ☐ Nostr Relay                                                 │
│                                     ─── Docker ───              │
│  ─── Security ───                   services:                   │
│  ☐ SSL/TLS                            jss:                      │
│    Key:  [          ]                   image: jss:latest       │
│    Cert: [          ]                   environment:            │
│  ☐ Invite-only                           - JSS_PORT=3000        │
│                                          - JSS_SINGLE_USER=true │
│  ─── Quotas ───                                                 │
│  Default: [50MB     ]              [Copy Docker Compose]        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Implementation Options

1. **Standalone static site** - React/Vue app on GitHub Pages
2. **Built into JSS** - Serve at `/.well-known/config-generator` when in dev mode
3. **Part of docs site** - Integrate with documentation

### CSS Comparison

CSS provides this at: https://communitysolidserver.github.io/configuration-generator/v5/

Their generator covers:
- Storage backend (memory/file/SPARQL)
- Pod management (registration, URL format)
- Security (HTTPS, authorization)
- Features (WebSocket, setup endpoints)

---

## Proposal 4: Configuration Validation Command

### Problem

Configuration errors are only discovered at runtime, leading to failed startups or unexpected behavior.

### Proposed Solution

Add `jss validate` command:

```bash
$ jss validate --config config.json

Validating configuration...

✓ Port 8443 is valid
✓ Host 0.0.0.0 is valid  
✓ Data directory ./data exists and is writable
✓ SSL certificate found: ./ssl/cert.pem
✓ SSL private key found: ./ssl/key.pem
✓ SSL certificate is valid (expires: 2025-12-01)
⚠ Warning: IdP issuer URL should use HTTPS in production
✓ Default quota 50MB is valid
✓ Preset 'personal' applied successfully

Configuration is valid with 1 warning.
```

### Validation Checks

- Port range (1-65535)
- Data directory exists and is writable
- SSL files exist and are readable
- SSL certificate validity and expiration
- Required combinations (e.g., subdomains requires baseDomain)
- Mutual exclusions (e.g., can't use both mashlib and mashlibCdn)
- Security warnings (IdP without HTTPS, weak configurations)

---

## Implementation Priority

| Priority | Feature | Effort | Impact |
|----------|---------|--------|--------|
| **P0** | Web-based first-run wizard | Medium | High - Industry standard, critical for adoption |
| **P1** | Configuration presets | Low | High - Quick win, improves UX significantly |
| **P2** | Enhanced `jss init` with presets | Low | Medium - Improves CLI experience |
| **P3** | Config validation command | Low | Medium - Catches errors early |
| **P4** | Web-based config generator | Medium | Medium - Nice-to-have, can be separate project |

---

## References

### Community Solid Server
- [CSS Configuration Generator](https://communitysolidserver.github.io/configuration-generator/v5/)
- [CSS Starting the Server](https://communitysolidserver.github.io/CommunitySolidServer/7.x/usage/starting-server/)
- [CSS Custom Configurations](https://github.com/CommunitySolidServer/tutorials/blob/main/custom-configurations.md)

### Industry Examples
- [Nextcloud Installation Wizard](https://docs.nextcloud.com/server/latest/admin_manual/installation/installation_wizard.html)
- [Jellyfin Setup Wizard](https://jellyfin.org/docs/general/post-install/setup-wizard/)
- [Portainer Initial Setup](https://docs.portainer.io/start/install/server/setup)
- [Coolify Installation](https://coolify.io/docs/get-started/installation)
- [Vaultwarden Configuration](https://github.com/dani-garcia/vaultwarden/wiki/Configuration-overview)
- [Mastodon Server Setup](https://docs.joinmastodon.org/user/run-your-own/)

### Best Practices
- [Self-Hosting Guide](https://github.com/mikeroyal/Self-Hosting-Guide)
- [Self-Hosted Software Best Practices](https://blog.dreamfactory.com/self-hosted-software-best-practices-for-secure-and-reliable-deployment)

---

## Questions for Discussion

1. Should the web wizard be the default, or should it require `--enable-setup-wizard`?
2. Should preset configs be bundled in the package or loaded from a URL?
3. Should the config generator be part of JSS or a separate project?
4. What additional presets would be useful?
5. Should the wizard support themes/branding customization?

/cc @maintainers

Software	First-Run Experience
Nextcloud	Web wizard: admin account → database → data directory
Jellyfin	Web wizard: admin → libraries → metadata → remote access
Coolify	Web wizard: admin account → localhost/remote selection
Portainer	Web wizard: admin account → environment type
Mastodon	CLI wizard (`rake mastodon:setup`)
CSS	No wizard (relies on external config generator)
JSS (current)	CLI wizard only (`jss init`)
JSS (proposed)	Web wizard + CLI wizard + env var bootstrap

Layer	Method	Priority
Defaults	Hardcoded in `src/config.js`	Lowest
Config file	`-c config.json`	Low
Environment variables	`JSS_*` prefix	Medium
CLI arguments	`--port`, `--idp`, etc.	Highest

Priority	Feature	Effort	Impact
P0	Web-based first-run wizard	Medium	High - Industry standard, critical for adoption
P1	Configuration presets	Low	High - Quick win, improves UX significantly
P2	Enhanced `jss init` with presets	Low	Medium - Improves CLI experience
P3	Config validation command	Low	Medium - Catches errors early
P4	Web-based config generator	Medium	Medium - Nice-to-have, can be separate project

Uh oh!

Feature: Admin Onboarding Wizard & Configuration Improvements #95

Description

Summary

Current State

Proposal 1: Web-Based First-Run Onboarding Wizard (Primary)

Problem

Proposed Solution

Detection Logic

Headless/Docker Override

Industry Comparison

Proposal 2: Configuration Presets

Problem

Proposed Solution

Suggested Presets

minimal - Development/Testing

personal - Single-User Production

community - Multi-User Server

private - Invite-Only Server

federation - Federated Social Server

Enhanced jss init with Presets

Proposal 3: Web-Based Configuration Generator

Problem

Proposed Solution

Mockup

Implementation Options

CSS Comparison

Proposal 4: Configuration Validation Command

Problem

Proposed Solution

Validation Checks

Implementation Priority

References

Community Solid Server

Industry Examples

Best Practices

Questions for Discussion

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

`minimal` - Development/Testing

`personal` - Single-User Production

`community` - Multi-User Server

`private` - Invite-Only Server

`federation` - Federated Social Server

Enhanced `jss init` with Presets