diff --git a/README.md b/README.md index c2670aec9..249d1edbf 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,9 @@ [![NPM Version](https://img.shields.io/npm/v/ldnode.svg?style=flat)](https://npm.im/ldnode) [![Gitter chat](https://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg?style=flat)](http://gitter.im/linkeddata/ldnode) -> Implementation of a [Solid](https://github.com/solid)'s server spec in [NodeJS](https://nodejs.org/). -> This is all you need to run distributed Linked Data apps on top of the file system. +> [Solid](https://github.com/solid) server in [NodeJS](https://nodejs.org/) -You can use `ldnode` as a [command-line tool](https://github.com/linkeddata/ldnode/blob/master/README.md#command-line-tool) or as a [library](https://github.com/linkeddata/ldnode/blob/master/README.md#library) for your [Express](https://expressjs.com) app. +Ldnode lets you run a Solid server on top of the file-system. You can use it as a [command-line tool](https://github.com/linkeddata/ldnode/blob/master/README.md#command-line-usage) (easy) or as a [library](https://github.com/linkeddata/ldnode/blob/master/README.md#library-usage) (advanced). ## Solid Features supported - [x] [Linked Data Platform](http://www.w3.org/TR/ldp/) @@ -17,11 +16,75 @@ You can use `ldnode` as a [command-line tool](https://github.com/linkeddata/ldno - [x] Identity provider for WebID - [x] Proxy for cross-site data access - [ ] Group members in ACL +- [ ] Email account recovery ## Command Line Usage - npm install -g ldnode +### Install +To install, first install [Node](https://nodejs.org/en/) and then run the following + +```bash +$ npm install -g ldnode +``` + +### Run a single-user server (beginner) + +To run your server, simply run `ldnode` with the following flags: + +```bash +$ ldnode --port 8443 --ssl-key path/to/ssl-key.pem --ssl-cert path/to/ssl-cert.pem +# Solid server (ldnode v0.2.24) running on https://localhost:8443/ +``` + +First time user? If you have never run `ldnode` before, let's get you a WebID to access your server. +```bash +$ ldnode --port 8443 --ssl-key path/to/ssl-key.pem --ssl-cert path/to/ssl-cert.pem +# Action required: Create your admin account on https://localhost:8080/ +# When done, stop your server (+c) and restart without "--create-admin" +``` + +If you want to run `ldnode` on a particular folder (different from the one you are in, e.g. `path/to/folder`): +```bash +$ ldnode --root path/to/folder --port 8443 --ssl-key path/to/ssl-key.pem --ssl-cert path/to/ssl-cert.pem +# Solid server (ldnode v0.2.24) running on https://localhost:8443/ +``` + +##### How do I get the --ssl-key and the --ssl-cert? +You need an SSL certificate you get this from your domain provider or for free from [Let's Encrypt!](https://letsencrypt.org/getting-started/). + +If you don't have one yet, or you just want to test `ldnode`, generate a certificate (**DO NOT USE IN PRODUCTION**): +``` +$ openssl genrsa 2048 > ../localhost.key +$ openssl req -new -x509 -nodes -sha256 -days 3650 -key ../localhost.key -subj '/CN=*.localhost' > ../localhost.cert +``` + +### Run multi-user server (intermediate) + +You can run `ldnode` so that new users can sign up, in other words, get their WebIDs _username.yourdomain.com_. + +Pre-requisites: +- Get a [Wildcard Certificate](https://en.wikipedia.org/wiki/Wildcard_certificate) +- Add a Wildcard DNS record in your DNS zone (e.g.`*.yourdomain.com`) +- (If you are running locally) Add the line `127.0.0.1 *.localhost` to `/etc/hosts` + +```bash +$ ldnode --allow-signup --port 8443 --cert /path/to/cert --key /path/to/key --root ./accounts +``` + +Your users will have a dedicated folder under `./accounts`. Also, your root domain's website will be in `./accounts/yourdomain.tld`. New users can create accounts on `/accounts/new` and create new certificates on `/accounts/cert`. An easy-to-use sign-up tool is found on `/accounts`. + +### Run the Linked Data Platform (intermediate) +If you don't want WebID Authentication and Web Access Control, you can run a simple Linked Data Platform. + +```bash +# over HTTP +$ ldnode --port 8080 +# over HTTPS +$ ldnode --port 8080 --ssl-key key.pem --ssl-cert cert.pem +``` + +### Extra flags (expert) The command line tool has the following options ``` @@ -53,57 +116,87 @@ Options: --force-user Force a WebID to always be logged in (useful when offline) ``` -### Running the server +## Library Usage -#### Solid server, Single User mode (HTTPS / WebID enabled) +### Install Dependencies -To start `ldnode` in Solid Single User mode, you will need to enable the -`--webid` flag, and also pass in a valid SSL key and certificate files. -LDNode will use these certificates for its own server use (these are -different from the Admin user identity certificate discussed below). +``` +npm install +``` -**Initial Admin User Setup:** -The *first* time you run `ldnode`, you will also want to use the -`--create-admin` flag, to set up the initial Admin user identity and -certificates. +### Library Usage -```bash -ldnode --webid --port 8443 --cert /path/to/cert --key /path/to/key --create-admin -``` +The library provides two APIs: -You can then visit your LDNode server (at `https://localhost:8443/`, if you're -running it locally), and set up a new account. +- `ldnode.createServer(settings)`: starts a ready to use + [Express](http://expressjs.com) app. +- `lnode(settings)`: creates an [Express](http://expressjs.com) that you can + mount in your existing express app. -You should then restart `ldnode`, this time without the `--create-admin` flag: +In case the `settings` is not passed, then it will start with the following +default settings. -```bash -ldnode --webid --port 8443 --cert /path/to/cert --key /path/to/key +```javascript +{ + cache: 0, // Set cache time (in seconds), 0 for no cache + live: true, // Enable live support through WebSockets + root: './', // Root location on the filesystem to serve resources + secret: 'node-ldp', // Express Session secret key + cert: false, // Path to the ssl cert + key: false, // Path to the ssl key + mount: '/', // Where to mount Linked Data Platform + webid: false, // Enable WebID+TLS authentication + suffixAcl: '.acl', // Suffix for acl files + proxy: false, // Where to mount the proxy + errorHandler: false, // function(err, req, res, next) to have a custom error handler + errorPages: false // specify a path where the error pages are +} ``` -#### Solid server, Multi-user Mode (Allows account creation) +Have a look at the following examples or in the +[`examples/`](https://github.com/linkeddata/ldnode/tree/master/examples) folder +for more complex ones -To allow users to create a WebID on your server: +##### Simple Example -```bash -ldnode --webid --port 8443 --cert /path/to/cert --key /path/to/key -idp --root ./accounts +You can create an `ldnode` server ready to use using `ldnode.createServer(opts)` + +```javascript +var ldnode = require('ldnode') +var ldp = ldnode.createServer({ + key: '/path/to/sslKey.pem', + cert: '/path/to/sslCert.pem', + webid: true +}) +ldp.listen(3000, function() { + // Started Linked Data Platform +}) ``` -Your users will have a dedicated folder under `./accounts`. Also, your root domain's website will be in `./accounts/yourdomain.tld`. +##### Advanced Example -New users can create accounts on `/accounts/new` and create new certificates on `/accounts/cert`. An easy-to-use sign-up tool is found on `/accounts`. +You can integrate `ldnode` in your existing [Express](https://expressjs.org) +app, by mounting the `ldnode` app on a specific path using `lnode(opts)`. -#### LDP-only server mode (HTTP, no WebID) +```javascript +var ldnode = require('ldnode') +var app = require('express')() +app.use('/test', ldnode(yourSettings)) +app.listen(3000, function() { + // Started Express app with ldp on '/test' +}) +... +``` -You can also use `ldnode` as a Linked Data Platform server in HTTP mode (note -that this will not support WebID authentication, and so will not be able to use -any Solid apps such as the default [Warp](https://github.com/linkeddata/warp) -app). +##### Logging + +Run your app with the `DEBUG` variable set: ```bash -ldnode --port 8080 +$ DEBUG="ldnode:*" node app.js ``` -### Testing `ldnode` Locally +## Testing `ldnode` Locally #### Pre-Requisites @@ -132,8 +225,6 @@ For example, here is how to generate a self-signed certificate for `localhost` using the `openssl` library: ```bash -openssl genrsa 2048 > ../localhost.key -openssl req -new -x509 -nodes -sha256 -days 3650 -key ../localhost.key -subj '/CN=*.localhost' > ../localhost.cert ldnode --webid --port 8443 --cert ../localhost.cert --key ../localhost.key -v ``` @@ -183,85 +274,6 @@ In order to test a single component, you can run npm run test-(acl|formats|params|patch) ``` -## Library - -### Install Dependencies - -``` -npm install -``` - -### Library Usage - -The library provides two APIs: - -- `ldnode.createServer(settings)`: starts a ready to use - [Express](http://expressjs.com) app. -- `lnode(settings)`: creates an [Express](http://expressjs.com) that you can - mount in your existing express app. - -In case the `settings` is not passed, then it will start with the following -default settings. - -```javascript -{ - cache: 0, // Set cache time (in seconds), 0 for no cache - live: true, // Enable live support through WebSockets - root: './', // Root location on the filesystem to serve resources - secret: 'node-ldp', // Express Session secret key - cert: false, // Path to the ssl cert - key: false, // Path to the ssl key - mount: '/', // Where to mount Linked Data Platform - webid: false, // Enable WebID+TLS authentication - suffixAcl: '.acl', // Suffix for acl files - proxy: false, // Where to mount the proxy - errorHandler: false, // function(err, req, res, next) to have a custom error handler - errorPages: false // specify a path where the error pages are -} -``` - -Have a look at the following examples or in the -[`examples/`](https://github.com/linkeddata/ldnode/tree/master/examples) folder -for more complex ones - -##### Simple Example - -You can create an `ldnode` server ready to use using `ldnode.createServer(opts)` - -```javascript -var ldnode = require('ldnode') -var ldp = ldnode.createServer({ - key: '/path/to/sslKey.pem', - cert: '/path/to/sslCert.pem', - webid: true -}) -ldp.listen(3000, function() { - // Started Linked Data Platform -}) -``` - -##### Advanced Example - -You can integrate `ldnode` in your existing [Express](https://expressjs.org) -app, by mounting the `ldnode` app on a specific path using `lnode(opts)`. - -```javascript -var ldnode = require('ldnode') -var app = require('express')() -app.use('/test', ldnode(yourSettings)) -app.listen(3000, function() { - // Started Express app with ldp on '/test' -}) -... -``` - -##### Logging - -Run your app with the `DEBUG` variable set: - -```bash -$ DEBUG="ldnode:*" node app.js -``` ## Contributing diff --git a/bin/ldnode.js b/bin/ldnode.js index 4dde93e07..16975a3d7 100644 --- a/bin/ldnode.js +++ b/bin/ldnode.js @@ -143,7 +143,15 @@ function bin (argv) { return 1 } app.listen(argv.port, function () { - debug('LDP started on port ' + argv.port) + fs.readFile(path.resolve(__dirname, '../package.json'), 'utf-8', function (_, file) { + if (argv.createAdmin) { + console.log('Action required: Create your admin account on \u001b[4mhttps://localhost:' + argv.port + '/\u001b[0m') + console.log('When done, stop your server (+c) and restart without "--create-admin"') + } else { + console.log('Solid server (ldnode v' + JSON.parse(file).version + ') running on \u001b[4mhttps://localhost:' + argv.port + '/\u001b[0m') + console.log('Press +c to stop') + } + }) }) }