Skip to content

Commit 2cb3d23

Browse files
melvincarvalhomelvincarvalho
committed
feat: initial release of JSSD v0.0.1
JavaScript Solid Server Daemon - a "just works" wrapper around JavaScriptSolidServer with beautiful CLI and sensible defaults. Features: - Zero configuration - run with npx jssd - Beautiful ASCII banner and terminal output - Sensible defaults (port 5444, notifications, content negotiation) - World-class documentation with feature tables and guides - Graceful shutdown handling - Production-ready with security guidance
0 parents  commit 2cb3d23

6 files changed

Lines changed: 548 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
node_modules/
2+
pod-data/
3+
*.log
4+
.env
5+
.DS_Store
6+
package-lock.json

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Melvin Carvalho
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
# JSSD - JavaScript Solid Server Daemon
2+
3+
> **Just works**. Batteries included. Zero configuration.
4+
5+
[![npm version](https://img.shields.io/npm/v/jssd.svg)](https://www.npmjs.com/package/jssd)
6+
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
7+
8+
**JSSD** 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
11+
12+
```bash
13+
# Run instantly with npx (no installation required!)
14+
npx jssd
15+
16+
# That's it! Your Solid server is running at http://localhost:3000
17+
```
18+
19+
## ✨ Features
20+
21+
### 🎯 Just Works
22+
- **Zero configuration** - Smart defaults for everything
23+
- **One command** - `npx jssd` 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 jssd
43+
```
44+
45+
### Global Installation
46+
47+
```bash
48+
npm install -g jssd
49+
jssd
50+
```
51+
52+
### Local Installation
53+
54+
```bash
55+
npm install jssd
56+
npx jssd
57+
```
58+
59+
## 🎮 Usage
60+
61+
### Basic Usage
62+
63+
```bash
64+
# Start with defaults (port 3000, single-user)
65+
jssd
66+
67+
# Custom port
68+
jssd --port 8080
69+
70+
# Custom data directory
71+
jssd --root /var/pods
72+
73+
# Multi-user mode
74+
jssd --multiuser
75+
```
76+
77+
### CLI Options
78+
79+
```
80+
Options:
81+
-p, --port <number> Port to listen on (default: 3000)
82+
-h, --host <address> Host to bind to (default: 0.0.0.0)
83+
-r, --root <path> Data directory (default: ./pod-data)
84+
--multiuser Enable multi-user mode
85+
--no-auth Disable authentication
86+
--help Show help message
87+
```
88+
89+
### Environment Variables
90+
91+
```bash
92+
# Set JWT secret (recommended for production)
93+
export TOKEN_SECRET="your-secret-key-here"
94+
95+
# Set environment
96+
export NODE_ENV="production"
97+
98+
# Run server
99+
jssd
100+
```
101+
102+
### Production Deployment
103+
104+
**⚠️ Important**: Before deploying to production:
105+
106+
1. **Set TOKEN_SECRET**
107+
```bash
108+
export TOKEN_SECRET="$(openssl rand -base64 32)"
109+
```
110+
111+
2. **Use a proper domain** (not localhost)
112+
- Passkeys require HTTPS in production
113+
- Get SSL cert (Let's Encrypt recommended)
114+
115+
3. **Run as a service**
116+
```bash
117+
# Example systemd service
118+
sudo systemctl enable jssd
119+
sudo systemctl start jssd
120+
```
121+
122+
4. **Set up backups**
123+
- Back up `./pod-data` directory
124+
- Contains all user data and credentials
125+
126+
5. **Monitor logs**
127+
```bash
128+
jssd --verbose > jssd.log 2>&1
129+
```
130+
131+
## 🏃 Quickstart Examples
132+
133+
### Personal Pod
134+
135+
```bash
136+
# Start your personal Solid pod
137+
jssd
138+
139+
# Visit http://localhost:3000 in your browser
140+
# Register with passkey, start storing data!
141+
```
142+
143+
### Multi-User Server
144+
145+
```bash
146+
# Run a server for multiple users
147+
jssd --multiuser --port 443 --root /var/solid-pods
148+
149+
# Users can register and get their own pod space
150+
```
151+
152+
### Development Server
153+
154+
```bash
155+
# Run on custom port for development
156+
jssd --port 8080 --root ./dev-data
157+
```
158+
159+
## 🆚 JSSD vs JavaScriptSolidServer
160+
161+
| Feature | JavaScriptSolidServer | JSSD |
162+
|---------|----------------------|------|
163+
| Installation | `npm install -g javascript-solid-server` | `npx jssd` |
164+
| Configuration | Config file required | Smart defaults |
165+
| Commands | `jss start [options]` | `jssd` |
166+
| First run | 5+ steps | 1 command |
167+
| Use case | Power users, customization | Quick start, demos |
168+
169+
**When to use JavaScriptSolidServer**: Production deployments, custom configuration, advanced features
170+
171+
**When to use JSSD**: Quick demos, local development, "just want it to work"
172+
173+
## 🛠️ How It Works
174+
175+
JSSD is a thin wrapper that:
176+
177+
1. Provides sensible defaults
178+
2. Creates beautiful CLI output
179+
3. Manages the lifecycle of JavaScriptSolidServer
180+
4. Handles graceful shutdown
181+
182+
### Enabled Features
183+
184+
Under the hood, JSSD runs JavaScriptSolidServer with these options:
185+
186+
| Feature | JSS Flag | Description |
187+
|---------|----------|-------------|
188+
| **WebSocket Notifications** | `--notifications` | Real-time updates via WebSockets |
189+
| **Content Negotiation** | `--conneg` | Turtle, JSON-LD, and more |
190+
| **Single-user Mode** | `--no-multiuser` | One pod per server (use `--multiuser` flag to change) |
191+
| **Passkey Auth** | (built-in) | Automatic in JSS - no flag needed |
192+
| **WebID** | (built-in) | Core Solid protocol feature |
193+
194+
### Default Configuration
195+
196+
```javascript
197+
{
198+
port: 3000, // Easy to remember
199+
host: '0.0.0.0', // Accept connections from anywhere
200+
root: './pod-data', // Local data directory
201+
multiuser: false, // Single pod per server
202+
TOKEN_SECRET: (auto) // JWT secret (auto-generated, change for production)
203+
}
204+
```
205+
206+
## 🎯 First Run Guide
207+
208+
**Step 1**: Start the server
209+
```bash
210+
npx jssd
211+
```
212+
213+
**Step 2**: Open your browser to `http://localhost:3000`
214+
215+
**Step 3**: Register with a passkey
216+
- Click "Register" or "Sign Up"
217+
- Use your device's biometric auth (fingerprint, Face ID, etc.)
218+
- Your WebID will be created automatically
219+
220+
**Step 4**: Start using your pod!
221+
- Upload files, create resources
222+
- Use Solid apps to connect to your pod
223+
- Your data stays on your server
224+
225+
**Troubleshooting**:
226+
- **Port in use?** Run `jssd --port 3001`
227+
- **Data location?** Check `./pod-data` directory
228+
- **Can't register?** Make sure your browser supports WebAuthn (Chrome, Firefox, Safari, Edge all work)
229+
230+
## 📖 Learn More
231+
232+
### What is Solid?
233+
234+
[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.
235+
236+
### Resources
237+
238+
- **JSSD**: https://github.com/JavaScriptSolidServer/jssd
239+
- **JavaScriptSolidServer**: https://github.com/JavaScriptSolidServer/JavaScriptSolidServer
240+
- **Solid Project**: https://solidproject.org
241+
- **Solid Spec**: https://solidproject.org/TR/protocol
242+
- **WebID**: https://www.w3.org/2005/Incubator/webid/spec
243+
244+
## 🤝 Contributing
245+
246+
Contributions welcome! JSSD is intentionally simple - we want to keep it that way.
247+
248+
**Philosophy**:
249+
- Simple over complex
250+
- Defaults over configuration
251+
- Works over features
252+
253+
See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
254+
255+
## 📄 License
256+
257+
MIT - see [LICENSE](./LICENSE)
258+
259+
## 🙏 Credits
260+
261+
JSSD is built on top of the excellent [JavaScriptSolidServer](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer) by Melvin Carvalho and contributors.
262+
263+
## 💬 Support
264+
265+
- **Issues**: https://github.com/JavaScriptSolidServer/jssd/issues
266+
- **Discussions**: https://github.com/JavaScriptSolidServer/jssd/discussions
267+
- **Solid Forum**: https://forum.solidproject.org
268+
269+
---
270+
271+
**Made with ❤️ for the Solid community**
272+
273+
*"Solid made simple"*

‎count-ascii.js‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
#!/usr/bin/env node
2+
3+
// Count from user's screenshot
4+
const lines = [
5+
' ██╗███████╗███████╗██████╗ ',
6+
' ██║██╔════╝██╔════╝██╔══██╗ ',
7+
' ██║███████╗███████╗██║ ██║ ',
8+
' ██ ██║╚════██║╚════██║██║ ██║ ',
9+
' ╚█████╔╝███████║███████║██████╔╝ ',
10+
' ╚════╝ ╚══════╝╚══════╝╚═════╝ ',
11+
];
12+
13+
console.log('Current line lengths:\n');
14+
lines.forEach((line, i) => {
15+
console.log(`Row ${i + 3}: ${line.length} chars`);
16+
});
17+
18+
// Measure the ASCII content itself
19+
const asciiLines = [
20+
' ██╗███████╗███████╗██████╗ ',
21+
' ██║██╔════╝██╔════╝██╔══██╗',
22+
' ██║███████╗███████╗██║ ██║',
23+
'██ ██║╚════██║╚════██║██║ ██║',
24+
'╚█████╔╝███████║███████║██████╔╝',
25+
' ╚════╝ ╚══════╝╚══════╝╚═════╝ ',
26+
];
27+
28+
console.log('\nASCII content lengths:\n');
29+
asciiLines.forEach((line, i) => {
30+
console.log(`Line ${i + 1}: "${line}" = ${line.length} chars`);
31+
});

0 commit comments

Comments
 (0)