jspod

jspod - JavaScript Solid Pod

Just works. Batteries included. Zero configuration.

jspod is the easiest way to run a Solid server. It’s a thin wrapper around JavaScriptSolidServer with sensible defaults and a beautiful CLI.

🚀 Quick Start

# Run instantly with npx (no installation required!)
npx jspod

# That's it! Your Solid server is running at http://localhost:3000

✨ Features

🎯 Just Works

Zero configuration - Smart defaults for everything
One command - npx jspod and you’re running
Beautiful CLI - Gorgeous terminal output that makes you smile

🔋 Batteries Included

Built on JavaScriptSolidServer with all features enabled:

✅ Solid Protocol - Full Solid spec compliance
✅ WebID Authentication - Identity and access control
✅ Passkey Support - Modern passwordless authentication
✅ WebSocket Notifications - Real-time updates
✅ JSON-LD Native - First-class JSON-LD support
✅ Content Negotiation - Turtle, JSON-LD, and more

📦 Installation

No Installation (Recommended)

npx jspod

Global Installation

npm install -g jspod
jspod

Local Installation

npm install jspod
npx jspod

🎮 Usage

Basic Usage

# Start with defaults (port 3000, single-user)
jspod

# Custom port
jspod --port 8080

# Custom data directory
jspod --root /var/pods

# Multi-user mode
jspod --multiuser

CLI Options

Options:
  -p, --port <number>     Port to listen on (default: 3000)
  -h, --host <address>    Host to bind to (default: 0.0.0.0)
  -r, --root <path>       Data directory (default: ./pod-data)
  --multiuser             Enable multi-user mode
  --no-auth               Disable authentication
  --help                  Show help message

Environment Variables

# Set JWT secret (recommended for production)
export TOKEN_SECRET="your-secret-key-here"

# Set environment
export NODE_ENV="production"

# Run server
jspod

Production Deployment

⚠️ Important: Before deploying to production:

Set TOKEN_SECRET

export TOKEN_SECRET="$(openssl rand -base64 32)"

Use a proper domain (not localhost)
- Passkeys require HTTPS in production
- Get SSL cert (Let’s Encrypt recommended)

Run as a service

# Example systemd service
sudo systemctl enable jspod
sudo systemctl start jspod

Set up backups
- Back up ./pod-data directory
- Contains all user data and credentials
Monitor logs
```
jspod --verbose > jspod.log 2>&1
```

🏃 Quickstart Examples

Personal Pod

# Start your personal Solid pod
jspod

# Visit http://localhost:3000 in your browser
# Register with passkey, start storing data!

Multi-User Server

# Run a server for multiple users
jspod --multiuser --port 443 --root /var/solid-pods

# Users can register and get their own pod space

Development Server

# Run on custom port for development
jspod --port 8080 --root ./dev-data

🆚 jspod vs JavaScriptSolidServer

Feature	JavaScriptSolidServer	jspod
Installation	`npm install -g javascript-solid-server`	`npx jspod`
Configuration	Config file required	Smart defaults
Commands	`jss start [options]`	`jspod`
First run	5+ steps	1 command
Use case	Power users, customization	Quick start, demos

When to use JavaScriptSolidServer: Production deployments, custom configuration, advanced features

When to use jspod: Quick demos, local development, “just want it to work”

🛠️ How It Works

jspod is a thin wrapper that:

Provides sensible defaults
Creates beautiful CLI output
Manages the lifecycle of JavaScriptSolidServer
Handles graceful shutdown

Enabled Features

Under the hood, jspod runs JavaScriptSolidServer with these options:

Feature	JSS Flag	Description
WebSocket Notifications	`--notifications`	Real-time updates via WebSockets
Content Negotiation	`--conneg`	Turtle, JSON-LD, and more
Single-user Mode	`--no-multiuser`	One pod per server (use `--multiuser` flag to change)
Passkey Auth	(built-in)	Automatic in JSS - no flag needed
WebID	(built-in)	Core Solid protocol feature

Default Configuration

{
  port: 3000,              // Easy to remember
  host: '0.0.0.0',         // Accept connections from anywhere
  root: './pod-data',      // Local data directory
  multiuser: false,        // Single pod per server
  TOKEN_SECRET: (auto)     // JWT secret (auto-generated, change for production)
}

🎯 First Run Guide

Step 1: Start the server

npx jspod

Step 2: Open your browser to http://localhost:3000

Step 3: Register with a passkey

Click “Register” or “Sign Up”
Use your device’s biometric auth (fingerprint, Face ID, etc.)
Your WebID will be created automatically

Step 4: Start using your pod!

Upload files, create resources
Use Solid apps to connect to your pod
Your data stays on your server

Troubleshooting:

Port in use? Run jspod --port 3001
Data location? Check ./pod-data directory
Can’t register? Make sure your browser supports WebAuthn (Chrome, Firefox, Safari, Edge all work)

📖 Learn More

What is Solid?

Solid is a web specification that lets people store their data securely in decentralized data stores called Pods. This gives users control over their own data.

Resources

jspod: https://github.com/JavaScriptSolidServer/jspod
JavaScriptSolidServer: https://github.com/JavaScriptSolidServer/JavaScriptSolidServer
Solid Project: https://solidproject.org
Solid Spec: https://solidproject.org/TR/protocol
WebID: https://www.w3.org/2005/Incubator/webid/spec

🤝 Contributing

Contributions welcome! jspod is intentionally simple - we want to keep it that way.

Philosophy:

Simple over complex
Defaults over configuration
Works over features

See CONTRIBUTING.md for guidelines.

📄 License

MIT - see LICENSE

🙏 Credits

jspod is built on top of the excellent JavaScriptSolidServer by Melvin Carvalho and contributors.

💬 Support

Issues: https://github.com/JavaScriptSolidServer/jspod/issues
Discussions: https://github.com/JavaScriptSolidServer/jspod/discussions
Solid Forum: https://forum.solidproject.org

Made with ❤️ for the Solid community

“Solid made simple”

This site is open source. Improve this page.