Bookworm Library Web Application Backend [Work In Progress]

Java Spring Boot REST API

This is a toy app I once made in my free time. Application is dockerized - use run_prod.sh to build and start containers (must have docker and docker-compose installed).

When running on development environment, go to http://localhost:8000/swagger-ui.html to see API documentation.

Where to look for services

Development environment: start support services with run_dev.sh and use gradle to start backend on localhost:8000

./gradlew bootRun --args='--spring.profiles.active=dev'

• Bookworm Swagger UI: http://localhost:8000/swagger-ui.html
• Keycloak: http://localhost:8080/ - admin:admin
• Prometheus: http://localhost:9090/
• Grafana: http://localhost:3000/ - admin:admin
• PgAdmin4: http://localhost/ - [email protected]:password
• Postgres: tcp://localhost/5432

Production environment: start it with run_prod.sh, only bookworm-backend:8000 will be exposed on docker host (swagger-ui not available):

• Bookworm Backend: http://localhost:8000/
• Keycloak: http://bookworm-keycloak:8080/
• Prometheus: http://bookworm-prometheus:9090/
• Grafana: http://bookworm-grafana:3000/
• PgAdmin4: http://bookworm-pgadmin/
• Postgres: tcp://bookworm-postgres/5432

Running with Spring Cloud

Uncomment id "org.springframework.cloud.contract" version "2.1.5.RELEASE" in build.gradle to be able to run cloud version. bootstrap.properties ensures that app uses config server if one is available. When using config server add cloud to dev/prod profile to register with eureka (discovery service).

./gradlew bootRun --args='--spring.profiles.active=dev,cloud'

SpringBoot dashboard for Grafana

• add Prometheus on Graphana Data Sources config page, service address when running with prod profile will be http://bookworm-prometheus:9090/
• import dashboard definition to see any statistics from application
• run tests to create some traffic

Dashboard definition Spring Boot Statistics can be found on Grafana webpages:

https://grafana.com/grafana/dashboards/12464

Test examples included in project

Use run_dev.sh and ./gradlew bootRun to run tests on dev with

• gradle: ./gradlew test -Dkarate.env=dev

Alternatively, you can run tests also with run_prod.sh on prod (inside docker created network). To run tests on that environment put 127.0.0.1 docker in /etc/hosts and use mvn verify -DargLine="-Dkarate.env=test".

There are also properties for test env for karate and spring. Those properties are used with Gitlab CI pipeline.

Unit tests with junit4, mockito and assertj

• Tests are located in src/test/java/org/bookworm/library/services folder

Integration tests based on RestAssured library

• Tests are located in src/test/java/org/bookworm/library/controllers folder
• REST Assured webpage: https://rest-assured.io/

Integration REST API tests based on karate library

• Tests are located in src/test/java/org/bookworm/library/karate folder
• Karate webpage: https://github.com/karatelabs/karate

Integration security tests based on spock and groovy

• Tests are located in src/test/groovy folder
• Spock framework webpage: https://spockframework.org/
• Groovy webpage: https://groovy-lang.org/

E2E Tests based on Testcontainers

• Tests are located in src/test/java/org/bookworm/library/auth folder
• Testcontainers webpage: https://www.testcontainers.org/

Checkstyle

• checkstyle.xml config file located in main project folder is based on Google Checks (Feb 7 2022)
• Source: https://github.com/checkstyle/checkstyle/blob/master/src/main/resources/google_checks.xml

Liquibase

Project use liquibase to manage database schema changes. Schema changelog files are located in src/main/resources/db/changelog folder.

How to export database to Liquibase changelog file

Install liquibase with appropriate package manager.

liquidbase --url=jdbc:postgresql://localhost:5432/bookworm_library --username=bookworm_user \
--password=xyzXYZxyz --changeLogFile=output2.xml --diffTypes=data generateChangeLog

Kubernetes deployment config

Kubernetes deployment's files are located in k8s folder.

Terraform deployment for Azure Cloud

Deployment to Azure Container Instances

Deployment files are located in tf/azure/aci folder.

Deployment to Azure Container Instances with local docker

Read docker/AZURE_COMPOSE.md for recipe.

How to export Realm config from Keycloak

Enable configuration 4 realm data export config in docker-compose.yml and run run_dev.sh to start keycloak with postgres.

docker/docker-compose up bookworm_postgres bookworm_keycloak

Execute command:

docker exec -it bookworm-keycloak /opt/jboss/keycloak/bin/standalone.sh \
-Djboss.socket.binding.port-offset=100 \
-Dkeycloak.migration.action=export \
-Dkeycloak.migration.provider=singleFile \
-Dkeycloak.migration.realmName=bookworm \
-Dkeycloak.migration.usersExportStrategy=REALM_FILE \
-Dkeycloak.migration.file=/tmp/realm-bookworm.json

Command will create /tmp/realm-bookworm.json config file. Move file to docker/keycloak and src/test/resources.

SonarQube call with Gradle

./gradlew sonarqube -Dsonar.projectKey=bookworm-backend \
-Dsonar.host.url=http://localhost:9000 -Dsonar.login=PUT-SONAR-TOKEN-HERE

How to register local GitLab Runner with container support

Docker-in-Docker with TLS enabled in the Docker executor method

https://docs.gitlab.com/ee/ci/docker/using_docker_build.html

sudo gitlab-runner register -n \
--url https://gitlab.com/ \
--registration-token PUT-GITLAB-TOKEN-HERE \
--executor docker \
--description "Bookworm Runner" \
--docker-image "docker:20.10.12" \
--docker-privileged \
--docker-volumes "/certs/client"