This repository contains the implementation
of an Open Circularity Platform as part of the Onto-DESIDE Horizon Europe project.
We demonstrate the Open Circularity Platform through some example use cases:
The setup of the Open Circularity Platform is made reproducible by relying on Docker containers and Docker Compose for setting up the network locally that represents the Solid-based decentralized data sharing platform.
Within the network, we have set up:
- multiple data providers each publishing their data behind a secure access layer using Solid pods,
- a (technical) webclient providing a Web UI to execute queries on these Solid pods, and
- a (more user friendly) data viewer providing an easier to use Web UI to execute queries on these Solid pods.
During the setup-flow, Solid pods are created and prefilled with example WebIDs and other Resource Description Framework (RDF) formatted data.
During the usage-flow, an end user navigates either to the rather technical Comunica Webclient which provides a set of predefined queries the user can execute over the Solid pods or to the generic data viewer, a more user-friendly web application that works with the same underlying predefined queries.
A public deployment is available. To use it as is, no further setup is needed, so continue reading at Usage and choose Selected setup = Public deployment.
- a bash shell
- Node >= 18 with npm
- Docker Engine and Docker Compose
- Depending on your platform, different installation guides are available from the above links.
- OpenSSL
- Installation depends on your platform. On Linux (especially on Ubuntu 20.04 LTS), if it is not yet installed, execute
sudo apt install openssl.
- Installation depends on your platform. On Linux (especially on Ubuntu 20.04 LTS), if it is not yet installed, execute
- yarn classic
Unless specified otherwise below, execute commands from a bash shell in the repository root.
# Install dependencies
yarn installThe files in this repository were prepared to generate output for three different selected setups. The selection of a selected setup is done by means of environment variables. These environment variables are assigned in environment variables files.
An overview:
| Selected setup | Details | Environment variables file | Docker based |
|---|---|---|---|
| Development and stand-alone demo | URLS https://..., same as in envvars2, but nothing publicly accessible (use included webapps via included browser) |
envvars | yes |
| Public deployment | URLS https://..., publicly accessible pods and included webapps, open for external webapps |
envvars2 | yes |
| Local development | URLs http://localhost:..., pods running on the local host, webapps not included, open for local webapps |
envvars3 | no |
In any new bash shell, before executing any of the commands in this Setup section and in the other sections, first assign the environment variables using the appropriate environment variables file:
# example for file 'envvars2'
source envvars2For a closer look at the different selected setups, see here.
This repository contains template files *.template.
When following the instructions below, from every template file x.template a file x will be derived with contents
depending on the environment variables file sourced above. The files x themselves are git-ignored.
The list of actions to be executed here is managed in a script. The script takes into account the sourced environment variables file. Execute:
./scripts/setup/finalize-setup.shThis section applies to Docker based setups only.
Execute...
# if you are on a server where previous versions still are running:
docker compose --profile backend --profile frontend --profile extra-pod down -t 0
# and then:
docker compose --profile backend --profile frontend --profile extra-pod up --waitThe command above starts all services in a Docker environment and and waits until they are all ready (listening). This takes some time to complete.
Optional: if you're interested in what's happening while the previous command executes, you may open a new terminal window and in it, execute:
docker compose --profile backend --profile frontend --profile extra-pod logs -fExplore the section Usage.
To stop and remove the containers, execute:
docker compose --profile backend --profile frontend --profile extra-pod down -t 0This section applies to the local development setup only.
Execute...
./scripts/local-run/start-csss.shThe command above starts the pods in the background and waits until they are all ready (listening). This takes some time to complete.
The pods log files can be consulted at ./local-run/*.log.
The pods data can be viewed at ./local-run/data/css*/.
Explore the section Usage.
Execute:
./scripts/local-run/stop-csss.shIn case of environment variables file envvars, you need to let the Firefox browser trust our self-made Certificate Authority. Follow the instructions in the Setup section of FIREFOX_CONTAINER.md.
Some queries may require you to login as one of the actors, described in the use cases.
That is because read permissions to resources may be restricted to specific actors, as can be seen in the overview of permissions.
Find actors' email addresses and passwords in the overview of actors' WebIDs, emails and passwords.
The queries acting on the resources described as "Textile use case 2" in the overview of permissions give results only if these resources are added to the involved pod(s) after the pods are running. If not done before, you may add them now by executing:
./scripts/stuff-pods/stuff-pods.shSkip this section in favor of higher level querying using the included data viewer, unless if you really need to see low level details.
To query the Solid pods, navigate to the URL configured for the webclient:
| Selected setup | Included technical Comunica webclient URL | Browse via |
|---|---|---|
| Development and stand-alone demo | https://webclient.onto-deside.ilabt.imec.be/ | Included Firefox container at http://localhost:5800 |
| Public deployment | https://webclient.onto-deside.ilabt.imec.be/ | Your local browser |
| Local development | Not available; do it yourself if needed (1) | Your local browser |
(1) The queries as used in other setups are prepared for you in ./scripts/comunica/outputs/queries/.
This Comunica webclient allows you to query both public and private (if authenticated) data stored within the Solid pods of the Solid network.
This screenshot demonstrates querying Lindner Group's products. The result shown was obtained when logged in to identity provider https://css1.onto-deside.ilabt.imec.be as info@lindner-group.com.
All queries are configured to work on a predefined list of datasources (Solid pods in our case). Selecting a query preloads the Choose datasources: dialogue.
In the public deployment setup case, it is possible to add your own Solid pod to the list. See also Public deployment with additional external Solid pods.
If you don't have a pod yet:
- you can obtain one following the Solid project instructions
- or try out Solid pods with the SolidLab Pod Playground (be warned for this one: "The pods and data on the instance is removed daily and there are no guarantees regarding uptime.").
To add an external Solid pod to the list of datasources in the Comunica webclient, place the cursor in the field 'Choose datasources'.
Next type the baseURL of an additional Solid pod and confirm with the <Return> key.
The additional datasource will be taken into account when the query is executed, and the datasource will be available as a preset datasource from here on.
To use this data viewer, navigate to the URL configured for the data viewer:
| Selected setup | Included data viewer URL | Browse via |
|---|---|---|
| Development and stand-alone demo | https://viewer.onto-deside.ilabt.imec.be/ | Included Firefox container at http://localhost:5800 |
| Public deployment | https://viewer.onto-deside.ilabt.imec.be/ (2) | Your local browser |
| Local development | http://localhost:port-nr (1)(2) | Your local browser |
(1) Go to ../applied-in-architecture-generic-data-viewer-react-admin, spin up the viewer with npm run dev and browse the localhost at the port reported by this command.
(2) More about how to use ../applied-in-architecture-generic-data-viewer-react-admin for local query development: see The modified data viewer in the developer documentation.
This screenshot shows the result of a query about Texon's components and materials.
The result shown was obtained when logged in to identity provider https://css5.onto-deside.ilabt.imec.be as info@texon.com.
