solid-server in Node

Solid server in NodeJS

solid-server lets you run a Solid server on top of the file-system. You can use it as a command-line tool (easy) or as a library (advanced).

The solid test suite runs as part of GitHub Actions on this repository, ensuring that this server is always (to the best of our knowledge) fully spec compliant.

Solid Features supported

• [x] Linked Data Platform
• [x] Web Access Control
• [x] WebID+TLS Authentication
• [x] Real-time live updates (using WebSockets)
• [x] Identity provider for WebID
• [x] CORS proxy for cross-site data access
• [x] Group members in ACL
• [x] Email account recovery

Command Line Usage

Install

You can install and run the server either using Node.js directly or using Docker. This and the following sections describe the first approach, for the second approach see the section use Docker Section below.

Note: If using Git for Windows, it is helpful to use the -verbose flag to see the progress of the install.

To install, first install Node and then run the following

$ npm install -g solid-server

Run a single-user server (beginner)

The easiest way to setup solid-server is by running the wizard. This will create a config.json in your current folder

$ solid init

Note: If prompted for an SSL key and certificate, follow the instructions below.

To run your server, simply run solid start:

$ solid start
# Solid server (solid v0.2.24) running on https://localhost:8443/

If you prefer to use flags instead, the following would be the equivalent

$ solid start --port 8443 --ssl-key path/to/ssl-key.pem --ssl-cert path/to/ssl-cert.pem
# Solid server (solid v0.2.24) running on https://localhost:8443/

If you want to run solid on a particular folder (different from the one you are in, e.g. path/to/folder):

$ solid start --root path/to/folder --port 8443 --ssl-key path/to/ssl-key.pem --ssl-cert path/to/ssl-cert.pem
# Solid server (solid v0.2.24) running on https://localhost:8443/

By default, solid runs in debug all mode. To stop the debug logs, use -q, the quiet parameter.

$ DEBUG="solid:*" solid start -q
# use quiet mode and set debug to all
# DEBUG="solid:ACL" logs only debug.ACL's

Running in development environments

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.

If you want to run in multi-user mode on localhost, do the following: * configure the server as such with bin/solid-test init * start the server with bin/solid-test start * visit https://localhost:8443 and register a user, for instance 'myusername'. * Edit your hosts file and add a line 127.0.0.1 myusername.localhost * Now you can visit https://myusername.localhost:8443.

How do I get an SSL key and certificate?

You need an SSL certificate from a certificate authority, such as your domain provider or Let's Encrypt!.

For testing purposes, you can use bin/solid-test with a self-signed certificate, generated as follows:

$ openssl req -outform PEM -keyform PEM -new -x509 -sha256 -newkey rsa:2048 -nodes -keyout ../privkey.pem -days 365 -out ../fullchain.pem

Note that this example creates the fullchain.pem and privkey.pem files in a directory one level higher from the current, so that you don't accidentally commit your certificates to solid while you're developing.

If you would like to get rid of the browser warnings, import your fullchain.pem certificate into your 'Trusted Root Certificate' store.

Running Solid behind a reverse proxy (such as NGINX)

See Running Solid behind a reverse proxy.

Run multi-user server (intermediate)

You can run solid so that new users can sign up, in other words, get their WebIDs username.yourdomain.com.

Pre-requisites: - Get a 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

$ solid init
..
? Allow users to register their WebID (y/N) # write `y` here
..
$ solid start

Otherwise, if you want to use flags, this would be the equivalent

$ solid start --multiuser --port 8443 --ssl-cert /path/to/cert --ssl-key /path/to/key --root ./data

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.

How can I send emails to my users with my Gmail?

To use Gmail you may need to configure "Allow Less Secure Apps" in your Gmail account unless you are using 2FA in which case you would have to create an Application Specific password. You also may need to unlock your account with "Allow access to your Google account" to use SMTP.

also add to config.json

  "useEmail": true,
  "emailHost": "smtp.gmail.com",
  "emailPort": "465",
  "emailAuthUser": "xxxx@gmail.com",
  "emailAuthPass": "gmailPass"

Upgrading from version <5.3

Please take into account the v5.3 upgrade notes.

Upgrading from version <5.0

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.

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.

Extra flags (expert)

The command line tool has the following options

