René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Feature: Admin Onboarding Wizard \u0026 Configuration Improvements","articleBody":"## Summary\n\nThis 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.\n\n## Current State\n\nJSS already has a solid configuration foundation:\n\n| Layer | Method | Priority |\n|-------|--------|----------|\n| Defaults | Hardcoded in `src/config.js` | Lowest |\n| Config file | `-c config.json` | Low |\n| Environment variables | `JSS_*` prefix | Medium |\n| CLI arguments | `--port`, `--idp`, etc. | Highest |\n\n**Existing features:**\n- `jss init` - Interactive CLI wizard for basic setup\n- `--print-config` - Debug/inspect current configuration\n- 30+ configurable options (port, SSL, IdP, quotas, federation, etc.)\n\n**Current gaps:**\n- No web-based first-run experience\n- No preset configurations for common use cases\n- No web-based configuration generator\n- First-time users must use CLI before seeing any UI\n\n---\n\n## Proposal 1: Web-Based First-Run Onboarding Wizard (Primary)\n\n### Problem\n\nWhen a new admin starts JSS for the first time, they must:\n1. Read documentation to understand options\n2. Run `jss init` or manually create a config\n3. Start the server\n4. Then figure out how to create their first account/pod\n\nMost modern self-hosted software detects first-run and presents a guided setup wizard in the browser.\n\n### Proposed Solution\n\nWhen 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:\n\n```\nStep 1: Welcome\n┌─────────────────────────────────────────────────────────┐\n│   Welcome to JavaScript Solid Server                    │\n│                                                         │\n│   Let's configure your server in a few simple steps.   │\n│                                                         │\n│   [Get Started →]                                       │\n└─────────────────────────────────────────────────────────┘\n\nStep 2: Server Mode\n┌─────────────────────────────────────────────────────────┐\n│   How will you use this server?                         │\n│                                                         │\n│   ○ Personal server (single user, just for me)          │\n│   ○ Multi-user server (allow registrations)             │\n│   ○ Invite-only server (registration requires invite)   │\n│                                                         │\n│   [← Back]  [Next →]                                    │\n└─────────────────────────────────────────────────────────┘\n\nStep 3: Admin Account (if IdP enabled)\n┌─────────────────────────────────────────────────────────┐\n│   Create your administrator account                     │\n│                                                         │\n│   Username: [_______________]                           │\n│   Email:    [_______________]                           │\n│   Password: [_______________]                           │\n│   Confirm:  [_______________]                           │\n│                                                         │\n│   [← Back]  [Next →]                                    │\n└─────────────────────────────────────────────────────────┘\n\nStep 4: Features (Optional)\n┌─────────────────────────────────────────────────────────┐\n│   Enable additional features:                           │\n│                                                         │\n│   ☐ WebSocket Notifications                            │\n│   ☐ Content Negotiation (Turtle/RDF)                   │\n│   ☐ ActivityPub Federation                             │\n│   ☐ Nostr Relay                                        │\n│   ☐ Git Backend                                        │\n│                                                         │\n│   [← Back]  [Next →]                                    │\n└─────────────────────────────────────────────────────────┘\n\nStep 5: Complete\n┌─────────────────────────────────────────────────────────┐\n│   ✓ Setup Complete!                                     │\n│                                                         │\n│   Your server is ready at: https://example.com          │\n│   Admin account: admin@example.com                      │\n│                                                         │\n│   Configuration saved to: ./config.json                 │\n│                                                         │\n│   [Go to Dashboard →]                                   │\n└─────────────────────────────────────────────────────────┘\n```\n\n### Detection Logic\n\n```javascript\n// In server.js onReady hook\nconst setupComplete = fs.existsSync(path.join(dataRoot, '.setup-complete'));\nconst hasAccounts = fs.existsSync(path.join(dataRoot, '.accounts'));\nconst hasPods = fs.readdirSync(dataRoot).some(f =\u003e !f.startsWith('.'));\n\nif (!setupComplete \u0026\u0026 !hasAccounts \u0026\u0026 !hasPods) {\n  // Redirect all non-setup routes to /setup\n}\n```\n\n### Headless/Docker Override\n\nFor automated deployments, allow skipping the wizard via environment variable:\n\n```bash\nJSS_SKIP_SETUP_WIZARD=true\nJSS_ADMIN_EMAIL=admin@example.com\nJSS_ADMIN_PASSWORD=securepassword\n```\n\n### Industry Comparison\n\n| Software | First-Run Experience |\n|----------|---------------------|\n| **Nextcloud** | Web wizard: admin account → database → data directory |\n| **Jellyfin** | Web wizard: admin → libraries → metadata → remote access |\n| **Coolify** | Web wizard: admin account → localhost/remote selection |\n| **Portainer** | Web wizard: admin account → environment type |\n| **Mastodon** | CLI wizard (`rake mastodon:setup`) |\n| **CSS** | No wizard (relies on external config generator) |\n| **JSS (current)** | CLI wizard only (`jss init`) |\n| **JSS (proposed)** | Web wizard + CLI wizard + env var bootstrap |\n\n---\n\n## Proposal 2: Configuration Presets\n\n### Problem\n\nNew users face 30+ configuration options without guidance on which combinations make sense for their use case.\n\n### Proposed Solution\n\nAdd preset profiles that bundle sensible defaults for common scenarios:\n\n```bash\n# CLI usage\njss start --preset personal\njss start --preset community\njss start --preset federation\n\n# Or in config file\n{\n  \"preset\": \"personal\",\n  \"port\": 8443  // overrides still work\n}\n```\n\n### Suggested Presets\n\n#### `minimal` - Development/Testing\n```json\n{\n  \"port\": 3000,\n  \"multiuser\": false,\n  \"singleUser\": true,\n  \"singleUserName\": \"me\",\n  \"conneg\": false,\n  \"notifications\": false,\n  \"idp\": false\n}\n```\n\n#### `personal` - Single-User Production\n```json\n{\n  \"port\": 443,\n  \"multiuser\": false,\n  \"singleUser\": true,\n  \"conneg\": true,\n  \"notifications\": true,\n  \"idp\": true,\n  \"mashlib\": true\n}\n```\n\n#### `community` - Multi-User Server\n```json\n{\n  \"port\": 443,\n  \"multiuser\": true,\n  \"conneg\": true,\n  \"notifications\": true,\n  \"idp\": true,\n  \"inviteOnly\": false,\n  \"defaultQuota\": \"100MB\"\n}\n```\n\n#### `private` - Invite-Only Server\n```json\n{\n  \"port\": 443,\n  \"multiuser\": true,\n  \"conneg\": true,\n  \"notifications\": true,\n  \"idp\": true,\n  \"inviteOnly\": true,\n  \"defaultQuota\": \"1GB\"\n}\n```\n\n#### `federation` - Federated Social Server\n```json\n{\n  \"port\": 443,\n  \"multiuser\": true,\n  \"conneg\": true,\n  \"notifications\": true,\n  \"idp\": true,\n  \"activitypub\": true,\n  \"nostr\": true\n}\n```\n\n### Enhanced `jss init` with Presets\n\n```\n$ jss init\n\n  JavaScript Solid Server Setup\n\n? Choose a starting point:\n  \u003e Personal server (single user, simple setup)\n    Community server (multi-user, open registration)\n    Private server (multi-user, invite-only)\n    Federation server (ActivityPub + Nostr)\n    Minimal (development/testing)\n    Custom (configure everything manually)\n\n? Port (443): \n? Domain (localhost): example.com\n...\n```\n\n---\n\n## Proposal 3: Web-Based Configuration Generator\n\n### Problem\n\nCSS 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`.\n\n### Proposed Solution\n\nCreate a static web page (can be hosted on GitHub Pages or docs site) that:\n\n1. Presents all configuration options with descriptions\n2. Shows real-time preview of generated config\n3. Validates combinations (e.g., warns if IdP enabled without HTTPS)\n4. Exports as JSON config file or docker-compose snippet\n\n### Mockup\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│  JSS Configuration Generator                                    │\n├─────────────────────────────────────────────────────────────────┤\n│                                                                 │\n│  PRESET: [Personal ▼]                                          │\n│                                                                 │\n│  ─── Server ───                    ─── Preview ───             │\n│  Port:     [3000    ]              {                           │\n│  Host:     [0.0.0.0 ]                \"port\": 3000,             │\n│  Data Dir: [./data  ]                \"host\": \"0.0.0.0\",        │\n│                                      \"root\": \"./data\",          │\n│  ─── Features ───                    \"singleUser\": true,        │\n│  ☑ Single-user mode                  \"idp\": true,               │\n│  ☑ Identity Provider                 \"notifications\": true      │\n│  ☑ WebSocket Notifications         }                           │\n│  ☐ Content Negotiation                                         │\n│  ☐ ActivityPub                     [Copy] [Download]           │\n│  ☐ Nostr Relay                                                 │\n│                                     ─── Docker ───              │\n│  ─── Security ───                   services:                   │\n│  ☐ SSL/TLS                            jss:                      │\n│    Key:  [          ]                   image: jss:latest       │\n│    Cert: [          ]                   environment:            │\n│  ☐ Invite-only                           - JSS_PORT=3000        │\n│                                          - JSS_SINGLE_USER=true │\n│  ─── Quotas ───                                                 │\n│  Default: [50MB     ]              [Copy Docker Compose]        │\n│                                                                 │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n### Implementation Options\n\n1. **Standalone static site** - React/Vue app on GitHub Pages\n2. **Built into JSS** - Serve at `/.well-known/config-generator` when in dev mode\n3. **Part of docs site** - Integrate with documentation\n\n### CSS Comparison\n\nCSS provides this at: https://communitysolidserver.github.io/configuration-generator/v5/\n\nTheir generator covers:\n- Storage backend (memory/file/SPARQL)\n- Pod management (registration, URL format)\n- Security (HTTPS, authorization)\n- Features (WebSocket, setup endpoints)\n\n---\n\n## Proposal 4: Configuration Validation Command\n\n### Problem\n\nConfiguration errors are only discovered at runtime, leading to failed startups or unexpected behavior.\n\n### Proposed Solution\n\nAdd `jss validate` command:\n\n```bash\n$ jss validate --config config.json\n\nValidating configuration...\n\n✓ Port 8443 is valid\n✓ Host 0.0.0.0 is valid  \n✓ Data directory ./data exists and is writable\n✓ SSL certificate found: ./ssl/cert.pem\n✓ SSL private key found: ./ssl/key.pem\n✓ SSL certificate is valid (expires: 2025-12-01)\n⚠ Warning: IdP issuer URL should use HTTPS in production\n✓ Default quota 50MB is valid\n✓ Preset 'personal' applied successfully\n\nConfiguration is valid with 1 warning.\n```\n\n### Validation Checks\n\n- Port range (1-65535)\n- Data directory exists and is writable\n- SSL files exist and are readable\n- SSL certificate validity and expiration\n- Required combinations (e.g., subdomains requires baseDomain)\n- Mutual exclusions (e.g., can't use both mashlib and mashlibCdn)\n- Security warnings (IdP without HTTPS, weak configurations)\n\n---\n\n## Implementation Priority\n\n| Priority | Feature | Effort | Impact |\n|----------|---------|--------|--------|\n| **P0** | Web-based first-run wizard | Medium | High - Industry standard, critical for adoption |\n| **P1** | Configuration presets | Low | High - Quick win, improves UX significantly |\n| **P2** | Enhanced `jss init` with presets | Low | Medium - Improves CLI experience |\n| **P3** | Config validation command | Low | Medium - Catches errors early |\n| **P4** | Web-based config generator | Medium | Medium - Nice-to-have, can be separate project |\n\n---\n\n## References\n\n### Community Solid Server\n- [CSS Configuration Generator](https://communitysolidserver.github.io/configuration-generator/v5/)\n- [CSS Starting the Server](https://communitysolidserver.github.io/CommunitySolidServer/7.x/usage/starting-server/)\n- [CSS Custom Configurations](https://github.com/CommunitySolidServer/tutorials/blob/main/custom-configurations.md)\n\n### Industry Examples\n- [Nextcloud Installation Wizard](https://docs.nextcloud.com/server/latest/admin_manual/installation/installation_wizard.html)\n- [Jellyfin Setup Wizard](https://jellyfin.org/docs/general/post-install/setup-wizard/)\n- [Portainer Initial Setup](https://docs.portainer.io/start/install/server/setup)\n- [Coolify Installation](https://coolify.io/docs/get-started/installation)\n- [Vaultwarden Configuration](https://github.com/dani-garcia/vaultwarden/wiki/Configuration-overview)\n- [Mastodon Server Setup](https://docs.joinmastodon.org/user/run-your-own/)\n\n### Best Practices\n- [Self-Hosting Guide](https://github.com/mikeroyal/Self-Hosting-Guide)\n- [Self-Hosted Software Best Practices](https://blog.dreamfactory.com/self-hosted-software-best-practices-for-secure-and-reliable-deployment)\n\n---\n\n## Questions for Discussion\n\n1. Should the web wizard be the default, or should it require `--enable-setup-wizard`?\n2. Should preset configs be bundled in the package or loaded from a URL?\n3. Should the config generator be part of JSS or a separate project?\n4. What additional presets would be useful?\n5. Should the wizard support themes/branding customization?\n\n/cc @maintainers","author":{"url":"https://github.com/melvincarvalho","@type":"Person","name":"melvincarvalho"},"datePublished":"2026-01-19T12:43:57.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/95/JavaScriptSolidServer/issues/95"}