Skip to content

Commit 21953bc

Browse files
melvincarvalhomelvincarvalho
authored
docs: slim README to 89 lines, hero block above the fold (#10)
The README had grown to 317 lines across 23+ sections with substantial overlap (three install paths, three Quickstart Examples that repeated the CLI, a 5-step Production Deployment block, a How-It-Works section, a Default Configuration code block that restated CLI options, and a First Run Guide that retold the auth-ladder story already covered elsewhere). Slim version: 89 lines, 9 sections. Top of the file is now a "Try in 60 seconds" hero with the command, the `me` / `me` credentials in a table, and one line about what happens next. Everything below is reference material (CLI options, auth ladder, env-var config, the data-browser philosophy, when to use jspod vs JSS direct, outbound links, license). Removed (content moved to comments inline or simply dropped): - Three install variants (npx is THE install) - Quickstart Examples (redundant with CLI Options) - Production Deployment 5-step block (covered by Configuration + the LAN-exposure warning that jspod itself prints) - Default Configuration code block (CLI Options table covers it) - First Run Guide step-by-step (folded into the hero) - How It Works internals (jspod is small enough to read directly) - Learn More / Contributing scaffolding (replaced by a single Links block + license/credits) No behaviour change; docs-only.
1 parent de7ad9d commit 21953bc

1 file changed

Lines changed: 48 additions & 276 deletions

File tree

‎README.md‎

Lines changed: 48 additions & 276 deletions
Original file line numberDiff line numberDiff line change
@@ -1,317 +1,89 @@
1-
# jspod - JavaScript Solid Pod
1+
# jspod
22

3-
> **Just works**. Batteries included. Zero configuration.
3+
> Your personal [Solid](https://solidproject.org) pod, in one command.
44
55
[![npm version](https://img.shields.io/npm/v/jspod.svg)](https://www.npmjs.com/package/jspod)
66
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
77

8-
**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.
9-
10-
## 🚀 Quick Start
8+
## Try in 60 seconds
119

1210
```bash
13-
# Run instantly with npx (no installation required!)
1411
npx jspod
15-
16-
# That's it! Your Solid server is running at http://localhost:5444
1712
```
1813

19-
## ✨ Features
20-
21-
### 🎯 Just Works
22-
- **Zero configuration** - Smart defaults for everything
23-
- **One command** - `npx jspod` and you're running
24-
- **Beautiful CLI** - Gorgeous terminal output that makes you smile
25-
26-
### 🔋 Batteries Included
27-
28-
Built on [JavaScriptSolidServer](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer) with all features enabled:
29-
30-
- ✅ **Solid Protocol** - Full Solid spec compliance
31-
- ✅ **WebID Authentication** - Identity and access control
32-
- ✅ **Passkey Support** - Modern passwordless authentication
33-
- ✅ **WebSocket Notifications** - Real-time updates
34-
- ✅ **JSON-LD Native** - First-class JSON-LD support
35-
- ✅ **Content Negotiation** - Turtle, JSON-LD, and more
36-
37-
## 📦 Installation
38-
39-
### No Installation (Recommended)
40-
41-
```bash
42-
npx jspod
43-
```
14+
Your browser opens to `http://localhost:5444`. Click **Sign in** and use:
4415

45-
### Global Installation
16+
| Username | Password |
17+
| -------- | -------- |
18+
| `me` | `me` |
4619

47-
```bash
48-
npm install -g jspod
49-
jspod
50-
```
51-
52-
### Local Installation
53-
54-
```bash
55-
npm install jspod
56-
npx jspod
57-
```
58-
59-
## 🎮 Usage
60-
61-
### Basic Usage
62-
63-
```bash
64-
# Start with defaults (port 5444, single-user)
65-
jspod
20+
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.
6621

67-
# Custom port
68-
jspod --port 8080
22+
> jspod binds to `127.0.0.1` by default so the placeholder `me` / `me` credentials are reachable only from your local machine.
6923
70-
# Custom data directory
71-
jspod --root /var/pods
24+
## CLI options
7225

73-
# Multi-user mode
74-
jspod --multiuser
7526
```
76-
77-
### CLI Options
78-
79-
```
80-
Options:
8127
-p, --port <number> Port to listen on (default: 5444)
8228
-h, --host <address> Host to bind to (default: 127.0.0.1)
8329
-r, --root <path> Data directory (default: ./pod-data)
84-
--multiuser Enable multi-user mode
85-
--no-auth Disable authentication
86-
--no-open Do not open the browser automatically
87-
-v, --version Show jspod version
88-
--help Show help message
89-
```
90-
91-
### Environment Variables
92-
93-
```bash
94-
# JWT secret — auto-generated and persisted at <root>/.token-secret on
95-
# first run. Override here only for operator-managed deployments.
96-
export TOKEN_SECRET="$(openssl rand -base64 32)"
97-
98-
# Set environment
99-
export NODE_ENV="production"
100-
101-
# Run server
102-
jspod
103-
```
104-
105-
### Production Deployment
106-
107-
**⚠️ Important**: Before deploying to production:
108-
109-
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:
110-
```bash
111-
export TOKEN_SECRET="$(openssl rand -base64 32)"
112-
```
113-
114-
2. **Use a proper domain** (not localhost)
115-
- Passkeys require HTTPS in production
116-
- Get SSL cert (Let's Encrypt recommended)
117-
118-
3. **Run as a service**
119-
```bash
120-
# Example systemd service
121-
sudo systemctl enable jspod
122-
sudo systemctl start jspod
123-
```
124-
125-
4. **Set up backups**
126-
- Back up `./pod-data` directory
127-
- Contains all user data and credentials
128-
129-
5. **Monitor logs**
130-
```bash
131-
jspod > jspod.log 2>&1
132-
```
133-
134-
## 🏃 Quickstart Examples
135-
136-
### Personal Pod
137-
138-
```bash
139-
# Start your personal Solid pod
140-
jspod
141-
142-
# Visit http://localhost:5444 in your browser
143-
# Register with passkey, start storing data!
30+
--multiuser Enable multi-user mode (registration enabled)
31+
--no-auth Open pod, no IDP, no ACL (demos / dev only)
32+
--no-open Don't auto-open the browser on start
33+
-v, --version Print jspod version
34+
--help Show help
14435
```
14536

146-
### Multi-User Server
37+
## The auth ladder
14738

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

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

155-
### Development Server
156-
157-
```bash
158-
# Run on custom port for development
159-
jspod --port 8080 --root ./dev-data
160-
```
161-
162-
## 🆚 jspod vs JavaScriptSolidServer
163-
164-
| Feature | JavaScriptSolidServer | jspod |
165-
|---------|----------------------|------|
166-
| Installation | `npm install -g javascript-solid-server` | `npx jspod` |
167-
| Configuration | Config file required | Smart defaults |
168-
| Commands | `jss start [options]` | `jspod` |
169-
| First run | 5+ steps | 1 command |
170-
| Use case | Power users, customization | Quick start, demos |
171-
172-
**When to use JavaScriptSolidServer**: Production deployments, custom configuration, advanced features
173-
174-
**When to use jspod**: Quick demos, local development, "just want it to work"
175-
176-
## 🛠️ How It Works
177-
178-
jspod is a thin wrapper that:
179-
180-
1. Provides sensible defaults
181-
2. Creates beautiful CLI output
182-
3. Manages the lifecycle of JavaScriptSolidServer
183-
4. Handles graceful shutdown
184-
185-
### Enabled Features
186-
187-
Under the hood, jspod runs JavaScriptSolidServer with these options:
188-
189-
| Feature | JSS Flag | Description |
190-
|---------|----------|-------------|
191-
| **WebSocket Notifications** | `--notifications` | Real-time updates via WebSockets |
192-
| **Content Negotiation** | `--conneg` | Turtle, JSON-LD, and more |
193-
| **Single-user Mode** | `--no-multiuser --single-user` | One pod per server (use `--multiuser` flag to change) |
194-
| **Identity Provider** | `--idp` | Built-in IDP so the rung-1 sign-in works out of the box |
195-
| **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. |
196-
| **Passkey Auth** | (built-in) | Automatic in JSS - no flag needed |
197-
| **WebID** | (built-in) | Core Solid protocol feature |
198-
199-
### The page is the data
200-
201-
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*.
202-
203-
The browser source is two files in this npm package:
204-
205-
- [`data-browser.js`](./data-browser.js) — finds `#dataisland`, renders to `#mashlib`, makes URIs clickable
206-
- [`data-browser.css`](./data-browser.css) — system font, cream background, soft card
207-
208-
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.
209-
210-
### Default Configuration
211-
212-
```javascript
213-
{
214-
port: 5444, // Memorable, low collision with common dev servers
215-
host: '127.0.0.1', // Localhost-only by default (rung-1 credentials)
216-
root: './pod-data', // Local data directory
217-
multiuser: false, // Single pod per server
218-
TOKEN_SECRET: (per-pod) // Auto-generated on first run and persisted at
219-
// <root>/.token-secret (mode 0600). Override via
220-
// the TOKEN_SECRET env var for operator control.
221-
}
222-
```
223-
224-
## 🎯 First Run Guide
225-
226-
**Step 1**: Start the server
227-
```bash
228-
npx jspod
229-
```
230-
231-
**Step 2**: Your browser opens automatically to `http://localhost:5444`
232-
233-
> 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.
234-
235-
**Step 3**: Sign in (rung 1 of the auth ladder)
236-
237-
The first time you start jspod, an IDP account is seeded with deliberately weak default credentials:
238-
239-
| Field | Value |
240-
| -------- | ----- |
241-
| Username | `me` |
242-
| Password | `me` |
243-
244-
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`.
245-
246-
> **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.
247-
248-
**Step 4**: Climb the ladder
249-
250-
| Rung | Auth | How |
251-
| ---- | --------------------- | -------------------------------------------- |
252-
| 0 | None | `npx jspod --no-auth` (demos / dev only) |
253-
| 1 | `me` / `me` | **Default.** Localhost-only. |
254-
| 2 | Your password | Change it from your pod's account settings |
255-
| 3 | Passkey | Add a passkey from account settings |
256-
| 4 | Hardware key / MFA | Power-user setup |
257-
258-
Override the default password without going through the UI:
49+
Override the initial password without going through the UI:
25950

26051
```bash
26152
JSS_SINGLE_USER_PASSWORD='your-password' npx jspod
26253
```
26354

264-
**Step 5**: Start using your pod
265-
- Upload files, create resources from a Solid app
266-
- Your data stays on your server
267-
- Connect more apps — they all authenticate against your IDP
268-
269-
**Troubleshooting**:
270-
- **Port in use?** Run `jspod --port 5445`
271-
- **Data location?** Check `./pod-data` directory
272-
- **Can't register?** Make sure your browser supports WebAuthn (Chrome, Firefox, Safari, Edge all work)
273-
274-
## 📖 Learn More
275-
276-
### What is Solid?
277-
278-
[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.
279-
280-
### Resources
281-
282-
- **jspod**: https://github.com/JavaScriptSolidServer/jspod
283-
- **JavaScriptSolidServer**: https://github.com/JavaScriptSolidServer/JavaScriptSolidServer
284-
- **Solid Project**: https://solidproject.org
285-
- **Solid Spec**: https://solidproject.org/TR/protocol
286-
- **WebID**: https://www.w3.org/2005/Incubator/webid/spec
287-
288-
## 🤝 Contributing
55+
## Configuration
28956

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

292-
**Philosophy**:
293-
- Simple over complex
294-
- Defaults over configuration
295-
- Works over features
63+
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.
29664

297-
See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
65+
## The data browser
29866

299-
## 📄 License
67+
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.
30068

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

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

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

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

309-
- **Issues**: https://github.com/JavaScriptSolidServer/jspod/issues
310-
- **Discussions**: https://github.com/JavaScriptSolidServer/jspod/discussions
311-
- **Solid Forum**: https://forum.solidproject.org
81+
## Links
31282

313-
---
83+
- [JavaScriptSolidServer (the substrate)](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer)
84+
- [Solid project](https://solidproject.org)
85+
- [Solid spec](https://solidproject.org/TR/protocol)
31486

315-
**Made with ❤️ for the Solid community**
87+
## License & credits
31688

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

0 commit comments

Comments
 (0)