Overview:

• Style Guide
• How to Run
  • Configuration
    • Java Version
    • Environment Variables
    • Properties
  • Local Testing
  • Production Deployment
• How to Use
  • User Login
  • User Registration
• Application Overview
  • Project Structure
  • Vaadin Framework
    • Additional Information
• License

Style Guide

Please find the styleguide in its own repository.

How to Run

This application is based on maven and can be run after setting the required configurations, by typing mvnw (Windows), or ./mvnw (Mac & Linux) in the command line and opening http://localhost:8080 in your browser.

You can also import the project to your IDE of choice as you would with any Maven project. Read more on how to import Vaadin projects to different IDEs (Eclipse, IntelliJ IDEA, NetBeans, and VS Code).

Deploying to Production

To create a production build, call mvnw clean package -Pproduction (Windows), or ./mvnw clean package -Pproduction (Mac & Linux). This will build a JAR file with all the dependencies and front-end resources, ready to be deployed. The file can be found in the target folder after the build completes.

Once the JAR file is built, you can run it using java -jar target/datamanager-1.0-SNAPSHOT.jar

Configuration

Java Version

This application requires Java 17 to be build and run

Environment Variables

The env variables contain information about the salt and the secret. Both of them are used to encrypt and decrypt user information.

The application properties file could look like the following:

spring.datasource.url=${USER_DB_URL:localhost}
spring.datasource.username=${USER_DB_USER_NAME:myusername}
spring.datasource.password=${USER_DB_USER_PW:astrongpassphrase!}

To change the port or the driver those can be added as environmental variables as well. Both are preset with default values and are therefore not mandatory to set

server.port=${DM_PORT:8080}
spring.datasource.driver-class-name=${USER_DB_DRIVER:com.mysql.cj.jdbc.Driver}

As the application needs to send emails, you have to configure an smtp server as well.

spring.mail.username=${MAIL_USERNAME}
spring.mail.password=${MAIL_PASSWORD}
spring.mail.host=${MAIL_HOST:smtp.gmail.com}
spring.mail.port=${MAIL_PORT:587}

For user email confirmation a specific endpoint and context-path (for example if the app runs in a different context than the root path) is addressed. This endpoint can be configured using the following properties:

Generated email confirmation links will look like localhost:8080/login?confirm-email=<token> with the default configuration.

# global service route configuration for mail interaction requests
service.host.name=${DM_SERVICE_HOST:localhost}
service.host.protocol=${DM_HOST_PROTOCOL:https}
service.host.port=${DM_SERVICE_PORT:-1}
# Set the context path, for example if your app runs behind a proxy
server.servlet.context-path=${DM_SERVICE_CONTEXT_PATH:}
# route for mail confirmation consumption
email-confirmation-endpoint=${EMAIL_CONFIRMATION_ENDPOINT:login}
email-confirmation-parameter=${EMAIL_CONFIRMATION_PARAMETER:confirm-email}
# route for password reset
password-reset-endpoint=${PASSWORD_RESET_ENDPOINT:new-password}
password-reset-parameter=${PASSWORD_RESET_PARAMETER:user-id}

Since the application will retrieve experimental design values from a list of defined vocabularies a connection to the datasource containing this information is necessary:

The application properties file could look like the following:

openbis.user.name=${OPENBIS_USER_NAME:openbis-username}
openbis.user.password=${OPENBIS_USER_PASSWORD:openbis-password}
openbis.datasource.url=${OPENBIS_DATASOURCE_URL:openbis-url}

Properties

The environment variables can either be set in the runtime configuration of your IDE or directly in the application properties file:

