ALU Dev Documentation

Appearance

Developer Onboarding ​

Overview ​

ALU is made up of a few components:

  • UI Frontend: An Angular client side application.
  • Server Backend: A Spring Boot rest based server.
  • Keycloak Server: Keycloack is an identity and access management server.
  • Vite press docs: A documentation site built using Vite press.
  • IDEs for development: I use IntelliJ IDEA for the server side development and WebStorm for the client side development. Visual Studio Code is also a popular free IDE you can use.

[see Architectural Overview for more details]

While developing you will mainly be working on the UI Frontend and Server Backend.

Required Software ​

  • Java 21+: I develop using Amazon Correto 21
    • This is used in the development of the server side backend.
  • Node version ^22.0.0: You can find install instructions here
    • This is used in the development of the UI frontend and the documentation.
  • Docker: Install instructions can be found here
    • This is used to run the Keycloak server and the Postgres databases used by the backend and keycloak.
  • Maven?: Install instructions can be found here
    • This is used to build and run the server backend. If you are using IntelliJ IDEA or Visual Studio Code you can use the built in maven.

Checking out the code ​

The code is hosted on GitHub. You can clone the repository using the following command:

bash
git clone git@github.com:nrel-alu-code/alu.git

This git repository contains both the UI Frontend and Server Backend code as well as the source for this documentation and docker compose files for keycloak and Postgres.

  • src/main/java: Contains the server side code.
  • src/main/resources: Contains the server side resources.
  • src/main/ui: Contains the client side code.
  • docs: Contains the documentation source.
  • etc/compose/alu-dev: Contains the docker compose files for keycloak and Postgres.

Starting Postgres and Keycloak ​

bash
cd etc/compose/alu-dev
docker compose up -d

This will spin up 3 containers:

  • alu-dev-db: A Postgres database used by the server backend.
  • alu-dev-keycloak: A Keycloak server used for user authentication.
  • alu-dev-kc-db: A Postgres database used by the Keycloak server.

Note: By default when running the server locally user authentication is disabled. If you want to enable user authentication you will need to change the app.auth.enabled property to true. This can be done by creating a application-local.properties file in the src/main/resources/config directory and adding the following line:

properties
app.auth.enabled=true

src/main/resources/config/application-local.properties is excluded from git to allow developers to safely override properties.)

You will also need to enable it on the ui, by editing the src/main/ui/src/environments/environment.development.ts file and setting auth { enabled: true } (line 3).

Running the Server Backend ​

The server backend is a Spring Boot application. You can run the server using the following command:

bash
./mvnw spring-boot:run

But usually you would want to run the server in your IDE.

Running the UI Frontend ​

The UI Frontend is an Angular application. You can run the UI frontend using the following command:

bash
cd src/main/ui
npm install
npm start

Again, you would usually want to run the UI frontend in your IDE.

Running the Documentation Site ​

The documentation site is built using Vite press. You can run the documentation site using the following command:

bash
cd docs
npm run serve

This will start a live reload server that will automatically update the site as you make changes to the documentation. You can acceess it at http://localhost:5173.