Skip to content

Commit fe2da76

Browse files
Document pre-reqs, self-signed certificate for testing
Closes issue #173.
1 parent 8907cfa commit fe2da76

1 file changed

Lines changed: 87 additions & 22 deletions

File tree

‎README.md‎

Lines changed: 87 additions & 22 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
- [ ] Identity provider for WebID+TLS
1921

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

2324
npm install -g ldnode
2425

@@ -49,36 +50,97 @@ Options:
4950
5051
```
5152

52-
### Run your server
53-
To start your Linked Data Platform server:
53+
### Running the server
54+
55+
#### Pre-Requisites
56+
57+
In order to really get a feel for the Solid platform, and to test out `ldnode`,
58+
you will need the following:
59+
60+
1. A WebID profile and browser certificate from one of the Solid-compliant
61+
identity providers, such as [databox.me](https://databox.me).
62+
63+
2. A server-side SSL certificate for `ldnode` to use (see the section below
64+
on creating a self-signed certificate for testing).
65+
66+
While these steps are technically optional (since you could launch it in
67+
HTTP/LDP-only mode), you will not be able to use any actual Solid features
68+
without them.
69+
70+
#### Solid server mode (HTTPS / WebID enabled)
71+
72+
To start `ldnode` in Solid server mode, you will need to enable the `--webid`
73+
flag, and also pass in a valid SSL key and certificate files:
74+
75+
```bash
76+
ldnode --webid --port 8443 --cert /path/to/cert --key /path/to/key
77+
```
78+
79+
#### Creating a self-signed certificate
80+
81+
When deploying `ldnode` in production, we recommend that you go the
82+
usual Certificate Authority route to generate your SSL certificate (as you
83+
would with any website that supports HTTPS). However, for testing it locally,
84+
you can easily generate a self-signed certificate for whatever domain you're
85+
working with.
86+
87+
For example, here is how to generate a self-signed certificate for `localhost`
88+
using the `openssl` library:
5489

5590
```bash
56-
$ ldnode --port 80
91+
openssl genrsa 2048 > ../localhost.key
92+
openssl req -new -x509 -nodes -sha1 -days 3650 -key ../localhost.key -subj '/CN=*.localhost' > ../localhost.cert
93+
94+
ldnode --webid --port 8443 --cert ../localhost.cert --key ../localhost.key -v
5795
```
5896

59-
To start your Solid server:
97+
Note that this example creates the `localhost.cert` and `localhost.key` files
98+
in a directory one level higher from the current, so that you don't
99+
accidentally commit your certificates to `ldnode` while you're developing.
100+
101+
#### Accessing your server
102+
103+
If you started your `ldnode` server locally on port 8443 as in the example
104+
above, you would then be able to visit `https://localhost:8443` in the browser
105+
(ignoring the Untrusted Connection browser warnings as usual), where your
106+
`ldnode` server would redirect you to the default viewer app (see the `--skin`
107+
server config parameter), which is usually the
108+
[github.io/warp](https://linkeddata.github.io/warp/#/list/) file browser.
109+
110+
Accessing most Solid apps (such as Warp) will prompt you to select your browser
111+
side certificate which contains a WebID from a Solid storage provider (see
112+
the [pre-requisites](#pre-requisites) discussion above).
113+
114+
#### LDP-only server mode (HTTP, no WebID)
115+
116+
You can also use `ldnode` as a Linked Data Platform server in HTTP mode (note
117+
that this will not support WebID authentication, and so will not be able to use
118+
any Solid apps such as the default [Warp](https://github.com/linkeddata/warp)
119+
app).
60120

61121
```bash
62-
$ ldnode --webid --port 443 --cert /path/to/cert --key /path/to/key
122+
ldnode --port 8080
63123
```
64-
**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`.
65124

66125
## Library
67126

68-
### Install
127+
### Install Dependencies
69128

70129
```
71130
npm install
72131
```
73132

74-
### Usage
133+
### Library Usage
75134

76135
The library provides two APIs:
77136

78-
- `ldnode.createServer(settings)`: starts a ready to use [Express](http://expressjs.com) app.
79-
- `lnode(settings)`: creates an [Express](http://expressjs.com) that you can mount in your existing express app.
137+
- `ldnode.createServer(settings)`: starts a ready to use
138+
[Express](http://expressjs.com) app.
139+
- `lnode(settings)`: creates an [Express](http://expressjs.com) that you can
140+
mount in your existing express app.
80141

81-
In case the `settings` is not passed, then it will start with the following default settings.
142+
In case the `settings` is not passed, then it will start with the following
143+
default settings.
82144

83145
```javascript
84146
{
@@ -98,11 +160,13 @@ In case the `settings` is not passed, then it will start with the following defa
98160
}
99161
```
100162

101-
Have a look at the following examples or in the [`examples/`](https://github.com/linkeddata/ldnode/tree/master/examples) folder for more complex ones
163+
Have a look at the following examples or in the
164+
[`examples/`](https://github.com/linkeddata/ldnode/tree/master/examples) folder
165+
for more complex ones
102166

103-
##### Simple
167+
##### Simple Example
104168

105-
You can create an ldnode server ready to use using `ldnode.createServer(opts)`
169+
You can create an `ldnode` server ready to use using `ldnode.createServer(opts)`
106170

107171
```javascript
108172
var ldnode = require('ldnode')
@@ -116,9 +180,10 @@ ldp.listen(3000, function() {
116180
})
117181
```
118182

119-
##### Advanced
183+
##### Advanced Example
120184

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

123188
```javascript
124189
var ldnode = require('ldnode')
@@ -130,15 +195,15 @@ app.listen(3000, function() {
130195
...
131196
```
132197

133-
##### Logs
198+
##### Logging
134199

135200
Run your app with the `DEBUG` variable set:
136201

137202
```bash
138203
$ DEBUG="ldnode:*" node app.js
139204
```
140205

141-
## Tests
206+
## Testing
142207

143208
```bash
144209
$ npm test

0 commit comments

Comments
 (0)