The Staff User Interface (staff-ui) is an administrative user interface component of Consent2Share (C2S) used to create and manage user accounts. Administrative staff can use this to log in, visit their home page, create user accounts, and manage user information.
- Oracle Java JDK 8 with Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy
- Docker Engine (for building a Docker image from the project)
- Node.js (Optional, see Structure for details)
- Angular CLI (Optional, see Structure for details)
- MD2 (Optional, see Structure for details)
There are two main modules in this project:
client: This folder contains all frontend user interface code, which is written using Angular v4.0.server: This folder contains a Spring Boot project, which is primarily responsible for packaging and serving the static resources that are built from theclientmodule. This is also an Apache Maven project which utilizes Frontend Maven Plugin to:- locally install Node.js and the
clientmodule Node.js dependencies; - Build the
clientmodule using Node Package Manager NPM Node.js package. Finally, it uses Apache Maven Resources Plugin to copy the resources that are built from theclientmodule into theservermodule that will be eventually packaged as a build artifact injarformat. Therefore, there is no need to install Node.js globally ifservermodule is built with Maven.
- locally install Node.js and the
- Angular CLI and MD2 are required only during development. It is not required to install them if you're only running the application out of the box.
This Maven project requires Apache Maven 3.3.3 or greater to build it. It is recommended to use the Maven Wrapper scripts provided with this project. Maven Wrapper requires an internet connection to download Maven and project dependencies for the very first build.
To build the project, navigate to the folder that contains pom.xml file using the terminal/command line.
- To build a JAR:
- For Windows, run
mvnw.cmd clean install - For *nix systems, run
mvnw clean install
- For Windows, run
- To build a Docker Image (this will create an image with
bhitsdev/staff-ui:latesttag):- For Windows, run
mvnw.cmd clean package docker:build - For *nix systems, run
mvnw clean package docker:build
- For Windows, run
Note: Frontend developers can build client and server modules separately and save build time by using Angular CLI. This option requires Angular CLI to be installed globally.
- Build the
clientmodule: runnpm run prodin the client folder - Manually repackage the
jarfile from theservermodule
This is a Spring Boot project and serves the project via an embedded Tomcat instance. Therefore there is no need for a separate application server to run it.
- Run as a JAR file:
java -jar staff-ui-x.x.x-SNAPSHOT.jar <additional program arguments> - Run as a Docker Container:
docker run -d bhitsdev/staff-ui:latest <additional program arguments>
NOTE: In order for this project to fully function as a microservice in the Consent2Share application, it is required to setup the dependency microservices and the support level infrastructure. Please refer to the Consent2Share Deployment Guide in the corresponding Consent2Share release (see Consent2Share Releases Page) for instructions to setup the Consent2Share infrastructure.
During build, Angular-Cli uses Webpack to create bundles (Javascript files) which will be referenced in the browser. Run the application and use browser development tools to set breakpoints in related Javascript files to start debugging.
The server module runs with some default configuration that is primarily targeted for development environment. It utilizes Configuration Server which is based on Spring Cloud Config to manage externalized configuration, which is stored in a Configuration Data Git Repository. We provide a Default Configuration Data Git Repository.
This API can run with the default configuration, which is targeted for a local development environment. Default configuration data is from three places: bootstrap.yml, application.yml, and the data which Configuration Server reads from Configuration Data Git Repository. Both bootstrap.yml and application.yml files are located in the resources folder of this source code.
We recommend overriding the configuration as needed in the Configuration Data Git Repository, which is used by the Configuration Server.
Also, please refer to Spring Cloud Config Documentation to see how the config server works, Spring Boot Externalized Configuration documentation to see how Spring Boot applies the order to load the properties, and Spring Boot Common Properties documentation to see the common properties used by Spring Boot.
java -jar staff-ui-x.x.x-SNAPSHOT.jar --c2s.staff-ui.oauth2.client.secret=strongpassword
NOTE: The oauth2.client.client-id and oauth2.client.secret value are used for User Account and Authentication (UAA) Password Grant type. The configuration uses the format client_id:client_secret to be Base 64 encoded. The client_id refers to the OAuth2 Client ID assigned to the Consent2Share UI by UAA. C2S uses staff-ui as the default client_id for this application.
-
docker run -d bhitsdev/staff-ui:latest --c2s.staff-ui.oauth2.client.secret=strongpassword -
In a
docker-compose.yml, this can be provided as:
version: '2'
services:
...
staff-ui.c2s.com:
image: "bhitsdev/staff-ui:latest"
command: ["--c2s.staff-ui.oauth2.client.secret=strongpassword"]
...For simplicity in development and testing environments, SSL is NOT enabled by default configuration. SSL can easily be enabled following the examples below:
java -jar staff-ui-x.x.x-SNAPSHOT.jar --spring.profiles.active=ssl --server.ssl.key-store=/path/to/ssl_keystore.keystore --server.ssl.key-store-password=strongkeystorepassword
docker run -d -v "/path/on/dockerhost/ssl_keystore.keystore:/path/to/ssl_keystore.keystore" bhitsdev/staff-ui:latest --spring.profiles.active=ssl --server.ssl.key-store=/path/to/ssl_keystore.keystore --server.ssl.key-store-password=strongkeystorepassword- In the
docker-compose.yml, this can be provided as:
...
staff-ui.c2s.com:
image: "bhitsdev/staff-ui:latest"
command: ["--spring.profiles.active=ssl","--server.ssl.key-store=/path/to/ssl_keystore.keystore", "--server.ssl.key-store-password=strongkeystorepassword"]
volumes:
- /path/on/dockerhost/ssl_keystore.keystore:/path/to/ssl_keystore.keystore
...NOTE: As seen in the examples above, /path/to/ssl_keystore.keystore is made available to the container via a volume mounted from the Docker host running this container.
Java has a default CA Certificates Store that allows it to trust well-known certificate authorities. For development and testing purposes, one might want to trust additional self-signed certificates. In order to override the default Java CA Certificates Store in Docker container, one can mount a custom cacerts file over the default one in the Docker image as follows: docker run -d -v "/path/on/dockerhost/to/custom/cacerts:/etc/ssl/certs/java/cacerts" bhitsdev/staff-ui:latest
NOTE: The cacerts references given regarding volume mapping above are files, not directories.
For demo purpose, the system has a default staff admin user configured in User Account and Authentication (UAA) uaa.yml file. The default account can be modified or/and create more users.
...
scim:
users:
# Configure additional c2s staff admin(users) as:
# - EmailId | password | EmailId | FirstName | LastName | <Comma saperated list of permissions>
# For example:
- c2s-admin@mailinator.com|AAA#aaa1|c2s-admin@mailinator.com|admin|consent2share|staffUi.access,staffUiApi.read,staffUiApi.write
...If you have any questions, comments, or concerns please see Consent2Share project site.
Please use GitHub Issues page to report issues.