1 | # solid-server in Node
|
2 |
|
3 | [![](https://img.shields.io/badge/project-Solid-7C4DFF.svg?style=flat-square)](https://github.com/solid/solid)
|
4 | [![Build Status](https://travis-ci.org/solid/node-solid-server.svg?branch=master&style=flat-square)](https://travis-ci.org/solid/node-solid-server)
|
5 | [![NPM Version](https://img.shields.io/npm/v/solid-server.svg?style=flat-square)](https://npm.im/solid-server)
|
6 | [![Gitter chat](https://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg?style=flat-square)](http://gitter.im/solid/node-solid-server)
|
7 |
|
8 | > [Solid](https://github.com/solid) server in [NodeJS](https://nodejs.org/)
|
9 |
|
10 | `solid-server` lets you run a Solid server on top of the file-system. You can use it as a [command-line tool](https://github.com/solid/node-solid-server/blob/master/README.md#command-line-usage) (easy) or as a [library](https://github.com/solid/node-solid-server/blob/master/README.md#library-usage) (advanced).
|
11 |
|
12 | ## Solid Features supported
|
13 | - [x] [Linked Data Platform](http://www.w3.org/TR/ldp/)
|
14 | - [x] [Web Access Control](http://www.w3.org/wiki/WebAccessControl)
|
15 | - [x] [WebID+TLS Authentication](https://www.w3.org/2005/Incubator/webid/spec/tls/)
|
16 | - [x] [Real-time live updates](https://github.com/solid/solid-spec#subscribing) (using WebSockets)
|
17 | - [x] Identity provider for WebID
|
18 | - [x] CORS proxy for cross-site data access
|
19 | - [x] Group members in ACL
|
20 | - [x] Email account recovery
|
21 |
|
22 | ## Command Line Usage
|
23 |
|
24 | ### Install
|
25 |
|
26 | You can install and run the server either using Node.js directly or using
|
27 | [Docker](https://www.docker.com/). This and the following sections describe the
|
28 | first approach, for the second approach see the section [use Docker](#use-docker)
|
29 | Section below.
|
30 |
|
31 | To install, first install [Node](https://nodejs.org/en/) and then run the following
|
32 |
|
33 | ```bash
|
34 | $ npm install -g solid-server
|
35 | ```
|
36 |
|
37 | ### Run a single-user server (beginner)
|
38 |
|
39 | The easiest way to setup `solid-server` is by running the wizard. This will create a `config.json` in your current folder
|
40 |
|
41 | ```bash
|
42 | $ solid init
|
43 | ```
|
44 | **Note**: If prompted for an SSL key and certificate, follow the instructions below.
|
45 |
|
46 | To run your server, simply run `solid start`:
|
47 |
|
48 | ```bash
|
49 | $ solid start
|
50 | # Solid server (solid v0.2.24) running on https://localhost:8443/
|
51 | ```
|
52 |
|
53 | If you prefer to use flags instead, the following would be the equivalent
|
54 |
|
55 | ```bash
|
56 | $ solid start --port 8443 --ssl-key path/to/ssl-key.pem --ssl-cert path/to/ssl-cert.pem
|
57 | # Solid server (solid v0.2.24) running on https://localhost:8443/
|
58 | ```
|
59 |
|
60 | If you want to run `solid` on a particular folder (different from the one you are in, e.g. `path/to/folder`):
|
61 |
|
62 | ```bash
|
63 | $ solid start --root path/to/folder --port 8443 --ssl-key path/to/ssl-key.pem --ssl-cert path/to/ssl-cert.pem
|
64 | # Solid server (solid v0.2.24) running on https://localhost:8443/
|
65 | ```
|
66 |
|
67 | ### Running in development environments
|
68 |
|
69 | Solid requires SSL certificates to be valid, so you cannot use self-signed certificates. To switch off this security feature in development environments, you can use the `bin/solid-test` executable, which unsets the `NODE_TLS_REJECT_UNAUTHORIZED` flag and sets the `rejectUnauthorized` option.
|
70 |
|
71 | If you want to run in multi-user mode on localhost, do the following:
|
72 | * configure the server as such with `bin/solid-test init`
|
73 | * start the server with `bin/solid-test start`
|
74 | * visit https://localhost:8443 and register a user, for instance 'myusername'.
|
75 | * Edit your hosts file and add a line `127.0.0.1 myusername.localhost`
|
76 | * Now you can visit https://myusername.localhost:8443.
|
77 |
|
78 | ##### How do I get an SSL key and certificate?
|
79 | You need an SSL certificate from a _certificate authority_, such as your domain provider or [Let's Encrypt!](https://letsencrypt.org/getting-started/).
|
80 |
|
81 | For testing purposes, you can use `bin/solid-test` with a _self-signed_ certificate, generated as follows:
|
82 |
|
83 | ```
|
84 | $ openssl req -outform PEM -keyform PEM -new -x509 -sha256 -newkey rsa:2048 -nodes -keyout ../privkey.pem -days 365 -out ../fullchain.pem
|
85 |
|
86 | ```
|
87 |
|
88 | Note that this example creates the `fullchain.pem` and `privkey.pem` files
|
89 | in a directory one level higher from the current, so that you don't
|
90 | accidentally commit your certificates to `solid` while you're developing.
|
91 |
|
92 | If you would like to get rid of the browser warnings, import your fullchain.pem certificate into your 'Trusted Root Certificate' store.
|
93 |
|
94 | ### Running Solid behind a reverse proxy (such as NGINX)
|
95 | See [Running Solid behind a reverse proxy](https://github.com/solid/node-solid-server/wiki/Running-Solid-behind-a-reverse-proxy).
|
96 |
|
97 | ### Run multi-user server (intermediate)
|
98 |
|
99 | You can run `solid` so that new users can sign up, in other words, get their WebIDs _username.yourdomain.com_.
|
100 |
|
101 | Pre-requisites:
|
102 | - Get a [Wildcard Certificate](https://en.wikipedia.org/wiki/Wildcard_certificate)
|
103 | - Add a Wildcard DNS record in your DNS zone (e.g.`*.yourdomain.com`)
|
104 | - (If you are running locally) Add the line `127.0.0.1 *.localhost` to `/etc/hosts`
|
105 |
|
106 | ```bash
|
107 | $ solid init
|
108 | ..
|
109 | ? Allow users to register their WebID (y/N) # write `y` here
|
110 | ..
|
111 | $ solid start
|
112 | ```
|
113 |
|
114 | Otherwise, if you want to use flags, this would be the equivalent
|
115 |
|
116 | ```bash
|
117 | $ solid start --multiuser --port 8443 --ssl-cert /path/to/cert --ssl-key /path/to/key --root ./data
|
118 | ```
|
119 |
|
120 | Your users will have a dedicated folder under `./data` at `./data/<username>.<yourdomain.tld>`. Also, your root domain's website will be in `./data/<yourdomain.tld>`. New users can create accounts on `/api/accounts/new` and create new certificates on `/api/accounts/cert`. An easy-to-use sign-up tool is found on `/api/accounts`.
|
121 |
|
122 | ##### How can I send emails to my users with my Gmail?
|
123 |
|
124 | > To use Gmail you may need to configure ["Allow Less Secure Apps"](https://www.google.com/settings/security/lesssecureapps) in your Gmail account unless you are using 2FA in which case you would have to create an [Application Specific](https://security.google.com/settings/security/apppasswords) password. You also may need to unlock your account with ["Allow access to your Google account"](https://accounts.google.com/DisplayUnlockCaptcha) to use SMTP.
|
125 |
|
126 | also add to `config.json`
|
127 | ```
|
128 | "useEmail": true,
|
129 | "emailHost": "smtp.gmail.com",
|
130 | "emailPort": "465",
|
131 | "emailAuthUser": "xxxx@gmail.com",
|
132 | "emailAuthPass": "gmailPass"
|
133 | ```
|
134 |
|
135 | ### Upgrading from version <5.3
|
136 | Please take into account the [v5.3 upgrade notes](https://github.com/solid/node-solid-server/blob/master/CHANGELOG.md#530-upgrade-notes).
|
137 |
|
138 | ### Upgrading from version <5.0
|
139 | To upgrade from version 4 to the current version 5, you need to run a migration script, as explained in the [v5.0 upgrade notes](https://github.com/solid/node-solid-server/blob/master/CHANGELOG.md#500-upgrade-notes).
|
140 |
|
141 | Also, be aware that starting from version 5, third-party apps are untrusted by default. To trust a third-party app, before you can log in to it, you first need to go to your profile at https://example.com/profile/card#me (important to include the '#me' there), and then hover over the 'card' header to reveal the context menu. From there, select the 'A' symbol to go to your trusted applications pane, where you can whitelist third-party apps before using them. See also https://github.com/solid/node-solid-server/issues/1142 about streamlining this UX flow.
|
142 |
|
143 | ### Extra flags (expert)
|
144 | The command line tool has the following options
|
145 |
|
146 | ```
|
147 | $ solid
|
148 |
|
149 | Usage: solid [options] [command]
|
150 |
|
151 | Commands:
|
152 | init [options] create solid server configurations
|
153 | start [options] run the Solid server
|
154 |
|
155 | Options:
|
156 | -h, --help output usage information
|
157 | -V, --version output the version number
|
158 |
|
159 |
|
160 | $ solid init --help
|
161 |
|
162 | Usage: init [options]
|
163 | Create solid server configurations
|
164 |
|
165 | Options:
|
166 | -h, --help output usage information
|
167 | --advanced Ask for all the settings
|
168 |
|
169 |
|
170 | $ solid start --help
|
171 |
|
172 | Usage: start [options]
|
173 |
|
174 | run the Solid server
|
175 |
|
176 |
|
177 | Options:
|
178 |
|
179 | --root [value] Root folder to serve (default: './data')
|
180 | --port [value] SSL port to use
|
181 | --server-uri [value] Solid server uri (default: 'https://localhost:8443')
|
182 | --webid Enable WebID authentication and access control (uses HTTPS)
|
183 | --mount [value] Serve on a specific URL path (default: '/')
|
184 | --config-path [value]
|
185 | --config-file [value]
|
186 | --db-path [value]
|
187 | --auth [value] Pick an authentication strategy for WebID: `tls` or `oidc`
|
188 | --owner [value] Set the owner of the storage (overwrites the root ACL file)
|
189 | --ssl-key [value] Path to the SSL private key in PEM format
|
190 | --ssl-cert [value] Path to the SSL certificate key in PEM format
|
191 | --no-reject-unauthorized Accept self-signed certificates
|
192 | --multiuser Enable multi-user mode
|
193 | --idp [value] Obsolete; use --multiuser
|
194 | --no-live Disable live support through WebSockets
|
195 | --proxy [value] Obsolete; use --corsProxy
|
196 | --cors-proxy [value] Serve the CORS proxy on this path
|
197 | --suppress-data-browser Suppress provision of a data browser
|
198 | --data-browser-path [value] An HTML file which is sent to allow users to browse the data (eg using mashlib.js)
|
199 | --suffix-acl [value] Suffix for acl files (default: '.acl')
|
200 | --suffix-meta [value] Suffix for metadata files (default: '.meta')
|
201 | --secret [value] Secret used to sign the session ID cookie (e.g. "your secret phrase")
|
202 | --error-pages [value] Folder from which to look for custom error pages files (files must be named <error-code>.html -- eg. 500.html)
|
203 | --force-user [value] Force a WebID to always be logged in (useful when offline)
|
204 | --strict-origin Enforce same origin policy in the ACL
|
205 | --use-email Do you want to set up an email service?
|
206 | --email-host [value] Host of your email service
|
207 | --email-port [value] Port of your email service
|
208 | --email-auth-user [value] User of your email service
|
209 | --email-auth-pass [value] Password of your email service
|
210 | --use-api-apps Do you want to load your default apps on /api/apps?
|
211 | --api-apps [value] Path to the folder to mount on /api/apps
|
212 | --redirect-http-from [value] HTTP port or ','-separated ports to redirect to the solid server port (e.g. "80,8080").
|
213 | --server-name [value] A name for your server (not required, but will be presented on your server's frontpage)
|
214 | --server-description [value] A description of your server (not required)
|
215 | --server-logo [value] A logo that represents you, your brand, or your server (not required)
|
216 | --enforce-toc Do you want to enforce Terms & Conditions for your service?
|
217 | --toc-uri [value] URI to your Terms & Conditions
|
218 | --support-email [value] The support email you provide for your users (not required)
|
219 | -q, --quiet Do not print the logs to console
|
220 | -h, --help output usage information
|
221 | ```
|
222 |
|
223 | Instead of using flags, these same options can also be configured via environment variables taking the form of `SOLID_` followed by the `SNAKE_CASE` of the flag. For example `--api-apps` can be set via the `SOLID_API_APPS`environment variable, and `--serverUri` can be set with `SOLID_SERVER_URI`.
|
224 |
|
225 | CLI flags take precedence over Environment variables, which take precedence over entries in the config file.
|
226 |
|
227 | Configuring Solid via the config file can be a concise and convenient method and is the generally recommended approach. CLI flags can be useful when you would like to override a single configuration parameter, and using environment variables can be helpful in situations where you wish to deploy a single generic Docker image to multiple environments.
|
228 |
|
229 | ## Use Docker
|
230 |
|
231 |
|
232 | ### Production usage
|
233 |
|
234 | See the [documentation to run Solid using docker and docker-compose](https://github.com/solid/node-solid-server/tree/master/docker-image).
|
235 |
|
236 | We have automatic builds set up, so commits to master will trigger a build of https://hub.docker.com/r/nodesolidserver/node-solid-server.
|
237 |
|
238 | ### Development usage
|
239 |
|
240 | If you want to use Docker in development, then you can build it locally with:
|
241 |
|
242 | ```bash
|
243 | git clone https://github.com/solid/node-solid-server
|
244 | cd node-solid-server
|
245 | docker build -t node-solid-server .
|
246 | ```
|
247 |
|
248 | Run with:
|
249 | ```bash
|
250 | docker run -p 8443:8443 --name solid node-solid-server
|
251 | ```
|
252 |
|
253 | This will enable you to login to solid on https://localhost:8443 and then create a new account
|
254 | but not yet use that account. After a new account is made you will need to create an entry for
|
255 | it in your local (/etc/)hosts file in line with the account and subdomain, i.e. --
|
256 |
|
257 | ```pre
|
258 | 127.0.0.1 newsoliduser.localhost
|
259 | ```
|
260 |
|
261 | You can modify the config within the docker container as follows:
|
262 |
|
263 | - Copy the `config.json` to the current directory with:
|
264 | ```bash
|
265 | docker cp solid:/usr/src/app/config.json .
|
266 | ```
|
267 | - Edit the `config.json` file
|
268 | - Copy the file back with
|
269 | ```bash
|
270 | docker cp config.json solid:/usr/src/app/
|
271 | ```
|
272 | - Restart the server with
|
273 | ```bash
|
274 | docker restart solid
|
275 | ```
|
276 |
|
277 | ## Library Usage
|
278 |
|
279 | ### Install Dependencies
|
280 |
|
281 | ```
|
282 | npm install
|
283 | ```
|
284 |
|
285 | ### Library Usage
|
286 |
|
287 | The library provides two APIs:
|
288 |
|
289 | - `solid.createServer(settings)`: starts a ready to use
|
290 | [Express](http://expressjs.com) app.
|
291 | - `lnode(settings)`: creates an [Express](http://expressjs.com) that you can
|
292 | mount in your existing express app.
|
293 |
|
294 | In case the `settings` is not passed, then it will start with the following
|
295 | default settings.
|
296 |
|
297 | ```javascript
|
298 | {
|
299 | cache: 0, // Set cache time (in seconds), 0 for no cache
|
300 | live: true, // Enable live support through WebSockets
|
301 | root: './', // Root location on the filesystem to serve resources
|
302 | secret: 'node-ldp', // Express Session secret key
|
303 | cert: false, // Path to the ssl cert
|
304 | key: false, // Path to the ssl key
|
305 | mount: '/', // Where to mount Linked Data Platform
|
306 | webid: false, // Enable WebID+TLS authentication
|
307 | suffixAcl: '.acl', // Suffix for acl files
|
308 | corsProxy: false, // Where to mount the CORS proxy
|
309 | errorHandler: false, // function(err, req, res, next) to have a custom error handler
|
310 | errorPages: false // specify a path where the error pages are
|
311 | }
|
312 | ```
|
313 |
|
314 | Have a look at the following examples or in the
|
315 | [`examples/`](https://github.com/solid/node-solid-server/tree/master/examples) folder
|
316 | for more complex ones
|
317 |
|
318 | ##### Simple Example
|
319 |
|
320 | You can create a `solid` server ready to use using `solid.createServer(opts)`
|
321 |
|
322 | ```javascript
|
323 | var solid = require('solid-server')
|
324 | var ldp = solid.createServer({
|
325 | key: '/path/to/sslKey.pem',
|
326 | cert: '/path/to/sslCert.pem',
|
327 | webid: true
|
328 | })
|
329 | ldp.listen(3000, function() {
|
330 | // Started Linked Data Platform
|
331 | })
|
332 | ```
|
333 |
|
334 | ##### Advanced Example
|
335 |
|
336 | You can integrate `solid` in your existing [Express](https://expressjs.org)
|
337 | app, by mounting the `solid` app on a specific path using `lnode(opts)`.
|
338 |
|
339 | ```javascript
|
340 | var solid = require('solid-server')
|
341 | var app = require('express')()
|
342 | app.use('/test', solid(yourSettings))
|
343 | app.listen(3000, function() {
|
344 | // Started Express app with ldp on '/test'
|
345 | })
|
346 | ...
|
347 | ```
|
348 |
|
349 | ##### Logging
|
350 |
|
351 | Run your app with the `DEBUG` variable set:
|
352 |
|
353 | ```bash
|
354 | $ DEBUG="solid:*" node app.js
|
355 | ```
|
356 |
|
357 | ## Testing `solid` Locally
|
358 |
|
359 | #### Pre-Requisites
|
360 |
|
361 | In order to really get a feel for the Solid platform, and to test out `solid`,
|
362 | you will need the following:
|
363 |
|
364 | 1. A WebID profile and browser certificate from one of the Solid-compliant
|
365 | identity providers, such as [solidcommunity.net](https://solidcommunity.net).
|
366 |
|
367 | 2. A server-side SSL certificate for `solid` to use (see the section below
|
368 | on creating a self-signed certificate for testing).
|
369 |
|
370 | While these steps are technically optional (since you could launch it in
|
371 | HTTP/LDP-only mode), you will not be able to use any actual Solid features
|
372 | without them.
|
373 |
|
374 | #### Creating a certificate for local testing
|
375 |
|
376 | When deploying `solid` in production, we recommend that you go the
|
377 | usual Certificate Authority route to generate your SSL certificate (as you
|
378 | would with any website that supports HTTPS). However, for testing it locally,
|
379 | you can easily [generate a self-signed certificate for whatever domain you're
|
380 | Working with](https://github.com/solid/node-solid-server#how-do-i-get-an-ssl-key-and-certificate).
|
381 |
|
382 | #### Accessing your server
|
383 |
|
384 | If you started your `solid` server locally on port 8443 as in the example
|
385 | above, you would then be able to visit `https://localhost:8443` in the browser
|
386 | (ignoring the Untrusted Connection browser warnings as usual), where your
|
387 | `solid` server would redirect you to the default data viewer app.
|
388 |
|
389 | #### Editing your local `/etc/hosts`
|
390 |
|
391 | To test certificates and account creation on subdomains, `solid`'s test suite
|
392 | uses the following localhost domains: `nic.localhost`, `tim.localhost`, and
|
393 | `nicola.localhost`. You will need to create host file entries for these, in
|
394 | order for the tests to pass.
|
395 |
|
396 | Edit your `/etc/hosts` file, and append:
|
397 |
|
398 | ```
|
399 | # Used for unit testing solid
|
400 | 127.0.0.1 nic.localhost
|
401 | 127.0.0.1 tim.localhost
|
402 | 127.0.0.1 nicola.localhost
|
403 | ```
|
404 |
|
405 | #### Running the Unit Tests
|
406 |
|
407 | ```bash
|
408 | $ npm test
|
409 | # running the tests with logs
|
410 | $ DEBUG="solid:*" npm test
|
411 | ```
|
412 |
|
413 | In order to test a single component, you can run
|
414 |
|
415 | ```javascript
|
416 | npm run test-(acl|formats|params|patch)
|
417 | ```
|
418 |
|
419 | ## Blacklisted usernames
|
420 |
|
421 | By default Solid will not allow [certain usernames as they might cause
|
422 | confusion or allow vulnerabilies for social engineering](https://github.com/marteinn/The-Big-Username-Blacklist).
|
423 | This list is configurable via `config/usernames-blacklist.json`. Solid does not
|
424 | blacklist profanities by default.
|
425 |
|
426 | ## Quota
|
427 |
|
428 | By default, a file `serverSide.ttl.inactive` will be installed to new
|
429 | PODs. If you rename it to `serverSide.ttl`, it will currently set a
|
430 | quota for disk usage. This file is not writeable to users, only
|
431 | server administrators who are authorized on the backend can modify
|
432 | it. It is currently adviceable to remove it or set it inactive rather
|
433 | than set a large quota, because the current implementation will impair
|
434 | write performance if there is a lot of data.
|
435 |
|
436 | ## Get help and contribute
|
437 |
|
438 | Solid is only possible because of a large community of [contributors](https://github.com/solid/node-solid-server/blob/master/CONTRIBUTORS.md).
|
439 | A heartfelt thank you to everyone for all of your efforts!
|
440 |
|
441 | You can receive or provide help too:
|
442 |
|
443 | - [Join us in Gitter](https://gitter.im/solid/chat) to chat about Solid or to hang out with us :)
|
444 | - [NSS Gitter channel](https://gitter.im/solid/node-solid-server) for specific (installation) advice about this code base
|
445 | - [Create a new issue](https://github.com/solid/node-solid-server/issues/new) to report bugs
|
446 | - [Fix an issue](https://github.com/solid/node-solid-server/issues)
|
447 | - Reach out to Jackson at jacksonm@inrupt.com to become more involved in maintaining Node Solid Server
|
448 |
|
449 | Have a look at [CONTRIBUTING.md](https://github.com/solid/node-solid-server/blob/master/CONTRIBUTING.md).
|
450 |
|
451 | ## License
|
452 |
|
453 | [The MIT License](https://github.com/solid/node-solid-server/blob/master/LICENSE.md)
|