server.port=${DM_PORT:8080}
logging.level.org.atmosphere=warn
spring.mustache.check-template-location=false
# Launch the default browser when starting the application in development mode
vaadin.launch-browser=true
# To improve the performance during development.
# For more information https://vaadin.com/docs/flow/spring/tutorial-spring-configuration.html#special-configuration-parameters
vaadin.whitelisted-packages=com.vaadin,org.vaadin,dev.hilla,life.qbic
# Database setup configuration
spring.datasource.url=${USER_DB_URL:localhost}
spring.datasource.driver-class-name=${USER_DB_DRIVER:com.mysql.cj.jdbc.Driver}
spring.datasource.username=${USER_DB_USER_NAME:myusername}
spring.datasource.password=${USER_DB_USER_PW:astrongpassphrase!}
spring.jpa.hibernate.ddl-auto=update
# mail configuration
spring.mail.username=${MAIL_USERNAME}
spring.mail.password=${MAIL_PASSWORD}
spring.mail.host=${MAIL_HOST:smtp.gmail.com}
spring.mail.default-encoding=UTF-8
spring.mail.port=${MAIL_PORT:587}
# global service route configuration for mail interaction requests
service.host.name=${DM_SERVICE_HOST:localhost}
service.host.protocol=${DM_HOST_PROTOCOL:https}
service.host.port=${DM_SERVICE_PORT:-1}
# Set the context path, for example if your app runs behind a proxy
server.servlet.context-path=${DM_SERVICE_CONTEXT_PATH:}
# route for mail confirmation consumption
email-confirmation-endpoint=${EMAIL_CONFIRMATION_ENDPOINT:login}
email-confirmation-parameter=${EMAIL_CONFIRMATION_PARAMETER:confirm-email}
# route for password reset
password-reset-endpoint=${PASSWORD_RESET_ENDPOINT:new-password}
password-reset-parameter=${PASSWORD_RESET_PARAMETER:user-id}
# openbis-client credentials
openbis.user.name=${OPENBIS_USER_NAME:openbis-username}
openbis.user.password=${OPENBIS_USER_PASSWORD:openbis-password}
openbis.datasource.url=${OPENBIS_DATASOURCE_URL:openbis-url}

Local testing

The default configuration of the app binds to the local port 8080 to the systems localhost. \ After starting the application it will be accessible at http://localhost:8080 in a browser of your choice.

http://localhost:8080

Production Deployment

To create a production build, call mvnw clean package -Pproduction (Windows), or ./mvnw clean package -Pproduction (Mac & Linux). \ This will build a JAR file with all the dependencies and front-end resources, ready to be deployed. The file can be found in the target folder after the build completes:

|-target
|---datamanager-{version}.jar
|---...

Once the JAR file is built, you can run it using java -jar target/datamanager-{version}.jar

How To Use

This guide intends to showcase the features of the data-manager-application

User Login

After startup the data manager application will redirect the user to the login screen hosted by default at

http://localhost:8080/login

This view enables the user to login into an already existing account by providing the required credentials.

Additionally, in this screen the user can request a password reset for his account if necessary. \ The user will then be contacted via the provided email address with the steps necessary to perform a password reset.\ Finally, the user is able to switch to the registration screen by clicking on the register button or the registration link

User Registration

This view is accessible by clicking on the register button or the registration link in the Login Screen. It is hosted by default at:

http://localhost:8080/register

This view enables the user to register a new account by providing the required credentials:

After successful registration the user will be contacted via the provided email address with the steps necessary to authenticate the generated account.

Application overview

Project structure

The project is composed of a multi-module maven structure divided into a domain and webapp module. The domain module hosts the business logic for user and data management.

Examples include:

• UserRegistrationService.java in src/main/java/life/qbic/apps/datamanager/services/ contains the application service used to register users for the user management domain context.
• policies package in src/main/java/domain/usermanagement/ contains the business logic to validate provided user information.
• repository folder in src/main/java/domain/usermanagement/ contains the connection logic between the application and the user database.

In contrast, the webapp module hosts the frontend components and services provided in the application.

Examples include:

• MainLayout.java in src/main/java/views/ contains the navigation setup (i.e., the side/top bar and the main menu). This setup uses App Layout.
• views package in src/main/java contains the server-side Java views of your application.
• views folder in frontend/ contains the client-side JavaScript views of your application.
• themes folder in frontend/ contains the custom CSS styles.

Vaadin Framework

This application employs the frontend components released in version 23 of the vaadin framework

Additional Information

• Read the documentation at vaadin.com/docs.
• Follow the tutorials at vaadin.com/tutorials.
• Watch training videos and get certified at vaadin.com/learn/training.
• Create new projects at start.vaadin.com.
• Search UI components and their usage examples at vaadin.com/components.
• View use case applications that demonstrate Vaadin capabilities at vaadin.com/examples-and-demos.
• Discover Vaadin's set of CSS utility classes that enable building any UI without custom CSS in the docs.
• Find a collection of solutions to common use cases in Vaadin Cookbook.
• Find Add-ons at vaadin.com/directory.
• Ask questions on Stack Overflow or join the vaadin Discord channel.
• Report issues, create pull requests in the vaadin GitHub.

License

This work is licensed under the MIT license.

This work uses the Vaadin Framework, which is licensed under Apache 2.0.

The University of Tübingen logo is a registered trademark and the copyright is owned by the University of Tübingen.