ldnode

Ldnode implements the Linked Data Platform and Solid in NodeJS. This is all you need to run distributed Linked Data apps on top of the file system.

You can run ldnode as a command-line tool or as a library for your Express app.

Features

• Linked Data Platform compliant HEAD, OPTIONS, GET, PUT, POST, PATCH, DELETE
• Proxy for cross-site data access
• Access control using Web Access Control
• WebID+TLS Authentication
• Real-time live updates (using WebSockets)
• Identity provider for WebID+TLS
• Group members in ACL

Command Line Usage

npm install -g ldnode

The command line tool has the following options

Usage: ldnode [options]

Options:
  -v, --verbose               Print the logs to console
  --version                   Print current ldnode version
  -m, --mount                 Relative URL from which to serve the Linked Data Platform (default: '/')
  -r, --root                  Root location on the filesystem to serve resources
  -p, --port                  Port to use
  -c, --cache                 Set cache time (in seconds), 0 for no cache
  -K, --key                   Path to the ssl key file
  -C, --cert                  Path to the ssl cert file
  --webid                     Enable WebID+TLS authentication
  -idp, --identity-provider   Allow registration of WebIDs
  -s, --secret                HTTP Session cookie secret key (e.g. "your secret phrase")
  -fU, --force-user           Force a WebID to always be logged in (useful when offline)
  -P, --proxy                 Use a proxy on example.tld/proxyPath
  --no-live                   Disable live support through WebSockets
  -sA, --suffix-acl           Suffix for acl files (default: '.acl')
  -sM, --suffix-meta          Suffix for metadata files (default: '.meta')
  --no-error-pages            Disable custom error pages (use Node.js default pages instead)
  --error-pages               Folder from which to look for custom error pages files (files must be named <error-code>.html -- eg. 500.html)
  --default-app               URI to use as a default app for resources (default: https://linkeddata.github.io/warp/#/list/)

Running the server

Solid server mode (HTTPS / WebID enabled)

To start ldnode in Solid server mode, you will need to enable the --webid flag, and also pass in a valid SSL key and certificate files:

ldnode --webid --port 8443 --cert /path/to/cert --key /path/to/key

Solid server mode with WebID Identity Provider

To allow users to create a WebID on your server:

$ 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 app).

ldnode --port 8080

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.

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:

openssl genrsa 2048 > ../localhost.key
openssl req -new -x509 -nodes -sha1 -days 3650 -key ../localhost.key -subj '/CN=*.localhost' > ../localhost.cert

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 --default-app server config parameter), which is usually the github.io/warp 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 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

$ npm test
# running the tests with logs
$ DEBUG="ldnode:*" npm test

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 app.
• lnode(settings): creates an Express 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.

{
  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/ folder for more complex ones

Simple Example

You can create an ldnode server ready to use using ldnode.createServer(opts)

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 app, by mounting the ldnode app on a specific path using lnode(opts).

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:

$ DEBUG="ldnode:*" node app.js

Contributing

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

Do you want to contribute?

• Join us in Gitter to help with development or to hang out with us :)
• Create a new issue to report bugs
• Fix an issue

Have a look at CONTRIBUTING.md.

License

MIT