Skip to content

docs: slim README to 89 lines, hero block above the fold #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
melvincarvalho merged 1 commit into from
May 16, 2026
Merged

docs: slim README to 89 lines, hero block above the fold #10

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
324 changes: 48 additions & 276 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,317 +1,89 @@
# jspod - JavaScript Solid Pod
# jspod

> **Just works**. Batteries included. Zero configuration.
> Your personal [Solid](https://solidproject.org) pod, in one command.

[![npm version](https://img.shields.io/npm/v/jspod.svg)](https://www.npmjs.com/package/jspod)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**jspod** is the easiest way to run a [Solid](https://solidproject.org) server. It's a thin wrapper around [JavaScriptSolidServer](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer) with sensible defaults and a beautiful CLI.

## 🚀 Quick Start
## Try in 60 seconds

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

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

## ✨ 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](https://github.com/JavaScriptSolidServer/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)

```bash
npx jspod
```
Your browser opens to `http://localhost:5444`. Click **Sign in** and use:

### Global Installation
| Username | Password |
| -------- | -------- |
| `me` | `me` |

```bash
npm install -g jspod
jspod
```

### Local Installation

```bash
npm install jspod
npx jspod
```

## 🎮 Usage

### Basic Usage

```bash
# Start with defaults (port 5444, single-user)
jspod
That's it. You have a working Solid pod with a passkey-capable identity provider, a tiny built-in data browser, and a [WebID](https://www.w3.org/2005/Incubator/webid/spec) you can point any Solid app at.

# Custom port
jspod --port 8080
> jspod binds to `127.0.0.1` by default so the placeholder `me` / `me` credentials are reachable only from your local machine.

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

# Multi-user mode
jspod --multiuser
```

### CLI Options

```
Options:
-p, --port <number> Port to listen on (default: 5444)
-h, --host <address> Host to bind to (default: 127.0.0.1)
-r, --root <path> Data directory (default: ./pod-data)
--multiuser Enable multi-user mode
--no-auth Disable authentication
--no-open Do not open the browser automatically
-v, --version Show jspod version
--help Show help message
```

### Environment Variables

```bash
# JWT secret — auto-generated and persisted at <root>/.token-secret on
# first run. Override here only for operator-managed deployments.
export TOKEN_SECRET="$(openssl rand -base64 32)"

# Set environment
export NODE_ENV="production"

# Run server
jspod
```

### Production Deployment

**⚠️ Important**: Before deploying to production:

1. **TOKEN_SECRET** is auto-generated on first run and persisted at `<root>/.token-secret` (mode 0600). For operator-managed deployments — secret rotation, distributed setups, secret managers — set it explicitly via env:
```bash
export TOKEN_SECRET="$(openssl rand -base64 32)"
```

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

3. **Run as a service**
```bash
# Example systemd service
sudo systemctl enable jspod
sudo systemctl start jspod
```

4. **Set up backups**
- Back up `./pod-data` directory
- Contains all user data and credentials

5. **Monitor logs**
```bash
jspod > jspod.log 2>&1
```

## 🏃 Quickstart Examples

### Personal Pod

```bash
# Start your personal Solid pod
jspod

# Visit http://localhost:5444 in your browser
# Register with passkey, start storing data!
--multiuser Enable multi-user mode (registration enabled)
--no-auth Open pod, no IDP, no ACL (demos / dev only)
--no-open Don't auto-open the browser on start
-v, --version Print jspod version
--help Show help
```

### Multi-User Server
## The auth ladder

```bash
# Run a server for multiple users
jspod --multiuser --port 443 --root /var/solid-pods
jspod ships you onto the lowest rung that's safe, and the climb is visible:

# Users can register and get their own pod space
```
| Rung | Auth | How to get there |
| ---: | ------------------- | -------------------------------------------------- |
| 0 | None | `jspod --no-auth` (demos / dev only) |
| 1 | `me` / `me` | Default. Localhost-only. |
| 2 | Your password | Change it in your pod's account settings |
| 3 | Passkey | Add a passkey from account settings |
| 4 | Hardware key / MFA | Power-user setup |

### Development Server

```bash
# 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:

1. Provides sensible defaults
2. Creates beautiful CLI output
3. Manages the lifecycle of JavaScriptSolidServer
4. 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 --single-user` | One pod per server (use `--multiuser` flag to change) |
| **Identity Provider** | `--idp` | Built-in IDP so the rung-1 sign-in works out of the box |
| **Tiny Data Browser** | `--mashlib-module` | ~200 bytes of JS + CSS shipped in this npm package, served from jsdelivr. Replaces the full mashlib bundle by default. |
| **Passkey Auth** | (built-in) | Automatic in JSS - no flag needed |
| **WebID** | (built-in) | Core Solid protocol feature |

### The page is the data

By default jspod uses a deliberately minimal data browser — a ~200-byte ES module that renders the JSON-LD data island JSS already embeds in each HTML response, with every URI turned into a clickable link. No SPA, no CDN bundle, no parsing — *the page is the data, and the URIs are the navigation*.

The browser source is two files in this npm package:

- [`data-browser.js`](./data-browser.js) — finds `#dataisland`, renders to `#mashlib`, makes URIs clickable
- [`data-browser.css`](./data-browser.css) — system font, cream background, soft card

JSS loads them from a version-pinned jsdelivr URL: `https://cdn.jsdelivr.net/npm/jspod@<version>/data-browser.js`. Override with `--mashlib-cdn` (full mashlib from CDN) or `--no-mashlib` (raw RDF responses) via your own JSS invocation if you want something else.

### Default Configuration

```javascript
{
port: 5444, // Memorable, low collision with common dev servers
host: '127.0.0.1', // Localhost-only by default (rung-1 credentials)
root: './pod-data', // Local data directory
multiuser: false, // Single pod per server
TOKEN_SECRET: (per-pod) // Auto-generated on first run and persisted at
// <root>/.token-secret (mode 0600). Override via
// the TOKEN_SECRET env var for operator control.
}
```

## 🎯 First Run Guide

**Step 1**: Start the server
```bash
npx jspod
```

**Step 2**: Your browser opens automatically to `http://localhost:5444`

> Running over SSH, in CI, or in a non-interactive terminal? jspod skips auto-open and prints the URL instead. You can also pass `--no-open` to disable it explicitly.

**Step 3**: Sign in (rung 1 of the auth ladder)

The first time you start jspod, an IDP account is seeded with deliberately weak default credentials:

| Field | Value |
| -------- | ----- |
| Username | `me` |
| Password | `me` |

Click **Sign in** on the welcome page, then point a Solid app (like [Pilot](https://solid-apps.github.io/pilot/)) at `http://localhost:5444` and sign in with `me` / `me`.

> **Why are the defaults so weak?** jspod ships you onto the first rung of the auth ladder in under a minute, then guides you up. Rung 1 is **only safe on localhost** — jspod binds to `127.0.0.1` by default for exactly this reason. Once you're in, change the password (rung 2) or add a passkey (rung 3) from your pod's account settings. See [issue #6](https://github.com/JavaScriptSolidServer/jspod/issues/6) for the ladder rationale.

**Step 4**: Climb the ladder

| Rung | Auth | How |
| ---- | --------------------- | -------------------------------------------- |
| 0 | None | `npx jspod --no-auth` (demos / dev only) |
| 1 | `me` / `me` | **Default.** Localhost-only. |
| 2 | Your password | Change it from your pod's account settings |
| 3 | Passkey | Add a passkey from account settings |
| 4 | Hardware key / MFA | Power-user setup |

Override the default password without going through the UI:
Override the initial password without going through the UI:

```bash
JSS_SINGLE_USER_PASSWORD='your-password' npx jspod
```

**Step 5**: Start using your pod
- Upload files, create resources from a Solid app
- Your data stays on your server
- Connect more apps — they all authenticate against your IDP

**Troubleshooting**:
- **Port in use?** Run `jspod --port 5445`
- **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](https://solidproject.org) 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
## Configuration

Contributions welcome! jspod is intentionally simple - we want to keep it that way.
| Variable | Effect |
| --------------------------- | ------------------------------------------------------------------- |
| `JSS_SINGLE_USER_PASSWORD` | Seed password instead of `me` (kept out of `ps` / banner output). |
| `TOKEN_SECRET` | JWT signing secret. Auto-generated at `<root>/.token-secret` (mode 0600) on first run if unset. Override for operator-managed deployments. |
| `NODE_ENV` | Standard Node env. Defaults to `development`. |

**Philosophy**:
- Simple over complex
- Defaults over configuration
- Works over features
For LAN-reachable deployments, pass `--host 0.0.0.0` (jspod prints a warning to remind you that the rung-1 credentials are now exposed) and either set `JSS_SINGLE_USER_PASSWORD` or change the password from the pod UI immediately after first sign-in.

See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
## The data browser

## 📄 License
jspod ships a deliberately minimal data browser — about 800 bytes of JS that JSS loads from a version-pinned jsdelivr URL. It parses the JSON-LD island JSS already embeds in each HTML response, pretty-prints it, and renders every URI as a clickable link.

MIT - see [LICENSE](./LICENSE)
The source: [`data-browser.js`](./data-browser.js). The page is the data; the URIs are the navigation. No SPA, no mashlib CDN bundle.

## 🙏 Credits
If you want the full mashlib data browser instead, skip jspod and run JSS directly with `jss start --mashlib-cdn`.

jspod is built on top of the excellent [JavaScriptSolidServer](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer) by Melvin Carvalho and contributors.
## When to use jspod

## 💬 Support
- ✅ A working personal pod in 60 seconds on your laptop
- ✅ Trying Solid for the first time
- ✅ Local development against a Solid app
- ❌ Hosting pods for multiple users → use [JSS](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer) directly with `--multiuser`
- ❌ Production deployments → JSS with operator-managed config

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

---
- [JavaScriptSolidServer (the substrate)](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer)
- [Solid project](https://solidproject.org)
- [Solid spec](https://solidproject.org/TR/protocol)

**Made with ❤️ for the Solid community**
## License & credits

*"Solid made simple"*
MIT. Built on [JavaScriptSolidServer](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer) by Melvin Carvalho and contributors. Issues: [GitHub](https://github.com/JavaScriptSolidServer/jspod/issues).