diff --git a/README.md b/README.md index bc922c9..1cb99b0 100644 --- a/README.md +++ b/README.md @@ -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 Port to listen on (default: 5444) -h, --host
Host to bind to (default: 127.0.0.1) -r, --root 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 /.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 `/.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@/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 - // /.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 `/.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).