solid-server in Node
Solid Features supported
- Linked Data Platform
- Web Access Control
- WebID+TLS Authentication
- Real-time live updates (using WebSockets)
- Identity provider for WebID
- CORS proxy for cross-site data access
- Group members in ACL
- Email account recovery
Command Line Usage
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.
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 server (solid v0.2.24) running on
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
If you want to run
solid on a particular folder (different from the one you are in, e.g.
$ 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
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
If you want to run in multi-user mode on localhost, do the following:
- configure the server as such with
- start the server with
- visit https://localhost:8443 and register a user, for instance 'myusername'.
- Edit your hosts file and add a line
- 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
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)
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.
- Get a Wildcard Certificate
- Add a Wildcard DNS record in your DNS zone (e.g.
- (If you are running locally) Add the line
$ solid init..? Allow users to register their WebID # 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/<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
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
"useEmail": true, "emailHost": "smtp.gmail.com", "emailPort": "465", "emailAuthUser": "email@example.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 --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
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.
We have automatic builds set up, so commits to master will trigger a build of https://hub.docker.com/r/nodesolidserver/node-solid-server.
If you want to use Docker in development, then you can build it locally with:
git clone https://github.com/solid/node-solid-servercd node-solid-serverdocker 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. --
You can modify the config within the docker container as follows:
- Copy the
config.jsonto the current directory with:docker cp solid:/usr/src/app/config.json .
- Edit the
- Copy the file back withdocker cp config.json solid:/usr/src/app/
- Restart the server withdocker restart solid
The library provides two APIs:
solid.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
cache: 0 // Set cache time (in seconds), 0 for no cachelive: true // Enable live support through WebSocketsroot: './' // Root location on the filesystem to serve resourcessecret: 'node-ldp' // Express Session secret keycert: false // Path to the ssl certkey: false // Path to the ssl keymount: '/' // Where to mount Linked Data Platformwebid: false // Enable WebID+TLS authenticationsuffixAcl: '.acl' // Suffix for acl filescorsProxy: false // Where to mount the CORS proxyerrorHandler: false // function(err, req, res, next) to have a custom error handlererrorPages: false // specify a path where the error pages are
Have a look at the following examples or in the
for more complex ones
You can create a
solid server ready to use using
var solid =var ldp = solidldp
You can integrate
solid in your existing Express
app, by mounting the
solid app on a specific path using
var solid =var app =appapp...
Run your app with the
DEBUG variable set:
$ DEBUG="solid:*" node app.js
In order to really get a feel for the Solid platform, and to test out
you will need the following:
A WebID profile and browser certificate from one of the Solid-compliant identity providers, such as solid.community.
A server-side SSL certificate for
solidto 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
solid 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
Accessing your server
If you started your
solid 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
solid server would redirect you to the default data viewer app.
Editing your local
To test certificates and account creation on subdomains,
solid's test suite
uses the following localhost domains:
nicola.localhost. You will need to create host file entries for these, in
order for the tests to pass.
/etc/hosts file, and append:
# Used for unit testing solid 127.0.0.1 nic.localhost 127.0.0.1 tim.localhost 127.0.0.1 nicola.localhost
Running the Unit Tests
$ npm test# running the tests with logs$ DEBUG="solid:*" npm test
In order to test a single component, you can run
npm run test-acl|formats|params|patch
By default Solid will not allow certain usernames as they might cause
confusion or allow vulnerabilies for social engineering.
This list is configurable via
config/usernames-blacklist.json. Solid does not
blacklist profanities by default.
By default, a file
serverSide.ttl.inactive will be installed to new
PODs. If you rename it to
serverSide.ttl, it will currently set a
quota for disk usage. This file is not writeable to users, only
server administrators who are authorized on the backend can modify
it. It is currently adviceable to remove it or set it inactive rather
than set a large quota, because the current implementation will impair
write performance if there is a lot of data.
Get help and contribute
Solid is only possible because of a large community of contributors. A heartfelt thank you to everyone for all of your efforts!
You can receive or provide help too:
- Join us in Gitter to chat about Solid or to hang out with us :)
- NSS Gitter channel for specific (installation) advice about this code base
- Create a new issue to report bugs
- Fix an issue
- Reach out to Jackson at firstname.lastname@example.org to become more involved in maintaining Node Solid Server
Have a look at CONTRIBUTING.md.