From ed6f2ec8e953e84efa6701482d00f616cf6ecbc2 Mon Sep 17 00:00:00 2001 From: Joachim Van Herwegen Date: Wed, 12 Jun 2024 13:57:31 +0200 Subject: [PATCH] docs: Explain the provided configs --- config/README.md | 145 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 100 insertions(+), 45 deletions(-) diff --git a/config/README.md b/config/README.md index 4b03b91be..dd8784a27 100644 --- a/config/README.md +++ b/config/README.md @@ -1,67 +1,122 @@ # Configuration This folder contains several configurations that can be used to start up the server. +These can be used directly, or used as inspiration on how you would want to configure your server. All those configurations are created in the same way: features are enabled or disabled by choosing a specific option for every component. All components are represented by the subfolders found in the folders here: `ldp` contains all LDP related components, `identity` all IDP components, etc. Options are then chosen by importing 1 entry from every component subfolder. -In case none of the available options have the exact feature configuration you want, -it is always possible to not choose any of them and create your own custom version instead. +More information on how this can be done manually, +can be found in this [tutorial](https://github.com/CommunitySolidServer/tutorials/blob/main/custom-configurations.md). -## How to use +As manually changing server options can be cumbersome, +there is also an online [configuration generator](https://communitysolidserver.github.io/configuration-generator/). -The easiest way to create a new config is by creating a JSON-LD file -that imports one option from every component subfolder -(such as either `allow-all.json` or `webacl.json` from `ldp/authorization`). -In case none of the available options suffice, there are 2 other ways to handle this: +Below we give an overview of the main identifying features of the configurations. +We start with all features of the default configuration, +after which we will explain in which features the other ones differ from it. -### Append to an existing config +## default.json -In case the options mostly suffice, but they just need to do a bit more, -it might be possible to append to one of the solutions. +This is the configuration that is used if no configuration is provided when starting the server. +It stores all data in memory, so this server is perfect for quickly trying some things out, +but not if you want a persistent server. -For example, in case all the existing metadata parsers can remain, -but an additional one needs to be added, -you could import `ldp/metadata-parser/default.json` -and then add the following in your root config: +For authorization, it uses [Web Access Control (WAC)](https://solid.github.io/web-access-control-spec/), +it supports all [notification methods](https://solidproject.org/TR/notifications-protocol) implemented in CSS, +allows users to create accounts, pods, WebIDs, and use them for [Solid-OIDC](https://solid.github.io/solid-oidc/). -```json -{ - "@id": "urn:solid-server:default:MetadataParser", - "@type": "ParallelHandler", - "handlers": [ - { "@type": "MyNewParser" } - ] -} -``` +It is also initialized with an `index.html` page at root level, +with permissions set in such a way that everyone has full access to the server. -This will add the new parser to the list of metadata parsers. -The `@id` value is needed so Components.js knows which object to add the values to, -and the `@type` is needed so it can interpret the other fields (`handlers` in this case). +Although strictly not allowed by the Solid specification, +this configuration allows users to both write data at root level of the server, +and also create pods in subcontainers. +In all other configurations only or the other (or neither) will be allowed, +but here both are enabled for maximum flexibility when testing things out. -Note that generally it is only advised to append to ParallelHandlers or key/value maps. -In case the order is important this can not be guaranteed over separate files. +## file.json -### Create a new option +The most important difference with the `default.json` configuration is that this one stores its data as files on disk, +thereby making the data persistent. +Besides that, it also prevents data from being written to the root, +the only way to add data is to create a pod and add data there. +To still show something at root level when the server is started, +a static page is shown which can not be modified using standard Solid requests. -If a more drastic change is required, -the solution is to not import anything from that folder but instead write your own. +## file-acp.json -For example, in case you only want the slug parser but not any of the others, -you would have to not import anything from `ldp/metadata-parser` folder, -but instead have the following in your root config: +The only difference with `file.json`is that this uses +[Access Control Policy (ACP)](https://solid.github.io/authorization-panel/acp-specification/) +for authorization instead of WAC. -```json -{ - "@id": "urn:solid-server:default:MetadataParser", - "@type": "ParallelHandler", - "handlers": [ - { "@type": "SlugParser" } - ] -} -``` +## file-root.json -Don't forget that in some cases you would also have to copy some imports! -The existing options can be used as inspiration. +This configuration starts from `file.json`, but does not allow the creation of accounts. +Instead, it allows data to be written directly to the root of the server. +To make sure users can write data there after starting the server, +permissions have been set to grant everyone full access, +so this needs to be changed after starting the server. + +## file-root-pod.json + +The same idea as `file-root.json`, +but here it is done by creating an account with a pod +in the root of the server the first time it is started. +The credentials to this account are stored in the configuration so should be changed afterwards. +This has the advantage of both having your data at root level, +but also allowing you to authenticate using Solid-OIDC. + +## https-file-cli.json + +A variant of `file.json` that uses HTTPS of HTTP. +The required key and cert file paths need to be defined using two new CLI options: `--httpsKey` and `-httpCert`. + +## example-https-file.json + +Another way to define HTTPS, but this time through the configuration file itself instead of the CLI. +As can be seen in the configuration itself, two paths are defined, pointing to the key and cert files. +To actually use this solution, you need to update the paths in that file before running the server. + +## sparql-endpoint.json + +Sets up a server that uses a SPARQL endpoint to store the data. +Only RDF data can be stored on a server using this configuration. +For internal data, such as accounts, temporary OIDC resources, etc, +the servers uses non-RDF data formats. +While other configurations store this kind of data in the same backend as the Solid data, +this is not feasible when using a SPARQL endpoint. +For this reason, this configuration stores all that data in memory, +meaning this solution should not be used if you want persistent accounts. + +## sparql-endpoint-root.json + +This differs from `sparql-endpoint.json` in the same way as `file-root.json` differs from `file.json`. + +## sparql-file-storage.json + +Similar to `sparql-endpoint.json` with the main difference being +that here internal data is stored on disk instead of in memory. + +## memory-subdomains.json + +A memory-based server whose main differentiating feature is how pod URLs are constructed. +In most other configurations, pods are created by appending the chosen name to the base URL of the server, +so for a server running at `http://example.com/`, +choosing the name `test` for your pod would result in `http://example.com/test/`. +With this configuration, the name is used as a subdomain of the url instead, +so the above values would result in a pod at `http://test.example.com/` instead. + +## quota-file.json + +A file-based server that limits the amount of data a user can put in a pod. +The values in the configuration determine the limit. + +## path-routing.json + +This configuration serves as an example of how a server can be configured +to serve data from different backends depending on the URL that is used. +In this example, all data in the `/sparql/` container will be stored in a SPARQL backend, +and similarly for `/memory/` and `/file/`.