A single page application providing a responsive web user interface for the SKOOP server application.
This project is in the incubation stage and is by far NOT ready for production use!
SKOOP WebApp is a single page application which provides a responsive web user interface for the SKOOP Server. It makes use of the REST API provided by the server to interact with the various SKOOP functionalities like relating users to skills, viewing statistics and many more.
For hosting the pre-built distribution:
-
Web server of your choice (e.g. Nginx, Apache HTTP Server)
For running the application as a Docker container:
-
Docker 18.06 (or higher)
-
Optional: Docker Compose
For development:
-
Node.js 10.5.x (or higher)
-
NPM 6.2.x (or higher)
The project uses NPM in conjunction with Angular CLI to build the final static assets of the application. Run the following commands in the project root to build the application:
npm install npm run build
This installs the dependencies and then compiles the final static assets in the dist/skoop-webapp directory. These files can be served by an arbitrary web server.
The static assets of the application (HTML, CSS, JavaScript) can be hosted by any web server.
Important configurations:
The web server must provide the index.html file for every route of the application. For example, if a user requests the deeplink /skills/123/users the main page must be served for this request as well. The Angular router will show the appropriate component once the application has been initialized.
See the following documentation for example configurations: https://angular.io/guide/deployment#server-configuration
Additionally, the web server must forward every request starting with /api/ to the SKOOP Server application. For example, the SKOOP WebApp will request the user identity by calling /api/my-identity. The web server receiving this request must strip off the leading /api and forward the request for /my-identity to the SKOOP Server.
At first you must create an Apache HTTP Server configuration file to set up forwarding of API requests to the SKOOP Server application. You only need to declare the ProxyPass directives for the backend:
ProxyPass "/api/" "http://skoop-server:8080/" ProxyPassReverse "/api/" "http://skoop-server:8080/"
You should store this configuration file with the extension .conf in a separate directory, e.g. skoop-config.
Then you must create a network to enable the web app to connect to the KeyCloak and the SKOOP server.
docker network create --driver bridge skoop_nw
We provide the public Docker image on Docker Hub.
You can start the container and mount the configuration directory as a volume:
docker run \ --name skoop-webapp \ -d \ -p 4200:80 \ -e SERVER_NAME=localhost:4200 \ -e [email protected] \ -e SKOOP_WEBAPP_AUTHENTICATION_ISSUER=http://localhost:9000/auth/realms/SKOOP \ -e SKOOP_WEBAPP_AUTHENTICATION_INSECURE=true \ -v ./skoop-config:/usr/local/apache2/conf/skoop \ --network=skoop_nw -itd \ tsystemsmms/skoop-webapp:latest
Alternatively you still can create your own image after building the application from source.
After completing the NPM build run the following command in the project root (mind the dot at the end):
docker build \ -t skoop/webapp:latest \ .
Finally, you can start the container and mount the configuration directory as a volume:
docker run \ --name skoop-webapp \ -d \ -p 4200:80 \ -e SERVER_NAME=localhost:4200 \ -e [email protected] \ -e SKOOP_WEBAPP_AUTHENTICATION_ISSUER=http://localhost:9000/auth/realms/SKOOP \ -e SKOOP_WEBAPP_AUTHENTICATION_INSECURE=true \ -v ./skoop-config:/usr/local/apache2/conf/skoop \ --network=skoop_nw -itd \ skoop/webapp:latest
Now the SKOOP WebApp is accessible at http://localhost:4200/
|
Note
|
This example assumes that the configuration file is located in the subdirectory skoop-config, that you have created a Docker service for the SKOOP Server named skoop-server and that a KeyCloak server with a SKOOP realm is running on localhost:9000. Both SKOOP server and the KeyCloak server are expected to be connected to the skoop_nw network.
|
|
Caution
|
Do not use SKOOP_WEBAPP_AUTHENTICATION_INSECURE=true on a production environment!
|
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 WebApp is a browser-based single page application which provides a web user interface to interact with the SKOOP Server. Therefore, it focuses on the presentation of the data retrieved from the REST API endpoints of the server. The project makes use of the following noteworthy frameworks:
-
Angular: The popular JavaScript framework is the basis of the application. We use the Angular routing for navigation to different views.
-
Angular CLI: Makes development and the build process of the application much easier. It encapsulates the Webpack build configuration and provides some reasonable conventions to follow instead. The CLI also provides some convenient commands to generate new components, services, etc.
-
Angular Material: Provides components to build an application with Google’s Material design. We use it as a basis for our graphical layout.
-
Angular Flex-Layout: Provides directives to create responsive layouts with Angular based on Flexbox CSS. We use it to make the application look great on handsets and desktops.
-
Angular OAuth2 OIDC: Enables support for user authentication via OpenID Connect using an external authorization server.
-
SASS: Stylesheet pre-processor used for component style definitions.
-
RxJS: When it comes to asynchronous operations the reactive extensions with their well-known
Observablescome into play. We use them primarily when requesting the API of the SKOOP Server. -
Karma and Jasmine: The standard tools for test automation in Angular projects.
Before starting with development you have to download the project dependencies using NPM. Run the following command in the project root:
npm install
The installation takes some time… be patient 😴
Once the dependencies have been installed you can launch the Webpack development server by running this command:
npm start
As soon as the server is running open this URL in your browser: http://localhost:4200/
Webpack automatically reloads modules when you change the source code. There is no need to restart the server after each modification.
The server proxies all requests starting with the path /api/ to http://localhost:8080/ (stripping that prefix). For example, a request to /api/skills will be forwarded to http://localhost:8080/skills. This allows the development server to collaborate with the real SKOOP Server application.
In order to set up the OpenID Connect login you need to install a local KeyCloak server and configure an appropriate realm.
In the development configuration the SKOOP WebApp assumes that the KeyCloak server is available at localhost:9000. Currently, there is no option for external configuration. If you have to use a different host or port please temporarily adjust the configuration in src/environments/environment.ts.
There must be a realm called SKOOP which allows the client skoop to perform the OpenID Connect implicit flow.
Please see the SKOOP Server for more hints and a preconfigured KeyCloak test realm.
The automated tests can be executed by running the following command in the project root:
npm test
Note: The Karma configuration relies on Chrome as the browser to run the tests.
Travis CI uploads test coverage reports to codecov.io. Uploaded reports can be found here.
Fundamentally, the SKOOP WebApp project follows the principles of Angular projects. The directory structure and naming follows the conventions given by the Angular CLI tool and the Angular style guide.
In the application source directory src/app there are various subdirectories focusing on specific parts of the domain model. For example, the directory src/app/skoop contains everything related to the presentation of the user’s personal skill profile page (components, services, tests). The src/app/shared directory contains cross-cutting sources which are used all across the application.
The routing to different views is accomplished by the Angular router. The configuration is encapsulated in its own module src/app/app-routing.module.ts.
The import of all Angular Material components is also centralized in the module src/app/app-material.module.ts. This module can also be imported in test specs to have the Material components ready to go.
The application makes use of the Angular OAuth2 OIDC module to authenticates users against an external OpenID Connect provider (e.g. KeyCloak) using the implicit flow. The obtained ID tokens are automatically added to any API requests sent to the SKOOP Server using an auto-configured HttpInterceptor.
The directory src/styles is configured as a Sass include path. All files from this directory can be imported directly without traversal. For example, the variables module src/styles/_variables.scss can be imported in any other Sass source file using @import 'variables';.
Environment-specific configuration is located in the module src/environments/environment.ts (Angular CLI convention). This module contains the development configuration. During the production build this module is replaced by the production version environment.prod.ts. The main HTML page src/index.html is handled in a similar way. During the production build it is replaced by src/index.prod.html.
The concept for external environment configuration assumes that environment-specific settings are given as meta elements in the main HTML page. Therefore, the production environment module looks for external configuration in such specific meta elements in the document.
The main HTML page for production contains the supported meta elements with server-side-include tags inside their content attributes. This allows the Apache HTTP Server hosting the SKOOP WebApp to resolve these placeholders to configuration values given as external environment variables.
There are some general design principles to follow in the project.
Components should never make use of the HttpClient directly. Calling the API of the SKOOP Server is the responsibility of services. These services should return the Observable of the HTTP response directly to their calling code without subscribing on their own (except there is some reason to do so).
Reusable styles should be written as Sass mixins in the file src/styles/_mixins.scss. Common values for sizes and colors should be written as variables in the file src/styles/_variables.scss and then the variable should be used for the specific style property.