mirror of
https://github.com/CommunitySolidServer/CommunitySolidServer.git
synced 2024-10-03 14:55:10 +00:00
docs: Add basic documentation of config variables
* Add basic documentation of config variables * Address PR comments * Added additional documentation based on chat with Joachim * Import wiki to documentation folder The reason for this migration is that community members cannot submit PRs against the wiki to update documentation, so move them here so they can. Next steps are to deploy this folder as part of the docs CI setup. * Update README.md Co-authored-by: Joachim Van Herwegen <joachimvh@gmail.com> * Address Joachim's comments Co-authored-by: Joachim Van Herwegen <joachimvh@gmail.com>
This commit is contained in:
Ian Davis
GitHub
parent
54ff2317a5
commit
184a862297
91
README.md
91
README.md
@ -18,41 +18,86 @@ 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.
|
||||
Your feedback is most welcome
|
||||
as [issues on this repository](https://github.com/solid/community-server/issues/new).
|
||||
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](https://github.com/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](#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.
|
||||
|
||||
However, you can already boot up the server,
|
||||
play around with it,
|
||||
and check how it is made.
|
||||
<br>
|
||||
The [📗 API documentation](https://solid.github.io/community-server/docs/)
|
||||
and the [📐 architectural diagram](https://rubenverborgh.github.io/solid-server-architecture/solid-architecture-v1-3-0.pdf)
|
||||
can help you find your way.
|
||||
Your feedback is most welcome as [issues on this
|
||||
repository](https://github.com/solid/community-server/issues/new).
|
||||
|
||||
If you are interested in helping out with the development of this server,
|
||||
be sure to have a look at the [📓 developer notes](https://github.com/solid/community-server/wiki/Notes-for-developers)
|
||||
and [🛠️ good first issues](https://github.com/solid/community-server/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
|
||||
However, you can already boot up the server, play around with it, and check how
|
||||
it is made.
|
||||
|
||||
The [📗 API documentation](https://solid.github.io/community-server/docs/) and
|
||||
the [📐 architectural
|
||||
diagram](https://rubenverborgh.github.io/solid-server-architecture/solid-architecture-v1-3-0.pdf)
|
||||
can help you find your way. The organization and structure of the classes and
|
||||
components in the [src folder](/src) is designed to align with this
|
||||
architectural diagram to the extent possible (i.e. the [ldp folder](src/ldp)
|
||||
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](documentation/Notes-for-developers.md) and
|
||||
[🛠️ good first
|
||||
issues](https://github.com/solid/community-server/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
|
||||
|
||||
## Running the server
|
||||
|
||||
### Configuring the server
|
||||
Community Solid Server (CSS) uses
|
||||
[ComponentJS](https://componentsjs.readthedocs.io/en/latest/) 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](https://github.com/solid/community-server-recipes).
|
||||
|
||||
## Running locally
|
||||
| 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
|
||||
|
||||
```shell
|
||||
npm ci
|
||||
npm start
|
||||
$ npm ci
|
||||
$ npm start [-- ARGS]
|
||||
```
|
||||
|
||||
This will start up a server running on port 3000 with a backend storing all data in memory.
|
||||
More configurations with different backends can be found in the `config` folder.
|
||||
|
||||
## 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`, ...
|
||||
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`.
|
||||
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:
|
||||
```shell
|
||||
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
|
||||
|
||||
|
||||
28
documentation/Create-a-custom-configuration.md
Normal file
28
documentation/Create-a-custom-configuration.md
Normal file
@ -0,0 +1,28 @@
|
||||
By default, the server will start with a set of preconfigured components.
|
||||
These components are configured in [`config-default.json`](https://github.com/solid/community-server/tree/master/config/config-default.json).
|
||||
Learn more about the structure of this config file in the [notes for developers](https://github.com/solid/community-server/wiki/Notes-for-developers#add-components-to-configuration).
|
||||
|
||||
## Local development environment
|
||||
|
||||
_This guide assumes the server is installed locally by cloning the git repo._
|
||||
|
||||
When starting the server via `bin/server.js`, you can provide another config via the `-c` flag.
|
||||
For example:
|
||||
```bash
|
||||
$ bin/server.js -c config/config-default.json
|
||||
```
|
||||
|
||||
The command above will behave in the exact same way as just running `bin/server.js`, since `config/config-default.json` is the default server config for when `-c` is not provided.
|
||||
|
||||
If you for example create a copy from `config/config-default.json` named `my-config.json`, and make some adjustments, you can invoke it as follows:
|
||||
```bash
|
||||
$ bin/server.js -c my-config.json
|
||||
```
|
||||
|
||||
## Globally installed server
|
||||
|
||||
TODO: after making a first release, write a guide on how to create a custom config for it when it is globally installed.
|
||||
|
||||
## Including the server as dependency in another package.
|
||||
|
||||
TODO: after making a first release, write a guide on how to create a custom config for it when it is included as a dependency in another package.
|
||||
11
documentation/FAQ-for-developers.md
Normal file
11
documentation/FAQ-for-developers.md
Normal file
@ -0,0 +1,11 @@
|
||||
# Unable to include my component in the config file
|
||||
|
||||
You may be getting an error in the form of:
|
||||
```
|
||||
Error: Invalid components file... Could not expand the JSON-LD shortcut "MyClass". Are all the required modules available and JSON-LD contexts included?'
|
||||
```
|
||||
|
||||
This could have several causes:
|
||||
* The class is not exported from `index.ts`.
|
||||
* The used component name does not correspond to the exported class name.
|
||||
* The class has not been compiled using `npm run build`.
|
||||
83
documentation/Notes-for-developers.md
Normal file
83
documentation/Notes-for-developers.md
Normal file
@ -0,0 +1,83 @@
|
||||
The community server is fully written in [Typescript](https://www.typescriptlang.org/docs/home.html).
|
||||
|
||||
All changes should be done through [pull requests](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork). There are strict requirements from the linter and the test coverage before a PR is valid. These are configured to run automatically when trying to commit to git. Although there are no tests for it (yet), we strongly advice documenting with [TSdoc](https://github.com/microsoft/tsdoc).
|
||||
|
||||
The initial architecture document the project was started from can be found [here](https://rubenverborgh.github.io/solid-server-architecture/solid-architecture-v1-3-0.pdf). Even though some changes and additions have been made it is still mostly accurate.
|
||||
|
||||
A draft of the Solid spec can be found [here](https://github.com/solid/specification). It is still incomplete but much information can also be found in the issues. An older version can be found [here](https://github.com/solid/solid-spec/). Note that this last one is not fully accurate anymore but can still give a general overview of certain components.
|
||||
|
||||
Solid is inspired by LDP (Linked Data Platform) of which the spec can be found [here](https://www.w3.org/TR/ldp/). It doesn't strictly follow the spec though.
|
||||
|
||||
An example of how a Solid request needs to be parsed and handled can be found [here](https://github.com/solid/solid-architecture/blob/master/server/request-flow.md), including the correct status codes for specific responses.
|
||||
|
||||
As can be seen from the architecture, the main idea is that all components can easily be interchanged for other versions with a different implementation. This makes it imperative to reduce direct dependencies between components, which is why in general one class should never instantiate another class, it should only accept other objects through its constructors. This also makes testing much easier due to the independence of components.
|
||||
|
||||
Many RDF utility libraries can be found [here](https://rdf.js.org/).
|
||||
|
||||
## Add components to configuration
|
||||
|
||||
After implementing and testing your component, you have to _configure_ it so that it is enabled when starting the server.
|
||||
|
||||
### Dependency Injection
|
||||
|
||||
Due to the large number of components in this server, we make use of the _dependency injection_ framework [Components.js](https://github.com/LinkedSoftwareDependencies/Components.js).
|
||||
This framework allows us to configure our components in a JSON file.
|
||||
The advantage of this is that changing the configuration of components does not require any changes to the code, as one can just change the default configuration file, or provide a custom configuration file.
|
||||
|
||||
### Config file structure
|
||||
|
||||
In order to add a component to the default configuration,
|
||||
you will have to update [`config-default.json`](https://github.com/solid/community-server/tree/master/config/config-default.json),
|
||||
or any of its _imported_ files, which exist in the [`presets`](https://github.com/solid/community-server/tree/master/config/presets) folder.
|
||||
|
||||
A component in a configuration file has the following structure:
|
||||
```json
|
||||
{
|
||||
"@id": "urn:solid-server:my:ResourceStore",
|
||||
"@type": "PatchingStore",
|
||||
"PatchingStore:_source": {
|
||||
"@id": "urn:solid-server:my:ResourceStore_Converting"
|
||||
},
|
||||
"PatchingStore:_patcher": {
|
||||
"@id": "urn:solid-server:my:PatchHandler"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The important elements here are the following:
|
||||
* `"@id"`: _(optional)_ A unique identifier of this component, which allows it to be used as parameter values in different places.
|
||||
* `"type"`: The class name of the component. This must be a TypeScript class name that is exported via `index.ts`.
|
||||
* `"PatchingStore:_source"`: _(optional)_ A constructor parameter of the `PatchingStore` class. For other classes, this will always have the structure `"[ClassName]:_[parameterName]"`.
|
||||
|
||||
### Tips & Tricks
|
||||
|
||||
As shown in the example above, the parameters `"PatchingStore:_source"` and `"PatchingStore:_patcher"` contain another `"@id"` as value. These `"@id"`'s MUST always refer to another valid component, either defined inline or elsewhere.
|
||||
|
||||
Defining an `"@id"` for a component is only required when your component is being used in different places. If it's just being used once as parameter value of another component, you can omit `"@id"` and define the component inline.
|
||||
|
||||
If you edit this config file, `npm run build` MUST have been invoked before so that the TypeScript files have been properly compiled, and the `components/` folder has been populated. The `components/` folder consists of a declarative representation of the TypeScript classes which are referred to from the config file. Since these files are auto-generated, you should NEVER change these files manually. This folder is generated using [Components-Generator.js](https://github.com/LinkedSoftwareDependencies/Components-Generator.js/).
|
||||
|
||||
Learn more about Components.js in its [documentation](https://componentsjs.readthedocs.io/en/latest/).
|
||||
|
||||
[Click here to learn more about creating custom configs](https://github.com/solid/community-server/wiki/Create-a-custom-configuration).
|
||||
|
||||
## Releasing a new version
|
||||
|
||||
_This is only relevant to developers with push-access._
|
||||
|
||||
Making a new release can be done by following these steps:
|
||||
|
||||
```bash
|
||||
$ npm version [major|minor|patch] -m "Release version %s of the npm package."
|
||||
$ npm publish
|
||||
$ git push --tags
|
||||
$ git push origin master
|
||||
```
|
||||
|
||||
(If you call this often, you can [copy this script](https://github.com/rubensworks/dotfiles/blob/master/bin/npm-release) into your dotfiles.)
|
||||
|
||||
When calling `npm version`, a new entry in `CHANGELOG.md` will [automatically be generated](https://github.com/rubensworks/manual-git-changelog.js) based on the git commits since last release.
|
||||
The process will _halt_ until you confirm the changes in `CHANGELOG.md`.
|
||||
Before confirming, it is recommended to have a look at this file, move around the commits if needed, and save the file.
|
||||
|
||||
**Note:** The changelog generator will make use of git tags to determine the range commit. While `npm version` will generate a git tag, you can also create one manually if you want to follow a different release process.
|
||||
Loading…
x
Reference in New Issue
Block a user