From ff9ff5a98b1e4a34aeacd27e969cb0934ba1e346 Mon Sep 17 00:00:00 2001 From: nicola Date: Sun, 13 Mar 2016 22:01:45 -0400 Subject: [PATCH 1/6] improved the first time user experience (command line) and the readme --- README.md | 125 +++++++++++++++++++++++++++----------------------- bin/ldnode.js | 10 +++- 2 files changed, 77 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index c2670aec9..091cfb570 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)'s 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-tool) (easy) or as a [library](https://github.com/linkeddata/ldnode/blob/master/README.md#library)(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,7 @@ Options: --force-user Force a WebID to always be logged in (useful when offline) ``` -### Running the server - -#### Solid server, Single User mode (HTTPS / WebID enabled) - -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). - -**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. - -```bash -ldnode --webid --port 8443 --cert /path/to/cert --key /path/to/key --create-admin -``` - -You can then visit your LDNode server (at `https://localhost:8443/`, if you're -running it locally), and set up a new account. - -You should then restart `ldnode`, this time without the `--create-admin` flag: - -```bash -ldnode --webid --port 8443 --cert /path/to/cert --key /path/to/key -``` - -#### Solid server, Multi-user Mode (Allows account creation) - -To allow users to create a WebID on your server: - -```bash -ldnode --webid --port 8443 --cert /path/to/cert --key /path/to/key -idp --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`. - -#### LDP-only server mode (HTTP, no WebID) - -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). - -```bash -ldnode --port 8080 -``` - -### Testing `ldnode` Locally +## Testing `ldnode` Locally #### Pre-Requisites @@ -132,8 +145,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 ``` 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') + } + }) }) } From f882738c1cdf631f659ec5cd5b7c4b6bdd825f1c Mon Sep 17 00:00:00 2001 From: Nicola Greco Date: Sun, 13 Mar 2016 22:04:03 -0400 Subject: [PATCH 2/6] s' not needed --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 091cfb570..2b9a7b944 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![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) -> [Solid](https://github.com/solid)'s server in [NodeJS](https://nodejs.org/) +> [Solid](https://github.com/solid) server in [NodeJS](https://nodejs.org/) 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-tool) (easy) or as a [library](https://github.com/linkeddata/ldnode/blob/master/README.md#library)(advanced). From a295387fbb1a8cb6b05aa950509ff6d5798dc436 Mon Sep 17 00:00:00 2001 From: Nicola Greco Date: Sun, 13 Mar 2016 22:05:27 -0400 Subject: [PATCH 3/6] Update README.md --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 2b9a7b944..1b18fcc4b 100644 --- a/README.md +++ b/README.md @@ -34,20 +34,20 @@ 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/ +# 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" +# 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/ +# Solid server (ldnode v0.2.24) running on https://localhost:8443/ ``` ##### How do I get the --ssl-key and the --ssl-cert? @@ -69,7 +69,7 @@ Pre-requisites: - (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 +$ 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`. From 6d18a810fddbc9a646f846f3f2b0a339f19d9938 Mon Sep 17 00:00:00 2001 From: Nicola Greco Date: Sun, 13 Mar 2016 22:05:51 -0400 Subject: [PATCH 4/6] missing space --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1b18fcc4b..e79566cb0 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ > [Solid](https://github.com/solid) server in [NodeJS](https://nodejs.org/) -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-tool) (easy) or as a [library](https://github.com/linkeddata/ldnode/blob/master/README.md#library)(advanced). +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-tool) (easy) or as a [library](https://github.com/linkeddata/ldnode/blob/master/README.md#library) (advanced). ## Solid Features supported - [x] [Linked Data Platform](http://www.w3.org/TR/ldp/) From 25d702780ded97351f46b3c40175ff9d0ffadd51 Mon Sep 17 00:00:00 2001 From: nicola Date: Sun, 13 Mar 2016 22:07:33 -0400 Subject: [PATCH 5/6] move testing down --- README.md | 157 +++++++++++++++++++++++++++--------------------------- 1 file changed, 79 insertions(+), 78 deletions(-) diff --git a/README.md b/README.md index 091cfb570..90c18b3b8 100644 --- a/README.md +++ b/README.md @@ -116,84 +116,6 @@ Options: --force-user Force a WebID to always be logged in (useful when offline) ``` -## Testing `ldnode` Locally - -#### Pre-Requisites - -In order to really get a feel for the Solid platform, and to test out `ldnode`, -you will need the following: - -1. A WebID profile and browser certificate from one of the Solid-compliant - identity providers, such as [databox.me](https://databox.me). - -2. A server-side SSL certificate for `ldnode` to use (see the section below - on creating a self-signed certificate for testing). - -While these steps are technically optional (since you could launch it in -HTTP/LDP-only mode), you will not be able to use any actual Solid features -without them. - -#### Creating a certificate for local testing - -When deploying `ldnode` in production, we recommend that you go the -usual Certificate Authority route to generate your SSL certificate (as you -would with any website that supports HTTPS). However, for testing it locally, -you can easily generate a self-signed certificate for whatever domain you're -working with. - -For example, here is how to generate a self-signed certificate for `localhost` -using the `openssl` library: - -```bash - -ldnode --webid --port 8443 --cert ../localhost.cert --key ../localhost.key -v -``` - -Note that this example creates the `localhost.cert` and `localhost.key` files -in a directory one level higher from the current, so that you don't -accidentally commit your certificates to `ldnode` while you're developing. - -#### Accessing your server - -If you started your `ldnode` server locally on port 8443 as in the example -above, you would then be able to visit `https://localhost:8443` in the browser -(ignoring the Untrusted Connection browser warnings as usual), where your -`ldnode` server would redirect you to the default viewer app (see the -`--file-browser` server config parameter), which is usually the -[github.io/warp](https://linkeddata.github.io/warp/#/list/) file browser. - -Accessing most Solid apps (such as Warp) will prompt you to select your browser -side certificate which contains a WebID from a Solid storage provider (see -the [pre-requisites](#pre-requisites) discussion above). - -#### Editing your local `/etc/hosts` - -To test certificates and account creation on subdomains, `ldnode`'s test suite -uses the following localhost domains: `nic.localhost`, `tim.localhost`, and -`nicola.localhost`. You will need to create host file entries for these, in -order for the tests to pass. - -Edit your `/etc/hosts` file, and append: - -``` -# Used for unit testing ldnode -127.0.0.1 nic.localhost, tim.localhost, nicola.localhost -``` - -#### Running the Unit Tests - -```bash -$ npm test -# running the tests with logs -$ DEBUG="ldnode:*" npm test -``` - -In order to test a single component, you can run - -```javascript -npm run test-(acl|formats|params|patch) -``` - ## Library ### Install Dependencies @@ -274,6 +196,85 @@ Run your app with the `DEBUG` variable set: $ DEBUG="ldnode:*" node app.js ``` +## Testing `ldnode` Locally + +#### Pre-Requisites + +In order to really get a feel for the Solid platform, and to test out `ldnode`, +you will need the following: + +1. A WebID profile and browser certificate from one of the Solid-compliant + identity providers, such as [databox.me](https://databox.me). + +2. A server-side SSL certificate for `ldnode` to use (see the section below + on creating a self-signed certificate for testing). + +While these steps are technically optional (since you could launch it in +HTTP/LDP-only mode), you will not be able to use any actual Solid features +without them. + +#### Creating a certificate for local testing + +When deploying `ldnode` in production, we recommend that you go the +usual Certificate Authority route to generate your SSL certificate (as you +would with any website that supports HTTPS). However, for testing it locally, +you can easily generate a self-signed certificate for whatever domain you're +working with. + +For example, here is how to generate a self-signed certificate for `localhost` +using the `openssl` library: + +```bash + +ldnode --webid --port 8443 --cert ../localhost.cert --key ../localhost.key -v +``` + +Note that this example creates the `localhost.cert` and `localhost.key` files +in a directory one level higher from the current, so that you don't +accidentally commit your certificates to `ldnode` while you're developing. + +#### Accessing your server + +If you started your `ldnode` server locally on port 8443 as in the example +above, you would then be able to visit `https://localhost:8443` in the browser +(ignoring the Untrusted Connection browser warnings as usual), where your +`ldnode` server would redirect you to the default viewer app (see the +`--file-browser` server config parameter), which is usually the +[github.io/warp](https://linkeddata.github.io/warp/#/list/) file browser. + +Accessing most Solid apps (such as Warp) will prompt you to select your browser +side certificate which contains a WebID from a Solid storage provider (see +the [pre-requisites](#pre-requisites) discussion above). + +#### Editing your local `/etc/hosts` + +To test certificates and account creation on subdomains, `ldnode`'s test suite +uses the following localhost domains: `nic.localhost`, `tim.localhost`, and +`nicola.localhost`. You will need to create host file entries for these, in +order for the tests to pass. + +Edit your `/etc/hosts` file, and append: + +``` +# Used for unit testing ldnode +127.0.0.1 nic.localhost, tim.localhost, nicola.localhost +``` + +#### Running the Unit Tests + +```bash +$ npm test +# running the tests with logs +$ DEBUG="ldnode:*" npm test +``` + +In order to test a single component, you can run + +```javascript +npm run test-(acl|formats|params|patch) +``` + + ## Contributing `ldnode` is only possible due to the excellent work of the following contributors: From 8b402cccad3ce5188125607468dfe83692e7a37f Mon Sep 17 00:00:00 2001 From: Nicola Greco Date: Sun, 13 Mar 2016 22:08:38 -0400 Subject: [PATCH 6/6] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index fd1b869c1..249d1edbf 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ > [Solid](https://github.com/solid) server in [NodeJS](https://nodejs.org/) -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-tool) (easy) or as a [library](https://github.com/linkeddata/ldnode/blob/master/README.md#library) (advanced). +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/) @@ -116,7 +116,7 @@ Options: --force-user Force a WebID to always be logged in (useful when offline) ``` -## Library +## Library Usage ### Install Dependencies