A lightweight web application to capture, manage and analyze skills of users and help them improve their capabilities by connecting them with each other and assisting with personalized suggestions for coaches, trainings, projects and many more.
This project is in the incubation stage and is by far NOT ready for production use!
SKOOP Server is a Java web application implementing the backend of the SKOOP ecosystem. This server has no graphical user interface. It exposes a REST API to allow clients (e.g. the SKOOP WebApp) to interact with the various SKOOP functionalities via network. The server takes care of persistently storing the data of the SKOOP domain model in a separate database.
For running the application using the executable JAR file:
-
Java Runtime Environment 11
-
Neo4j Community Edition 3.4.x
For running the application as a Docker container:
-
Docker 18.06 (or higher)
-
Optional: Docker Compose
For development:
-
Java Development Kit 11
-
Neo4j Community Edition 3.4.x
-
Optional: Docker 18.06 (or higher), useful for setting up a Neo4j database
The project uses Maven as the build tool. Run the following command in the project root to build the application:
mvnw package
The final executable JAR file is produced in the target subdirectory.
After completing the Maven build you can run the SKOOP Server like a simple Java application:
java -jar target/skoop-server-0.0.1-SNAPSHOT.jar
Configuration properties to customize the URIs of database and authorization server can be passed as command line arguments:
java -jar target/skoop-server-0.0.1-SNAPSHOT.jar \ --spring.data.neo4j.uri=bolt://192.168.99.100:7687 \ --security.oauth2.resourceserver.jwt.issuer-uri=http://192.168.99.100:9000/auth/realms/SKOOP
At first you must create a network to enable the server app to connect to the database and the SKOOP web app.
docker network create --driver bridge skoop_nw
We provide the public Docker image on Docker Hub.
You can start the container from the public image:
docker run \ --name skoop-server \ --rm \ -p 8080:8080 \ -e SMTP_SERVER_HOST=smtp-server \ -e SMTP_SERVER_PORT=25 \ -e SERVER_NAME=skoop-server \ -e SECURITY_OAUTH2_RESOURCESERVER_JWT_JWKSETURI=http://keycloak:8080/auth/realms/SKOOP/protocol/openid-connect/certs \ -e SPRING_DATA_NEO4J_URI=bolt://neo4j:7687 \ --network=skoop_nw -itd \ tsystemsmms/skoop-server:latest
Alternatively you can still create your own after completing the Maven build. Run the following command in the project root (mind the dot at the end):
docker build \ -t skoop/server:latest \ --build-arg JAR_FILE=target/skoop-server-0.0.1-SNAPSHOT.jar \ .
Then you can start the container as usual:
docker run \ --name skoop-server \ --rm \ -p 8080:8080 \ -e SMTP_SERVER_HOST=localhost \ -e SMTP_SERVER_PORT=25 \ -e SERVER_NAME=skoop-server \ -e SECURITY_OAUTH2_RESOURCESERVER_JWT_JWKSETURI=http://keycloak:8080/auth/realms/SKOOP/protocol/openid-connect/certs \ -e SPRING_DATA_NEO4J_URI=bolt://neo4j:7687 \ --network=skoop_nw -itd \ skoop/server:latest
Both the database and the KeyCloak server are expected to be connected to the skoop_nw network.
Once the application has started the API documentation should be available at http://localhost:8080/swagger-ui.html
Become a contributor to SKOOP by joining our KnowledgeAssets organization! Everyone can help, from UX designer over software developers and testers to documentation writers. Get involved and be part of a great community project!
Interested? Contact georg.wittberger (at) gmail.com
As described in the introduction the SKOOP Server is a pure server application with no graphical user interface. The project makes use of the following noteworthy frameworks:
-
Spring Boot: Provides the basis for the Java web application. Within the application itself it faciliates the configuration of the Spring application context. Furthermore, we use the Spring Boot Maven plugin to build the executable JAR file including an embedded Tomcat server.
-
Spring Web MVC: The REST API provided by the application is implemented using Spring Web MVC controllers. We use that synchronous variant instead of WebFlux at the moment.
-
Spring Security: Provides the authentication and authorization, including method security to implement access control for the REST endpoints.
-
Neo4j: We use this graph database to store the current state of the domain model and to obtain insights in the network of relationships between users, skills and more domain objects. The Neo4j database is typically connected to the application by the Bolt driver which is auto-configured by Spring Boot. For test automation there is also the embedded driver in the project setup.
-
Spring Data Neo4j: The graph database is accessed via Spring Data repositories and Spring Transaction handles the transaction management. Most of this data access layer is also auto-configured by Spring Boot.
-
Springfox: Provides the auto-generated Swagger UI with the REST API documentation.
-
JUnit 5 and Spring Test support are used to implement automated tests for different slices of the application. Neo4j repository tests are supported by an embedded Neo4j database.
SKOOP Server requires a Neo4j database for persistent storage.
Option 1: You can download the database server directly from the website and install it on your system.
Option 2: You can start Neo4j as a Docker container.
-
On Windows:
docker run ^ --name neo4j ^ -d ^ -p 7474:7474 ^ -p 7687:7687 ^ -e NEO4J_AUTH=none ^ --network=skoop_nw -itd ^ neo4j:3.4
-
On Unix/Mac:
docker run \ --name neo4j \ -d \ -p 7474:7474 \ -p 7687:7687 \ -e NEO4J_AUTH=none \ --network=skoop_nw -itd \ neo4j:3.4
This will create a container named neo4j which you start/stop simply like this:
docker start neo4j docker stop neo4j
Visit http://localhost:7474/ to view the Neo4j browser.
Note: The dev profile of the SKOOP Server assumes that the bolt endpoint of Neo4j is available at localhost:7687. The database server must be accessible when starting the SKOOP Server.
The source code makes use of Lombok annotations to generate getters, setters, etc. in POJO classes. The build process takes care of processing these annotations at compile time but any IDE may require further configuration to make internal builds work.
For IntelliJ IDEA:
-
Install the Lombok Plugin
-
Open the project settings, navigate to
Build, Execution, Deployment > Compiler > Annotation Processorsand activate the checkboxEnable annotation processing.
For Visual Studio Code:
Install the Lombok Annotations Support before opening the project workspace.
You can run the application by using the Java class SkoopServerApplication as main class in a usual Java launch configuration.
For IntelliJ IDEA right-click on this class and select Run 'SkoopServer….main()' from the context menu.
For Visual Studio Code a launch configuration is already included in the repository.
Note: You should enable the Spring profile dev to activate some configuration properties suitable for a development environment. A general way to do this is to add the command line argument --spring.profiles.active=dev to the launch configuration.
SKOOP Server requires an external OpenID Connect provider to generate ID token which can be used to authorize API requests.
During development a local KeyCloak server is recommended to manage test users and create access token.
Option 1: You can download KeyCloak directly from the website and install it on your system.
Option 2: You can start KeyCloak as a Docker container.
-
On Windows:
docker run ^ --name keycloak ^ -d ^ -p 9000:8080 ^ -e KEYCLOAK_USER=admin ^ -e KEYCLOAK_PASSWORD=admin ^ --network=skoop_nw -itd ^ jboss/keycloak:4.5.0.Final
-
On Unix/Mac:
docker run \ --name keycloak \ -d \ -p 9000:8080 \ -e KEYCLOAK_USER=admin \ -e KEYCLOAK_PASSWORD=admin \ --network=skoop_nw -itd \ jboss/keycloak:4.5.0.Final
This will create a container named keycloak which you start/stop simply like this:
docker start keycloak docker stop keycloak
Visit http://localhost:9000/auth/ to configure the KeyCloak server.
There is an export of a suitable test realm in tools/keycloak/skoop-realm.json which can be imported into the KeyCloak server. Simply log in to the administration console, select "Add realm" and upload the JSON file.
The test realm comes with a preconfigured client for SKOOP but contains no test users. You have to create users manually within the SKOOP realm.
Note: The dev profile of the SKOOP Server assumes that the KeyCloak server is available at localhost:9000 and contains a realm named SKOOP. The KeyCloak server must be accessible when starting the SKOOP Server.
In order to execute the automated tests run the following command in the project root:
mvnw test
Project test coverage is reported by JaCoCo Maven plugin.
To generate JaCoCo test coverage report it is necessary to run prepare-package maven build phase.
mvnw prepare-package
After the phase has been completed JaCoCo test coverage report can be found in target/site/jacoco/index.html.
Travis CI uploads JaCoCo test coverage reports to codecov.io. Uploaded reports can be found here.
Open the Swagger UI of the running application: http://localhost:8080/swagger-ui.html
Fundamentally, the SKOOP Server is based on the conventions of the Spring Boot framework. If you are familiar with that framework you should have an easy start with the project.
The base package com.tsmms.skoop contains several sub-packages with focus on specific parts of the domain model. For example, com.tsmms.skoop.skill contains everything related to skills as a domain object, including entity classes, data repositories, service implementations and controllers for the corresponding REST API.
A basic design principle of SKOOP Server is the application of the CQRS pattern (Command Query Responsibility Segregation).
In short words, all read access to the domain model is strictly separated from the write access. This segregation is made explicit by the separate command and query packages inside each domain package. For example:
-
com.tsmms.skoop.skill.command: Contains all the code dedicated to modifications of skills-
Service implementation with methods representing the commands which alter the state of the domain model
-
Controller implementation which provides POST, PUT and DELETE operations to modify the domain model
-
-
com.tsmms.skoop.skill.query: Contains all the code dedicated to reading skills-
Service implementation with methods to lookup domain objects and compile different views on the domain model
-
Controller implementation which provides GET operations to request views on the domain model
-
Important rule: Code from the command package may use code from the query package, e.g. to perform validation. But under no circumstances is the code in the query package allowed to use code from the command package!
The Spring Security framework is used to implement user authentication and access control for the provided API resources.
The application is implemented as a stateless OAuth2 resource server. Each API request must be authorized by including an Authorization header with a valid ID token:
Authorization: Bearer <ID token>
The signature of the ID token is validated using the public key of the authorization server (offline validation). By default, this public key is automatically loaded on startup from the JWK set URI of the authorization server.