Welcome to the CaPe Suite Installation Manual!

This section provides the description of the installation and administration functionalities. An administrator should be able to install, deploy, perform the sanity checks on the environment.

Get the source code from repository

Open a command prompt and execute the following command to clone the source code from the CaPe GitHub repository (Git must be installed):

git clone https://github.com/OPSILab/Cape.git
cd Cape

Install CaPe components

CaPe installation will involve the deployment of different architectural components, each of which can deployed either in a "on premise", "as a service" or mixed approach:

installation-overview


Libraries

CaPe Suite uses following libraries and frameworks (already included):

Name Version License
Spring Boot 2.4.5 Apache License 2.0
Springdoc Openapi 1.5.8 Apache License 2.0
Spring Data 2.4.5 Apache License 2.0
Nimbus Jose JWT 8.5 Apache License 2.0
Bouncy Castle 1.64 MIT
Lombok 1.18.12 MIT
Apache Commong Lang 3 3.11 Apache License 2.0
JSONSchema2Pojo 1.01 Apache License 2.0
Angular 11.2.12 MIT
Nebular 7.0.0 MIT
Json-Editor 2.3.0 MIT
Bootstrap 4.6.0 MIT
Ngx-configure 9.0.0 ISC License
Ng2-smart-table 1.7.2 MIT
Rxjs 6.6.7 Apache License 2.0
Ngx-translate 13.0.0 MIT
TypeScript 4.1.5 Apache License 2.0
jQuery 3.5.1 MIT
D3 6.2.0 BSD
Material-design-icons 3.0.1 Apache License 2.0
Fontawesome-free 5.15.3 CC-BY-4.0
Fontawesome-svg-core 1.2.35 MIT

Identity and Access Manager

CaPe must interact with any Identity Manager that supports OpenId Connect authorization framework.

Note. It is recommended to use Keycloak Identity and Access Management, which will be used as reference for the configuration sections of this installation guide.

Cape Dashboards will use the Open Id Connect protocol upon the OAuth2 Authentication workflow (Authorization Code grant), in order to perform User authentication and obtain an Access Token (JWT), which will be used to grant access to Cape APIs. This Access Token will be used by User and Data Controller Dashboards to call the Cape APIs exposed respectively by Cape Server and Cape SDK Client components.

In the same way, an external client application/service that wants to interact with Cape by using the Cape SDK APIs, must perform one of the available OAuth2 flows (Authorization Code, Client Credentials and Password grants) against the Cape Idm (e.g. Keycloak), in order to get an Access Token and then use it in the API requests.

Keycloak Identity Manager installation

In order to get Keycloak ready to be used by Cape, following steps must be performed:

  • Install Keycloak, create a Cape realm and at least one user (see here).
  • Register two client applications with cape-server and cape-service-sdk and clientId (see here). Be sure to select public in the Access Type field.
  • Create DATA_SUBJECT role in the cape-server client and DATA_CONTROLLER in the cape-service-sdk client. (see here).
  • Assign DATA_SUBJECT as default role for cape-server client and DATA_CONTROLLER as default for cape-service-sdk. (see here) and the image below.

cape-server-roles

  • Create for both clients a Mapper of type User Client Role and set roles as Token Claim Name, in order to map client roles to the roles field of the generated Access Token. (see the image below).

cape-server-roles-mapping


Any feedback on this documentation is highly welcome, including bug reports and suggestions. Please send the feedback through GitHub. Thanks!