Feature: Admin Onboarding Wizard & Configuration Improvements · Issue #95 · JavaScriptSolidServer/JavaScriptSolidServer · GitHub

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:

Read documentation to understand options
Run jss init or manually create a config
Start the server
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

// 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:

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:

# 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

{
  "port": 3000,
  "multiuser": false,
  "singleUser": true,
  "singleUserName": "me",
  "conneg": false,
  "notifications": false,
  "idp": false
}

personal - Single-User Production

{
  "port": 443,
  "multiuser": false,
  "singleUser": true,
  "conneg": true,
  "notifications": true,
  "idp": true,
  "mashlib": true
}

community - Multi-User Server

{
  "port": 443,
  "multiuser": true,
  "conneg": true,
  "notifications": true,
  "idp": true,
  "inviteOnly": false,
  "defaultQuota": "100MB"
}

private - Invite-Only Server

{
  "port": 443,
  "multiuser": true,
  "conneg": true,
  "notifications": true,
  "idp": true,
  "inviteOnly": true,
  "defaultQuota": "1GB"
}

federation - Federated Social Server

{
  "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:

Presents all configuration options with descriptions
Shows real-time preview of generated config
Validates combinations (e.g., warns if IdP enabled without HTTPS)
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

Standalone static site - React/Vue app on GitHub Pages
Built into JSS - Serve at /.well-known/config-generator when in dev mode
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:

$ 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

Industry Examples

Best Practices

Questions for Discussion

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

/cc @maintainers

Feature: Admin Onboarding Wizard & Configuration Improvements · Issue #95 · JavaScriptSolidServer/JavaScriptSolidServer · GitHub

Repository navigation

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

Activity

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions