{"id":13555855,"url":"https://github.com/nodeSolidServer/node-solid-server","last_synced_at":"2025-04-03T08:32:21.162Z","repository":{"id":21013961,"uuid":"24306004","full_name":"nodeSolidServer/node-solid-server","owner":"nodeSolidServer","description":"Solid server on top of the file-system in NodeJS","archived":false,"fork":false,"pushed_at":"2024-10-24T00:18:37.000Z","size":13340,"stargazers_count":1781,"open_issues_count":298,"forks_count":303,"subscribers_count":77,"default_branch":"main","last_synced_at":"2024-10-29T15:09:57.271Z","etag":null,"topics":["running-code"],"latest_commit_sha":null,"homepage":"https://solidproject.org/for-developers/pod-server","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nodeSolidServer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-09-21T22:05:03.000Z","updated_at":"2024-10-25T09:29:33.000Z","dependencies_parsed_at":"2024-01-28T14:08:24.352Z","dependency_job_id":"ea4866b9-8f1e-4673-8c8c-9b73fc53ad59","html_url":"https://github.com/nodeSolidServer/node-solid-server","commit_stats":{"total_commits":2501,"total_committers":95,"mean_commits":"26.326315789473686","dds":0.8668532586965214,"last_synced_commit":"f5b2b5cd88e9201138ac4e65c498e0dc5c2c6539"},"previous_names":["linkeddata/node-ldp-httpd","linkeddata/ldnode","solid/node-solid-server"],"tags_count":166,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeSolidServer%2Fnode-solid-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeSolidServer%2Fnode-solid-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeSolidServer%2Fnode-solid-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeSolidServer%2Fnode-solid-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nodeSolidServer","download_url":"https://codeload.github.com/nodeSolidServer/node-solid-server/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246966168,"owners_count":20862010,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["running-code"],"created_at":"2024-08-01T12:03:27.624Z","updated_at":"2025-04-03T08:32:16.148Z","avatar_url":"https://github.com/nodeSolidServer.png","language":"JavaScript","readme":"# solid-server in Node\n\n[![](https://img.shields.io/badge/project-Solid-7C4DFF.svg?style=flat-square)](https://github.com/solid/solid)\n[![Build Status](https://travis-ci.org/solid/node-solid-server.svg?branch=master\u0026style=flat-square)](https://travis-ci.org/solid/node-solid-server)\n[![NPM Version](https://img.shields.io/npm/v/solid-server.svg?style=flat-square)](https://npm.im/solid-server)\n[![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)\n\n\u003e [Solid](https://github.com/solid) server in [NodeJS](https://nodejs.org/)\n\n`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).\n\nThe [solid test suite](https://github.com/nodeSolidServer/node-solid-server/blob/main/test/surface/run-solid-test-suite.sh) runs as part of GitHub Actions on this repository, ensuring that this server is always (to the best of our knowledge) fully spec compliant.\n\n## Solid Features supported\n- [x] [Linked Data Platform](http://www.w3.org/TR/ldp/)\n- [x] [Web Access Control](http://www.w3.org/wiki/WebAccessControl)\n- [x] [WebID+TLS Authentication](https://www.w3.org/2005/Incubator/webid/spec/tls/)\n- [x] [Real-time live updates](https://github.com/solid/solid-spec#subscribing) (using WebSockets)\n- [x] Identity provider for WebID\n- [x] CORS proxy for cross-site data access\n- [x] Group members in ACL\n- [x] Email account recovery\n\n## Command Line Usage\n\n### Install\n\nYou can install and run the server either using Node.js directly or using\n[Docker](https://www.docker.com/).  This and the following sections describe the\nfirst approach, for the second approach see the section [use Docker](#use-docker)\nSection below.\n\n**Note**: If using Git for Windows, it is helpful to use the -verbose flag to see the progress of the install.\n\nTo install, first install [Node](https://nodejs.org/en/) and then run the following\n\n```bash\n$ npm install -g solid-server\n```\n\n\n### Run a single-user server (beginner)\n\nThe easiest way to setup `solid-server` is by running the wizard. This will create a `config.json` in your current folder\n\n```bash\n$ solid init\n```\n**Note**: If prompted for an SSL key and certificate, follow the instructions below.\n\nTo run your server, simply run `solid start`:\n\n```bash\n$ solid start\n# Solid server (solid v0.2.24) running on https://localhost:8443/\n```\n\nIf you prefer to use flags instead, the following would be the equivalent\n\n```bash\n$ solid start --port 8443 --ssl-key path/to/ssl-key.pem --ssl-cert path/to/ssl-cert.pem\n# Solid server (solid v0.2.24) running on https://localhost:8443/\n```\n\nIf you want to run `solid` on a particular folder (different from the one you are in, e.g. `path/to/folder`):\n\n```bash\n$ solid start --root path/to/folder --port 8443 --ssl-key path/to/ssl-key.pem --ssl-cert path/to/ssl-cert.pem\n# Solid server (solid v0.2.24) running on https://localhost:8443/\n```\n\nBy default, `solid` runs in `debug all` mode. To stop the debug logs, use `-q`, the quiet parameter.\n\n```bash\n$ DEBUG=\"solid:*\" solid start -q\n# use quiet mode and set debug to all\n# DEBUG=\"solid:ACL\" logs only debug.ACL's\n\n```\n\n### Running in development environments\n\nSolid 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.\n\nIf you want to run in multi-user mode on localhost, do the following:\n* configure the server as such with `bin/solid-test init`\n* start the server with `bin/solid-test start`\n* visit https://localhost:8443 and register a user, for instance 'myusername'.\n* Edit your hosts file and add a line `127.0.0.1 myusername.localhost`\n* Now you can visit https://myusername.localhost:8443.\n\n##### How do I get an SSL key and certificate?\nYou need an SSL certificate from a _certificate authority_, such as your domain provider or [Let's Encrypt!](https://letsencrypt.org/getting-started/).\n\nFor testing purposes, you can use `bin/solid-test` with a _self-signed_ certificate, generated as follows:\n\n```\n$ openssl req -outform PEM -keyform PEM -new -x509 -sha256 -newkey rsa:2048 -nodes -keyout ../privkey.pem -days 365 -out ../fullchain.pem\n\n```\n\nNote that this example creates the `fullchain.pem` and `privkey.pem` files\nin a directory one level higher from the current, so that you don't\naccidentally commit your certificates to `solid` while you're developing.\n\nIf you would like to get rid of the browser warnings, import your fullchain.pem certificate into your 'Trusted Root Certificate' store.\n\n### Running Solid behind a reverse proxy (such as NGINX)\nSee [Running Solid behind a reverse proxy](https://github.com/solid/node-solid-server/wiki/Running-Solid-behind-a-reverse-proxy).\n\n### Run multi-user server (intermediate)\n\nYou can run `solid` so that new users can sign up, in other words, get their WebIDs _username.yourdomain.com_.\n\nPre-requisites:\n- Get a [Wildcard Certificate](https://en.wikipedia.org/wiki/Wildcard_certificate)\n- Add a Wildcard DNS record in your DNS zone (e.g.`*.yourdomain.com`)\n- (If you are running locally) Add the line `127.0.0.1 *.localhost` to `/etc/hosts`\n\n```bash\n$ solid init\n..\n? Allow users to register their WebID (y/N) # write `y` here\n..\n$ solid start\n```\n\nOtherwise, if you want to use flags, this would be the equivalent\n\n```bash\n$ solid start --multiuser --port 8443 --ssl-cert /path/to/cert --ssl-key /path/to/key --root ./data\n```\n\nYour users will have a dedicated folder under `./data` at `./data/\u003cusername\u003e.\u003cyourdomain.tld\u003e`. Also, your root domain's website will be in `./data/\u003cyourdomain.tld\u003e`. 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`.\n\n##### How can I send emails to my users with my Gmail?\n\n\u003e 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.\n\nalso add to `config.json`\n``` \n  \"useEmail\": true,\n  \"emailHost\": \"smtp.gmail.com\",\n  \"emailPort\": \"465\",\n  \"emailAuthUser\": \"xxxx@gmail.com\",\n  \"emailAuthPass\": \"gmailPass\"\n```\n\n### Upgrading from version \u003c5.3\nPlease take into account the [v5.3 upgrade notes](https://github.com/solid/node-solid-server/blob/master/CHANGELOG.md#530-upgrade-notes).\n\n### Upgrading from version \u003c5.0\nTo 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).\n\nAlso, 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.\n\n### Extra flags (expert)\nThe command line tool has the following options\n\n```\n$ solid\n\n  Usage: solid [options] [command]\n\n  Commands:\n    init [options]    create solid server configurations\n    start [options]   run the Solid server\n\n  Options:\n    -h, --help     output usage information\n    -V, --version  output the version number\n\n\n$ solid init --help\n\n  Usage: init [options]\n  Create solid server configurations\n\n  Options:\n    -h, --help  output usage information\n    --advanced  Ask for all the settings\n\n\n$ solid start --help\n\n  Usage: start [options]\n\n  run the Solid server\n\n\n  Options:\n\n    --root [value]                Root folder to serve (default: './data')\n    --port [value]                SSL port to use\n    --server-uri [value]          Solid server uri (default: 'https://localhost:8443')\n    --webid                       Enable WebID authentication and access control (uses HTTPS)\n    --mount [value]               Serve on a specific URL path (default: '/')\n    --config-path [value]\n    --config-file [value]\n    --db-path [value]\n    --auth [value]                Pick an authentication strategy for WebID: `tls` or `oidc`\n    --owner [value]               Set the owner of the storage (overwrites the root ACL file)\n    --ssl-key [value]             Path to the SSL private key in PEM format\n    --ssl-cert [value]            Path to the SSL certificate key in PEM format\n    --no-reject-unauthorized      Accept self-signed certificates\n    --multiuser                   Enable multi-user mode\n    --idp [value]                 Obsolete; use --multiuser\n    --no-live                     Disable live support through WebSockets\n    --proxy [value]               Obsolete; use --corsProxy\n    --cors-proxy [value]          Serve the CORS proxy on this path\n    --suppress-data-browser       Suppress provision of a data browser\n    --data-browser-path [value]   An HTML file which is sent to allow users to browse the data (eg using mashlib.js)\n    --suffix-acl [value]          Suffix for acl files (default: '.acl')\n    --suffix-meta [value]         Suffix for metadata files (default: '.meta')\n    --secret [value]              Secret used to sign the session ID cookie (e.g. \"your secret phrase\")\n    --error-pages [value]         Folder from which to look for custom error pages files (files must be named \u003cerror-code\u003e.html -- eg. 500.html)\n    --force-user [value]          Force a WebID to always be logged in (useful when offline)\n    --strict-origin               Enforce same origin policy in the ACL\n    --use-email                   Do you want to set up an email service?\n    --email-host [value]          Host of your email service\n    --email-port [value]          Port of your email service\n    --email-auth-user [value]     User of your email service\n    --email-auth-pass [value]     Password of your email service\n    --use-api-apps                Do you want to load your default apps on /api/apps?\n    --api-apps [value]            Path to the folder to mount on /api/apps\n    --redirect-http-from [value]  HTTP port or ','-separated ports to redirect to the solid server port (e.g. \"80,8080\").\n    --server-name [value]         A name for your server (not required, but will be presented on your server's frontpage)\n    --server-description [value]  A description of your server (not required)\n    --server-logo [value]         A logo that represents you, your brand, or your server (not required)\n    --enforce-toc                 Do you want to enforce Terms \u0026 Conditions for your service?\n    --toc-uri [value]             URI to your Terms \u0026 Conditions\n    --support-email [value]       The support email you provide for your users (not required)\n    -q, --quiet                   Do not print the logs to console\n    -h, --help                    output usage information\n```\n\nInstead 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`.\n\nCLI flags take precedence over Environment variables, which take precedence over entries in the config file.\n\nConfiguring 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.\n\n## Use Docker\n\n\n### Production usage\n\nSee the [documentation to run Solid using docker and docker-compose](https://github.com/solid/node-solid-server/tree/master/docker-image).\n\nWe have automatic builds set up, so commits to master will trigger a build of https://hub.docker.com/r/nodesolidserver/node-solid-server.\n\n### Development usage\n\nIf you want to use Docker in development, you can build and run the image locally with either docker-compose —\n\n```bash\ngit clone https://github.com/solid/node-solid-server\ncd node-solid-server\ndocker-compose up -d\n```\n\n — or these manual commands —\n\n```bash\ngit clone https://github.com/solid/node-solid-server\ncd node-solid-server\ndocker build -t node-solid-server .\n\ndocker run -p 8443:8443 --name solid node-solid-server\n```\n\n\nThis will enable you to login to solid on https://localhost:8443 and then create a new account\nbut not yet use that account. After a new account is made you will need to create an entry for \nit in your local (/etc/)hosts file in line with the account and subdomain, i.e. --\n\n```pre\n127.0.0.1\tnewsoliduser.localhost\n```\n\nYou can modify the config within the docker container as follows:\n\n - Copy the `config.json` to the current directory with: \n   ```bash\n   docker cp solid:/usr/src/app/config.json .\n   ```\n - Edit the `config.json` file\n - Copy the file back with \n   ```bash\n   docker cp config.json solid:/usr/src/app/\n   ```\n - Restart the server with \n   ```bash\n   docker restart solid\n   ```\n\n## Library Usage\n\n### Install Dependencies\n\n```\nnpm install\n```\n\n### Library Usage\n\nThe library provides two APIs:\n\n- `solid.createServer(settings)`: starts a ready to use\n    [Express](http://expressjs.com) app.\n- `lnode(settings)`: creates an [Express](http://expressjs.com) that you can\n    mount in your existing express app.\n\nIn case the `settings` is not passed, then it will start with the following\ndefault settings.\n\n```javascript\n{\n  cache:        0,           // Set cache time (in seconds), 0 for no cache\n  live:         true,        // Enable live support through WebSockets\n  root:         './',        // Root location on the filesystem to serve resources\n  secret:       'node-ldp',  // Express Session secret key\n  cert:         false,       // Path to the ssl cert\n  key:          false,       // Path to the ssl key\n  mount:        '/',         // Where to mount Linked Data Platform\n  webid:        false,       // Enable WebID+TLS authentication\n  suffixAcl:    '.acl',      // Suffix for acl files\n  corsProxy:    false,       // Where to mount the CORS proxy\n  errorHandler: false,       // function(err, req, res, next) to have a custom error handler\n  errorPages:   false        // specify a path where the error pages are\n}\n```\n\nHave a look at the following examples or in the\n[`examples/`](https://github.com/solid/node-solid-server/tree/master/examples) folder\nfor more complex ones\n\n##### Simple Example\n\nYou can create a `solid` server ready to use using `solid.createServer(opts)`\n\n```javascript\nvar solid = require('solid-server')\nvar ldp = solid.createServer({\n    key: '/path/to/sslKey.pem',\n    cert: '/path/to/sslCert.pem',\n    webid: true\n})\nldp.listen(3000, function() {\n  // Started Linked Data Platform\n})\n```\n\n##### Advanced Example\n\nYou can integrate `solid` in your existing [Express](https://expressjs.org)\napp, by mounting the `solid` app on a specific path using `lnode(opts)`.\n\n```javascript\nvar solid = require('solid-server')\nvar app = require('express')()\napp.use('/test', solid(yourSettings))\napp.listen(3000, function() {\n  // Started Express app with ldp on '/test'\n})\n...\n```\n\n##### Logging\n\nRun your app with the `DEBUG` variable set:\n\n```bash\n$ DEBUG=\"solid:*\" node app.js\n```\n\n## Testing `solid` Locally\n\n#### Pre-Requisites\n\nIn order to really get a feel for the Solid platform, and to test out `solid`,\nyou will need the following:\n\n1. A WebID profile and browser certificate from one of the Solid-compliant\n    identity providers, such as [solidcommunity.net](bourgeoa\n    community.net).\n\n2. A server-side SSL certificate for `solid` to use (see the section below\n    on creating a self-signed certificate for testing).\n\nWhile these steps are technically optional (since you could launch it in\nHTTP/LDP-only mode), you will not be able to use any actual Solid features\nwithout them.\n\n#### Creating a certificate for local testing\n\nWhen deploying `solid` in production, we recommend that you go the\nusual Certificate Authority route to generate your SSL certificate (as you\nwould with any website that supports HTTPS). However, for testing it locally,\nyou can easily [generate a self-signed certificate for whatever domain you're\nWorking with](https://github.com/solid/node-solid-server#how-do-i-get-an-ssl-key-and-certificate).\n\n#### Accessing your server\n\nIf you started your `solid` server locally on port 8443 as in the example\nabove, you would then be able to visit `https://localhost:8443` in the browser\n(ignoring the Untrusted Connection browser warnings as usual), where your\n`solid` server would redirect you to the default data viewer app.\n\n#### Editing your local `/etc/hosts`\n\nTo test certificates and account creation on subdomains, `solid`'s test suite\nuses the following localhost domains: `nic.localhost`, `tim.localhost`, and\n`nicola.localhost`. You will need to create host file entries for these, in\norder for the tests to pass.\n\nEdit your `/etc/hosts` file, and append:\n\n```\n# Used for unit testing solid\n127.0.0.1 nic.localhost\n127.0.0.1 tim.localhost\n127.0.0.1 nicola.localhost\n```\n\n#### Running the Unit Tests\n\n```bash\n$ npm test\n# running the tests with logs\n$ DEBUG=\"solid:*\" npm test\n```\n\nIn order to test a single component, you can run\n\n```javascript\nnpm run test-(acl|formats|params|patch)\n```\n\n## Blacklisted usernames\n\nBy default Solid will not allow [certain usernames as they might cause\nconfusion or allow vulnerabilies for social engineering](https://github.com/marteinn/The-Big-Username-Blacklist).\nThis list is configurable via `config/usernames-blacklist.json`. Solid does not\nblacklist profanities by default.\n\n## Quota\n\nBy default, a file `serverSide.ttl.inactive` will be installed to new\nPODs. If you rename it to `serverSide.ttl`, it will currently set a\nquota for disk usage.  This file is not writeable to users, only\nserver administrators who are authorized on the backend can modify\nit. It is currently adviceable to remove it or set it inactive rather\nthan set a large quota, because the current implementation will impair\nwrite performance if there is a lot of data.\n\n## Get help and contribute\n\nSolid is only possible because of a large community of [contributors](https://github.com/solid/node-solid-server/blob/master/CONTRIBUTORS.md).\nA heartfelt thank you to everyone for all of your efforts!\n\nYou can receive or provide help too:\n\n- [Join us in Gitter](https://gitter.im/solid/chat) to chat about Solid or to hang out with us :)\n- [NSS Gitter channel](https://gitter.im/solid/node-solid-server) for specific (installation) advice about this code base\n- [Create a new issue](https://github.com/solid/node-solid-server/issues/new) to report bugs\n- [Fix an issue](https://github.com/solid/node-solid-server/issues)\n- Reach out to @bourgeoa at alain.bourgeois10@gmail.com to become more involved in maintaining Node Solid Server\n\nHave a look at [CONTRIBUTING.md](https://github.com/solid/node-solid-server/blob/master/CONTRIBUTING.md).\n\n## License\n\n[The MIT License](https://github.com/solid/node-solid-server/blob/master/LICENSE.md)\n","funding_links":[],"categories":["JavaScript","others"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FnodeSolidServer%2Fnode-solid-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FnodeSolidServer%2Fnode-solid-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FnodeSolidServer%2Fnode-solid-server/lists"}