Awesome Open Source
Awesome Open Source

Community Solid Server

Build Status Coverage Status npm version

An open and modular implementation of the Solid specifications

  • Community Solid Server is open software to provide people with their own Solid Pod.

  • It will give developers an environment to create and test new Solid applications.

  • Its modular architecture allows trying out new ideas on the server side and thereby shape the future of Solid.

Current status

This server is in beta stage, which means you can start using it for developing and testing apps, with some limitations:

  • User account / pod creation is not yet supported fully, and you must rely on an external identity provider to log you in and authenticate your WebID. solid/node-solid-server or any other pod provider can serve this purpose, and all you need to do is pass in an external WebID when creating pods. More information on creating pods can be found under Interacting with the server.
  • The spec is still under active development, and as such some features (like trustedApps) are not yet implemented because they are likely to change. If your users rely on this functionality, migrating is not yet recommended.

Your feedback is most welcome as issues on this repository.

However, you can already boot up the server, play around with it, and check how it is made.

The 📗 API documentation and the 📐 architectural diagram can help you find your way. The organization and structure of the classes and components in the src folder is designed to align with this architectural diagram to the extent possible (i.e. the ldp folder should contain all the components from the ldp section of the diagram.

If you are interested in helping out with the development of this server, be sure to have a look at the 📓 developer notes and 🛠️ good first issues.

Running the server

Configuring the server

Community Solid Server (CSS) uses ComponentJS to manage all configuration for the server. There are a variety of configuration files for common use cases in the config folder.

Additional recipes for configuring and deploying the server can be found at solid/community-server-recipes.

Parameter Default Description
--port, -p 3000
--baseUrl. -b "http://localhost:$PORT/" Needs to be set to the base URL of the server for authnetication and authorization to function.
--config, -c "config/config-default.json" config-default.json stores all data in memory. If you would like to persist data to your filesystem, try config-file.json
--mainModulePath, -m Absolute path to the package root from which ComponentJS module resolution should start.
--loggingLevel, -l "info"
--podTemplateFolder, -t "templates/pod" Folder containing the templates used for pod provisioning.
--rootFilePath, -f "./" Folder to start the server in when using a file-based config.
--sparqlEndpoint, -s Endpoint to call when using a SPARQL-based config.
--podConfigJson "./pod-config.json" JSON file to store pod configuration when using a dynamic config.

Installing and running locally

$ npm ci
$ npm start [-- ARGS]

Interacting with the server

CSS is still under active development, and as such the easiest and fastest way to understand what functionality is supported is to read the integration tests. This section is only intended as a high level summary of what's supported.

The server supports low-level interaction via HTTP methods, such as GET, PUT, HEAD, ...

Below, we provide several examples on how to interact with the server using curl.

POST: Creating a new pod

Create a pod using an external WebID for authentication:

curl -X POST -H "Content-Type: application/json" \
  -d '{"login": "timbl", "webId": "http://timbl.inrupt.net/profile/card#me"}' \
  http://localhost:3000/pods

PUT: Creating resources for a given URL

Create a plain text file:

curl -X PUT -H "Content-Type: text/plain" \
  -d "abc" \
  http://localhost:3000/myfile.txt

Create a turtle file:

curl -X PUT -H "Content-Type: text/turtle" \
  -d "<ex:s> <ex:p> <ex:o>." \
  http://localhost:3000/myfile.ttl

POST: Creating resources at a generated URL

Create a plain text file:

curl -X POST -H "Content-Type: text/plain" \
  -d "abc" \
  http://localhost:3000/

Create a turtle file:

curl -X POST -H "Content-Type: text/turtle" \
  -d "<ex:s> <ex:p> <ex:o>." \
  http://localhost:3000/

The response's Location header will contain the URL of the created resource.

GET: Retrieving resources

Retrieve a plain text file:

curl -H "Accept: text/plain" \
  http://localhost:3000/myfile.txt

Retrieve a turtle file:

curl -H "Accept: text/turtle" \
  http://localhost:3000/myfile.ttl

Retrieve a turtle file in a different serialization:

curl -H "Accept: application/ld+json" \
  http://localhost:3000/myfile.ttl

DELETE: Deleting resources

curl -X DELETE http://localhost:3000/myfile.txt

PATCH: Modifying resources

Currently, only patches over RDF resources are supported using SPARQL Update queries without WHERE clause.

curl -X PATCH -H "Content-Type: application/sparql-update" \
  -d "INSERT DATA { <ex:s2> <ex:p2> <ex:o2> }" \
  http://localhost:3000/myfile.ttl

HEAD: Retrieve resources headers

curl -I -H "Accept: text/plain" \
  http://localhost:3000/myfile.txt

OPTIONS: Retrieve resources communication options

curl -X OPTIONS -i http://localhost:3000/myfile.txt

Run using Docker

A Docker image is available to run the containerised Solid Community Server against your filesystem.

Common usage:

  • Build the Docker image
    docker build --rm -f Dockerfile -t css:latest .
    
  • Run the image against your ~/Solid directory on http://localhost:3000
    docker run --rm -v ~/Solid:/data -p 3000:3000 -it css:latest
    
  • Use alternative versions of the built in config. The filestorage is just the default configuration, you can override with any of the configurations included with the server
    docker run --rm -p 3000:3000 -it css:latest -c config/config-default.json
    
    Or override it with your own config mapped to the right directory
    docker run --rm -v ~/solid-config:/config -p 3000:3000 -it css:latest -c /config/my-config.json
    

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
typescript (10,877
rdf (82
solid (42
linked-data (39

Find Open Source By Browsing 7,000 Topics Across 59 Categories