Skip to content

Commit 27368c9

Browse files
author
nicola
committed
updating doc
2 parents 2d5c2f6 + 3b6876f commit 27368c9

2 files changed

Lines changed: 106 additions & 43 deletions

File tree

‎README.md‎

Lines changed: 105 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,11 @@
44
[![NPM Version](https://img.shields.io/npm/v/ldnode.svg?style=flat)](https://npm.im/ldnode)
55
[![Gitter chat](https://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg?style=flat)](http://gitter.im/linkeddata/ldnode)
66

7-
Ldnode implements the [Linked Data Platform](http://www.w3.org/TR/ldp/) and [Solid](https://github.com/solid) in [NodeJS](https://nodejs.org/). This is all you need to run distributed Linked Data apps on top of the file system.
7+
Ldnode implements the [Linked Data Platform](http://www.w3.org/TR/ldp/) and
8+
[Solid](https://github.com/solid) in [NodeJS](https://nodejs.org/). This is all
9+
you need to run distributed Linked Data apps on top of the file system.
810

9-
You can run 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.
11+
You can run `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.
1012

1113
## Features
1214

@@ -17,8 +19,7 @@ You can run ldnode as a [command-line tool](https://github.com/linkeddata/ldnode
1719
- [x] Real-time live updates (using WebSockets)
1820
- [x] Identity provider for WebID+TLS
1921

20-
21-
## Command line tool
22+
## Command Line Usage
2223

2324
npm install -g ldnode
2425

@@ -50,52 +51,125 @@ Options:
5051
5152
```
5253

53-
### Run your server
54-
55-
#### Run the Linked Data Platform
56-
To start your Linked Data Platform server:
54+
### Running the server
5755

58-
```bash
59-
$ ldnode --port 80
60-
```
56+
#### Solid server mode (HTTPS / WebID enabled)
6157

62-
#### Run Solid
63-
To start your Solid server:
58+
To start `ldnode` in Solid server mode, you will need to enable the `--webid`
59+
flag, and also pass in a valid SSL key and certificate files:
6460

6561
```bash
66-
$ ldnode --webid --port 443 --cert /path/to/cert --key /path/to/key
62+
ldnode --webid --port 8443 --cert /path/to/cert --key /path/to/key
6763
```
68-
**Note**: In order to support WebID+TLS authentication you will need `--webid` but also the flags `--cert` and `--key` to specify the keypair of your SSL certificate, since WebID+TLS will only work over `HTTPS`.
6964

70-
#### Run Solid (multi-user!)
65+
#### Solid server mode with WebID Identity Provider
7166

7267
To allow users to create a WebID on your server:
7368

7469
```bash
75-
$ ldnode --webid --port 443 --cert /path/to/cert --key /path/to/key -idp --root ./accounts
70+
$ ldnode --webid --port 8443 --cert /path/to/cert --key /path/to/key -idp --root ./accounts
7671
```
7772

7873
Your users will have a dedicated folder under `./accounts`. Also, your root domain's website will be in `./accounts/yourdomain.tld`.
7974

8075
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`.
8176

77+
#### LDP-only server mode (HTTP, no WebID)
78+
79+
You can also use `ldnode` as a Linked Data Platform server in HTTP mode (note
80+
that this will not support WebID authentication, and so will not be able to use
81+
any Solid apps such as the default [Warp](https://github.com/linkeddata/warp)
82+
app).
83+
84+
```bash
85+
ldnode --port 8080
86+
```
87+
88+
### Testing `ldnode` Locally
89+
90+
#### Pre-Requisites
91+
92+
In order to really get a feel for the Solid platform, and to test out `ldnode`,
93+
you will need the following:
94+
95+
1. A WebID profile and browser certificate from one of the Solid-compliant
96+
identity providers, such as [databox.me](https://databox.me).
97+
98+
2. A server-side SSL certificate for `ldnode` to use (see the section below
99+
on creating a self-signed certificate for testing).
100+
101+
While these steps are technically optional (since you could launch it in
102+
HTTP/LDP-only mode), you will not be able to use any actual Solid features
103+
without them.
104+
105+
#### Creating a certificate for local testing
106+
107+
When deploying `ldnode` in production, we recommend that you go the
108+
usual Certificate Authority route to generate your SSL certificate (as you
109+
would with any website that supports HTTPS). However, for testing it locally,
110+
you can easily generate a self-signed certificate for whatever domain you're
111+
working with.
112+
113+
For example, here is how to generate a self-signed certificate for `localhost`
114+
using the `openssl` library:
115+
116+
```bash
117+
openssl genrsa 2048 > ../localhost.key
118+
openssl req -new -x509 -nodes -sha1 -days 3650 -key ../localhost.key -subj '/CN=*.localhost' > ../localhost.cert
119+
120+
ldnode --webid --port 8443 --cert ../localhost.cert --key ../localhost.key -v
121+
```
122+
123+
Note that this example creates the `localhost.cert` and `localhost.key` files
124+
in a directory one level higher from the current, so that you don't
125+
accidentally commit your certificates to `ldnode` while you're developing.
126+
127+
#### Accessing your server
128+
129+
If you started your `ldnode` server locally on port 8443 as in the example
130+
above, you would then be able to visit `https://localhost:8443` in the browser
131+
(ignoring the Untrusted Connection browser warnings as usual), where your
132+
`ldnode` server would redirect you to the default viewer app (see the `--skin`
133+
server config parameter), which is usually the
134+
[github.io/warp](https://linkeddata.github.io/warp/#/list/) file browser.
135+
136+
Accessing most Solid apps (such as Warp) will prompt you to select your browser
137+
side certificate which contains a WebID from a Solid storage provider (see
138+
the [pre-requisites](#pre-requisites) discussion above).
139+
140+
#### Running the Unit Tests
141+
142+
```bash
143+
$ npm test
144+
# running the tests with logs
145+
$ DEBUG="ldnode:*" npm test
146+
```
147+
148+
In order to test a single component, you can run
149+
150+
```javascript
151+
npm run test-(acl|formats|params|patch)
152+
```
82153

83154
## Library
84155

85-
### Install
156+
### Install Dependencies
86157

87158
```
88159
npm install
89160
```
90161

91-
### Usage
162+
### Library Usage
92163

93164
The library provides two APIs:
94165

95-
- `ldnode.createServer(settings)`: starts a ready to use [Express](http://expressjs.com) app.
96-
- `lnode(settings)`: creates an [Express](http://expressjs.com) that you can mount in your existing express app.
166+
- `ldnode.createServer(settings)`: starts a ready to use
167+
[Express](http://expressjs.com) app.
168+
- `lnode(settings)`: creates an [Express](http://expressjs.com) that you can
169+
mount in your existing express app.
97170

98-
In case the `settings` is not passed, then it will start with the following default settings.
171+
In case the `settings` is not passed, then it will start with the following
172+
default settings.
99173

100174
```javascript
101175
{
@@ -115,11 +189,13 @@ In case the `settings` is not passed, then it will start with the following defa
115189
}
116190
```
117191

118-
Have a look at the following examples or in the [`examples/`](https://github.com/linkeddata/ldnode/tree/master/examples) folder for more complex ones
192+
Have a look at the following examples or in the
193+
[`examples/`](https://github.com/linkeddata/ldnode/tree/master/examples) folder
194+
for more complex ones
119195

120-
##### Simple
196+
##### Simple Example
121197

122-
You can create an ldnode server ready to use using `ldnode.createServer(opts)`
198+
You can create an `ldnode` server ready to use using `ldnode.createServer(opts)`
123199

124200
```javascript
125201
var ldnode = require('ldnode')
@@ -133,9 +209,10 @@ ldp.listen(3000, function() {
133209
})
134210
```
135211

136-
##### Advanced
212+
##### Advanced Example
137213

138-
You can integrate ldnode in your existing [Express](https://expressjs.org) app, by mounting the ldnode app on a specific path using `lnode(opts)`.
214+
You can integrate `ldnode` in your existing [Express](https://expressjs.org)
215+
app, by mounting the `ldnode` app on a specific path using `lnode(opts)`.
139216

140217
```javascript
141218
var ldnode = require('ldnode')
@@ -147,28 +224,14 @@ app.listen(3000, function() {
147224
...
148225
```
149226

150-
##### Logs
227+
##### Logging
151228

152229
Run your app with the `DEBUG` variable set:
153230

154231
```bash
155232
$ DEBUG="ldnode:*" node app.js
156233
```
157234

158-
## Tests
159-
160-
```bash
161-
$ npm test
162-
# running the tests with logs
163-
$ DEBUG="ldnode:*" npm test
164-
```
165-
166-
In order to test a single component, you can run
167-
168-
```javascript
169-
npm run test-(acl|formats|params|patch)
170-
```
171-
172235
## Contributing
173236

174237
`ldnode` is only possible due to the excellent work of the following contributors:

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "ldnode",
33
"description": "Linked Data Platform",
4-
"version": "0.2.14",
4+
"version": "0.2.15",
55
"author": {
66
"name": "Tim Berners-Lee",
77
"email": "timbl@w3.org"

0 commit comments

Comments
 (0)