Basic Development
To run the application, you will need to complete the Setup steps. Once you have completed the Setup steps, you can run the application as described below.
First start the database service using Podman Compose. From the root of the project, run the following command:
podman-compose up -d
Then run the application:
./gradlew :server:run
This step requires your environment to be set. Reach out to the team for the run.sh file which, in addition to setting your environment, will execute the :server:run gradle task.
You can access the application by navigating to http://localhost:8080/login in your browser.
Next login to the application with:
- Username: existinguser@objectcomputing.com
- Password: SUPER
You can use any email that the system has in its loaded test data. The “password” is actually a role name. Most of the time you will want to use SUPER which is just an alias for all the roles.
Using the Native Executable
If you wish to use the native executables built with GraalVM, you will need to switch over to that Java compiler using the following command:
nvm use java 21.0.2-graalce
21.0.2-graalce is the most recent version of GraalVM Community Edition, as of the time this was written. You can replace that version with a different Graal distribution as appropriate.
You can then run a native build using:
./gradlew nativeCompile
Then replace the ./gradlew :server:run command used above with:
./server/build/native/nativeCompile/check-ins
API Documentation
With server running locally, API documentation is available at http://localhost:8080/swagger-ui/index.html. This documentation is generated by Micronaut and provides a way to interact with the API directly from the browser.
Running the UI
The UI will be available on port 8080 once the application is running. The UI is served from the web-ui directory. The UI is built using Vite, a modern build tool for frontend development. The UI is written in JavaScript and uses React and Vitest.
Node Version
When developing against the UI, please use the latest Node LTS. A .nvmrc file is provided in the web-ui directory to help you manage the Node version. You can use the following command to switch to the expected Node version:
nvm install --lts
nvm use --lts
Or cd to the web-ui directory and run nvm use to be prompted to install the expected Node version as configured in the .nvmrc file.
HMR
For hot reloading during UI development, you can use the following command to start a Vite server:
yarn --cwd web-ui start
Or simply cd to the web-ui directory and run yarn start. When developing the UI, you can access the Vite server at http://localhost:5173.
Running Tests
To run the UI tests, use the following command:
yarn --cwd web-ui test
Or simply cd to the web-ui directory and run yarn test. Tests using Snapshots are likely to fail with component updates. Those which fail to meet their Snapshot will be marked as failed. You can update the Snapshot by running the following command:
yarn --cwd web-ui test -u # or simply `yarn test` followed by `u`
Testing Library is installed in the UI project. You can find more information about Testing Library here.
Testing the Native Executable
If you wish to test the native executables built with GraalVM, you will need to switch over to that Java compiler using the following command:
nvm use java 21.0.2-graalce
You can then run the native tests like so:
./gradlew nativeTest
Running the Server
Running Tests
To skip building the UI when running unit tests in the Server application add the environment variable SKIP_WEB_UI=true to your system or run configuration.
When running the full application UI/Server together it is important to remember to reset SKIP_WEB_UI=false. If you are using a run.sh script to launch the app
simply add export SKIP_WEB_UI=false to it.
Connecting to the database
The application uses a PostgresSQL database. The database runs on port 5432 by default as defined in docker-compose.yaml.
You can connect to the database on the default port using the following command:
psql -h localhost -U postgres -d checkinsdb
The password for the dev database is postgres.
Once connected, you can run SQL queries against the database, inspect the schema, and more.
Seeding the database
The application uses Flyway to manage database migrations. The migrations are located in the server/src/main/resources/db directory. The migrations are run automatically when the application starts.
For test data, a Repeatable Migration called R__Load_testing_data.sql is used to seed the database with test data. This migration is run every time the application starts.
Working with encrypted data
Sensitive columns in the database are stored encrypted. The application leverages pgcrypto to encrypt and decrypt these datum. The encryption key used is stored in the AES_KEY environment variable. The key is a 256-bit key encoded in base64. This key is used to encrypt and decrypt the data and will be available in the environment when the application is setup.
When running queries against the database, you will see the encrypted data. To decrypt the data, you can use the pgp_sym_decrypt function provided by pgcrypto. For example:
SELECT pgp_sym_decrypt(encrypted_column, 'AES_KEY') FROM table_name;
For more examples and information on working with encrypted data, refer to the pgcrypto documentation.