EVOKS repository

EVOKS (Editor for Vocabularies to Know Semantics) is a software for creating and publishing SKOS vocabularies and thesauri. It allows you to:

• create a SKOS vocabulary from scratch
• import SKOS vocabularies in RDF/XML or Turtle format
• edit SKOS vocabularies without using its textual representation
• work collaborativley
• publish the vocabulary with a single click in the vocabulary browser SKOSMOS

Note

Caution This software is only for internal vocabulary development purposes. It is not ready for production and shall not be available for public access when installed.

Installation

The main way to install EVOKS and its depending services is to build and run the docker images locally using docker compose.

Prerequisites

• Unix-based system (e.g. Linux, MacOS, Windows using WSL (untested))
• Installation of
  • git
  • Docker

Installation procedure:

1. Clone this repository:

   user@localhost:/home/user/$ git clone https://github.com/kit-data-manager/EVOKS.git
   Clone to 'EVOKS'
   [...]
   user@localhost:/home/user/$ cd EVOKS
   user@localhost:/home/user/EVOKS$
   

2. (until further notice) checkout development branch

   git checkout development
   

3. Copy .example.env and rename to .env

4. Open .env and change the variables if desired, see Overview of variables.

   Caution Change of Fuseki and Postgres credentials is strongly recommended, especially if not installed and used only on a local computer without access from other people

5. Run docker compose build

6. Run docker compose up

7. Open the file within the repo: evoks/evoks/settings.py and update the SKOSMOS URIs:

   SKOSMOS_DEV_URI = "http://<yourserverURL>:<chosen_port_in_evn_file>/"
   SKOSMOS_LIVE_URI = "http://<yourserverURL>:<chosen_port_in_evn_file>/"
   

   e.g.

   SKOSMOS_DEV_URI = "http://evoks.mydomain.edu:8001/"
   SKOSMOS_LIVE_URI = "http://evoks.mydomain.edu:8002/"
   

   or

   SKOSMOS_DEV_URI = "localhost:8001/"
   SKOSMOS_LIVE_URI = "localhost:8002/"
   

8. within settings.py adjust the allowed hosts to your needs (usually it should match the serverURL), e.g.

   ALLOWED_HOSTS: list[str] = ['.mydomain.edu','localhost']
   

9. Open <yourserverURL>:${EVOKS_PORT} which was set in .env file (default: 8000), e.g. localhost:8000 in your browser

10. Very likely, a bug will occur since there are problems with fuseki folder access rights (creating vocabs will fail). Run sudo chmod 777 -R fuseki-dev/ fuseki-live/ then (see issue #)

11. To stop the services, run docker compose down and to restart docker compose up

Variables

VAR NAME	Default value	Description	Change mandatory
INSTANCE_NAME	defaultinstance	Prefix of docker container names	no
EVOKS_PORT	8000	Port of EVOKS	no
SKOSMOS_DEV_PORT	8001	Port of Skosmos for vocabulary development	no
SKOSMOS_LIVE_PORT	8002	Port of Skosmos for published vocabularies	no
EVOKS_MAIL	[email protected]	Mailaddress for automatically sending notifications to the instance admin (typically the person who installed the service)	no
FUSEKI_USER	admin	Default fuseki username, change especially if not used locally	yes
FUSEKI_PASSWORD	fuseki_password	Default fuseki password, change especially if not used locally	yes
POSTGRES_USER	postgres	Default postgres username, change especially if not used locally	yes
POSTGRES_PASSWORD	changeme	Default postgres password, change especially if not used locally	yes
POSTGRES_PORT	8005	Port of Postgres DB, only needed for code developers	no
FUSEKI_DEV_PORT	8003	Port of Fuseki Triple Store, only needed for code developers	no
FUSEKI_LIVE_PORT	8004	Port of Fuseki Triple Store (of published vocabularies), only needed for code developers	no

Create an administrator

You need to create an administrator account for EVOKS by performing the following steps:

1. Run docker ps, look for <container_prefix>_web (or ...web_1) container
2. Run docker exec -it <container_prefix>_web bash (or ...web1 accordingly)
3. Now you are within the container. Run: python evoks/manage.py createsuperuser
4. Follow instructions to create a superuser. You can choose whatever username, password and (arbitary) mailaddress you like
5. Log into EVOKS using the email as username and the chosen password

Further settings (not needed for initial setup)

Configure Mail Server

1. Edit .env file
2. Fill out

   EMAIL_HOST_USER=your-email
   EMAIL_HOST_PASSWORD=your-password
   

   in this file. Caution: Be aware that the password is stored as plain text!
3. Open evoks/evoks/settings.py and configure the SMTP server. E.g. for gmail

   EMAIL_HOST = 'smtp.gmail.com'
   EMAIL_PORT = 587
   EMAIL_USE_TLS = TRUE
   

Most of the email providers (e.g. Gmail) do not accept Less Secure Apps by default, so you have to accept Less Secure Apps in the settings of the email you are using.

HTTPs + Domains

1. Stop containers
2. See Caddy.md for Caddy setup
3. Run containers again

For Developers

Execution of Tests (only for developers needed)

Run the unittests:

1. docker ps, look for <container_prefix>_web_1 container
2. docker exec -it <container_prefix>_web_1 bash
3. Within the container: cd evoks
4. run coverage run --source='.' --omit='*/migrations/*.py','guardian/*','theme/*','evoks/__init__.py','evoks/asgi.py','evoks/wsgi.py','manage.py','tests/*' manage.py test tests/model/ tests/migration/ tests/skosmos/ tests/fuseki/ tests/views/ tests/evoks && coverage html aus.
5. Open index.html from folder htmlcov with a browser.

License

EVOKS is licensed under the Apache License, Version 2.0. License owner: Karlsruhe Institute of Technology (KIT)

Acknowledgement Development of this software product was funded by the German Research Foundation (DFG)—CRC 980 Episteme in Motion, Project-ID 191249397, and by the research program “Engineering Digital Futures” of the Helmholtz Association of German Research Centers.