nodeSolidServer · deiu · Mar 14, 2016 · Mar 14, 2016 · Mar 14, 2016 · Mar 14, 2016
diff --git 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 (<ctrl>+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
@@ -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 (<ctrl>+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 <ctrl>+c to stop')
+      }
+    })
   })
 }