mirror of
https://github.com/CommunitySolidServer/CommunitySolidServer.git
synced 2024-10-03 14:55:10 +00:00
166 lines
9.1 KiB
Markdown
166 lines
9.1 KiB
Markdown
# Community Solid Server
|
||
|
||
<img src="https://raw.githubusercontent.com/CommunitySolidServer/CommunitySolidServer/main/templates/images/solid.svg" alt="[Solid logo]" height="150" align="right"/>
|
||
|
||
[](https://github.com/CommunitySolidServer/CommunitySolidServer/blob/main/LICENSE.md)
|
||
[](https://www.npmjs.com/package/@solid/community-server)
|
||
[](https://www.npmjs.com/package/@solid/community-server)
|
||
[](https://github.com/CommunitySolidServer/CommunitySolidServer/actions)
|
||
[](https://coveralls.io/github/CommunitySolidServer/CommunitySolidServer)
|
||
[](https://github.com/CommunitySolidServer/CommunitySolidServer/discussions)
|
||
[](https://gitter.im/CommunitySolidServer/community)
|
||
|
||
**The Community Solid Server is open software
|
||
that provides you with a [Solid](https://solidproject.org/) Pod and identity.
|
||
This Pod acts as your own personal storage space
|
||
so you can share data with people and Solid applications.**
|
||
|
||
As an open and modular implementation of the
|
||
[Solid specifications](https://solidproject.org/TR/),
|
||
the Community Solid Server is a great companion:
|
||
|
||
- 🧑🏽 **for people** who want to try out having their own Pod
|
||
|
||
- 👨🏿💻 **for developers** who want to create and test Solid apps
|
||
|
||
- 👩🏻🔬 **for researchers** who want to design new features for Solid
|
||
|
||
And, of course, for many others who like to experience Solid.
|
||
|
||
You can install the software locally or on your server
|
||
and get started with Solid immediately.
|
||
|
||
|
||
## ⚡ Running the server
|
||
To run the server, you will need [Node.js](https://nodejs.org/en/).
|
||
We support versions 14.2 and up.
|
||
<br>
|
||
If you do not use Node.js,
|
||
you can run a [Docker](https://www.docker.com/) version instead.
|
||
|
||
### 💻 Installing and running locally
|
||
After installing Node.js,
|
||
install the latest server version
|
||
from the [npm package repository](https://www.npmjs.com/):
|
||
|
||
```shell
|
||
npm install -g @solid/community-server
|
||
```
|
||
|
||
To run the server with in-memory storage, use:
|
||
```shell
|
||
community-solid-server # add parameters if needed
|
||
```
|
||
|
||
To run the server with your current folder as storage, use:
|
||
```shell
|
||
community-solid-server -c @css:config/file.json
|
||
```
|
||
|
||
### 📃 Installing and running from source
|
||
If you rather prefer to run the latest source code version,
|
||
or if you want to try a specific [branch](https://www.npmjs.com/) of the code,
|
||
you can use:
|
||
```shell
|
||
git clone https://github.com/CommunitySolidServer/CommunitySolidServer.git
|
||
cd CommunitySolidServer
|
||
npm ci
|
||
npm start -- # add parameters if needed
|
||
```
|
||
|
||
### 📦 Running via Docker
|
||
Docker allows you to run the server without having Node.js installed. Images are built on each tagged version and hosted on [Docker Hub](https://hub.docker.com/r/solidproject/community-server).
|
||
|
||
```shell
|
||
# Clone the repo to get access to the configs
|
||
git clone https://github.com/CommunitySolidServer/CommunitySolidServer.git
|
||
cd CommunitySolidServer
|
||
# Run the image, serving your `~/Solid` directory on `http://localhost:3000`
|
||
docker run --rm -v ~/Solid:/data -p 3000:3000 -it solidproject/community-server:latest
|
||
# Or use one of the built-in configurations
|
||
docker run --rm -p 3000:3000 -it solidproject/community-server -c config/default.json
|
||
# Or use your own configuration mapped to the right directory
|
||
docker run --rm -v ~/solid-config:/config -p 3000:3000 -it solidproject/community-server -c /config/my-config.json
|
||
```
|
||
|
||
### 🗃️ Helm Chart
|
||
The official [Helm](https://helm.sh/) Chart for Kubernetes deployment is maintained at [CommunitySolidServer/css-helm-chart](https://github.com/CommunitySolidServer/css-helm-chart) and published on [ArtifactHUB](https://artifacthub.io/packages/helm/community-solid-server/community-solid-server). There you will find complete installation instructions.
|
||
|
||
```
|
||
# Summary
|
||
helm repo add community-solid-server https://communitysolidserver.github.io/css-helm-chart/charts/
|
||
helm install my-css community-solid-server/community-solid-server
|
||
```
|
||
|
||
## 🔧 Configuring the server
|
||
The Community Solid Server is designed to be flexible
|
||
such that people can easily run different configurations.
|
||
This is useful for customizing the server with plugins,
|
||
testing applications in different setups,
|
||
or developing new parts for the server
|
||
without needing to change its base code.
|
||
|
||
### ⏱️ Parameters
|
||
An easy way to customize the server is
|
||
by passing parameters to the server command.
|
||
These parameters give you direct access
|
||
to some commonly used settings:
|
||
|
||
| parameter name | default value | description |
|
||
|------------------------|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
|
||
| `--port, -p` | `3000` | The TCP port on which the server should listen. |
|
||
| `--baseUrl, -b` | `http://localhost:$PORT/` | The base URL used internally to generate URLs. Change this if your server does not run on `http://localhost:$PORT/`. |
|
||
| `--loggingLevel, -l` | `info` | The detail level of logging; useful for debugging problems. Use `debug` for full information. |
|
||
| `--config, -c` | `@css:config/default.json` | The configuration for the server. The default only stores data in memory; to persist to your filesystem, use `@css:config/file.json` |
|
||
| `--rootFilePath, -f` | `./` | Root folder where the server stores data, when using a file-based configuration. |
|
||
| `--sparqlEndpoint, -s` | | URL of the SPARQL endpoint, when using a quadstore-based configuration. |
|
||
| `--showStackTrace, -t` | false | Enables detailed logging on error output. |
|
||
| `--podConfigJson` | `./pod-config.json` | Path to the file that keeps track of dynamic Pod configurations. Only relevant when using `@css:config/dynamic.json`. |
|
||
| `--seededPodConfigJson` | | Path to the file that keeps track of seeded Pod configurations. |
|
||
| `--mainModulePath, -m` | | Path from where Components.js will start its lookup when initializing configurations. |
|
||
|
||
### 🧶 Custom configurations
|
||
More substantial changes to server behavior can be achieved
|
||
by writing new configuration files in JSON-LD.
|
||
The Community Solid Server uses [Components.js](https://componentsjs.readthedocs.io/en/latest/)
|
||
to specify how modules and components need to be wired together at runtime.
|
||
|
||
Examples and guidance on configurations
|
||
are available in the [`config` folder](https://github.com/CommunitySolidServer/CommunitySolidServer/tree/main/config).
|
||
|
||
Recipes for configuring the server can be found at [CommunitySolidServer/recipes](https://github.com/CommunitySolidServer/recipes).
|
||
|
||
|
||
## 👩🏽💻 Developing server code
|
||
The server allows writing and plugging in custom modules
|
||
without altering its base source code.
|
||
|
||
The [📗 API documentation](https://communitysolidserver.github.io/CommunitySolidServer/latest/docs) and
|
||
the [📐 architectural diagram](https://rubenverborgh.github.io/solid-server-architecture/solid-architecture-v1-3-0.pdf)
|
||
can help you find your way.
|
||
|
||
If you want to help out with server development,
|
||
have a look at the [📓 user documentation](https://communitysolidserver.github.io/CommunitySolidServer/) and
|
||
[🛠️ good first issues](https://github.com/CommunitySolidServer/CommunitySolidServer/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
|
||
|
||
|
||
## 📜 License
|
||
The Solid Community Server code
|
||
is copyrighted by [Inrupt Inc.](https://inrupt.com/)
|
||
and [imec](https://www.imec-int.com/)
|
||
and available under the [MIT License](https://github.com/CommunitySolidServer/CommunitySolidServer/blob/main/LICENSE.md).
|
||
|
||
Core contributors are
|
||
[Joachim Van Herwegen](https://github.com/joachimvh),
|
||
[Ruben Verborgh](https://github.com/RubenVerborgh),
|
||
[Ruben Taelman](https://github.com/rubensworks),
|
||
and
|
||
[Matthieu Bosquet](https://github.com/matthieubosquet).
|
||
|
||
|
||
## 🎤 Feedback and questions
|
||
Don't hesitate to [start a discussion](https://github.com/CommunitySolidServer/CommunitySolidServer/discussions)
|
||
or [report a bug](https://github.com/CommunitySolidServer/CommunitySolidServer/issues).
|
||
|
||
Learn more about Solid at [solidproject.org](https://solidproject.org/).
|