$ solid

  Usage: solid [options] [command]

  Commands:
    init [options]    create solid server configurations
    start [options]   run the Solid server

  Options:
    -h, --help     output usage information
    -V, --version  output the version number


$ solid init --help

  Usage: init [options]
  Create solid server configurations

  Options:
    -h, --help  output usage information
    --advanced  Ask for all the settings


$ solid start --help

  Usage: start [options]

  run the Solid server


  Options:

    --root [value]                Root folder to serve (default: './data')
    --port [value]                SSL port to use
    --server-uri [value]          Solid server uri (default: 'https://localhost:8443')
    --webid                       Enable WebID authentication and access control (uses HTTPS)
    --mount [value]               Serve on a specific URL path (default: '/')
    --config-path [value]
    --config-file [value]
    --db-path [value]
    --auth [value]                Pick an authentication strategy for WebID: `tls` or `oidc`
    --owner [value]               Set the owner of the storage (overwrites the root ACL file)
    --ssl-key [value]             Path to the SSL private key in PEM format
    --ssl-cert [value]            Path to the SSL certificate key in PEM format
    --no-reject-unauthorized      Accept self-signed certificates
    --multiuser                   Enable multi-user mode
    --idp [value]                 Obsolete; use --multiuser
    --no-live                     Disable live support through WebSockets
    --no-prep                     Disable Per Resource Events
    --proxy [value]               Obsolete; use --corsProxy
    --cors-proxy [value]          Serve the CORS proxy on this path
    --suppress-data-browser       Suppress provision of a data browser
    --data-browser-path [value]   An HTML file which is sent to allow users to browse the data (eg using mashlib.js)
    --suffix-acl [value]          Suffix for acl files (default: '.acl')
    --suffix-meta [value]         Suffix for metadata files (default: '.meta')
    --secret [value]              Secret used to sign the session ID cookie (e.g. "your secret phrase")
    --error-pages [value]         Folder from which to look for custom error pages files (files must be named <error-code>.html -- eg. 500.html)
    --force-user [value]          Force a WebID to always be logged in (useful when offline)
    --strict-origin               Enforce same origin policy in the ACL
    --use-email                   Do you want to set up an email service?
    --email-host [value]          Host of your email service
    --email-port [value]          Port of your email service
    --email-auth-user [value]     User of your email service
    --email-auth-pass [value]     Password of your email service
    --use-api-apps                Do you want to load your default apps on /api/apps?
    --api-apps [value]            Path to the folder to mount on /api/apps
    --redirect-http-from [value]  HTTP port or ','-separated ports to redirect to the solid server port (e.g. "80,8080").
    --server-name [value]         A name for your server (not required, but will be presented on your server's frontpage)
    --server-description [value]  A description of your server (not required)
    --server-logo [value]         A logo that represents you, your brand, or your server (not required)
    --enforce-toc                 Do you want to enforce Terms & Conditions for your service?
    --toc-uri [value]             URI to your Terms & Conditions
    --support-email [value]       The support email you provide for your users (not required)
    -q, --quiet                   Do not print the logs to console
    -h, --help                    output usage information

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_APPSenvironment variable, and --serverUri can be set with SOLID_SERVER_URI.

CLI flags take precedence over Environment variables, which take precedence over entries in the config file.

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.

Use Docker

Production usage

See the documentation to run Solid using docker and docker-compose.

We have automatic builds set up, so commits to master will trigger a build of https://hub.docker.com/r/nodesolidserver/node-solid-server.

Development usage

If you want to use Docker in development, you can build and run the image locally with either docker-compose —

git clone https://github.com/solid/node-solid-server
cd node-solid-server
docker-compose up -d

— or these manual commands —

git clone https://github.com/solid/node-solid-server
cd node-solid-server
docker build -t node-solid-server .

docker run -p 8443:8443 --name solid node-solid-server

This will enable you to login to solid on https://localhost:8443 and then create a new account but not yet use that account. After a new account is made you will need to create an entry for it in your local (/etc/)hosts file in line with the account and subdomain, i.e. --

127.0.0.1   newsoliduser.localhost

You can modify the config within the docker container as follows:

• Copy the config.json to the current directory with: bash docker cp solid:/usr/src/app/config.json .
• Edit the config.json file
• Copy the file back with bash docker cp config.json solid:/usr/src/app/
• Restart the server with bash docker restart solid

Library Usage

Install Dependencies

npm install