Naming

The purpose of Naming is to handle Naming of ESS wide physical and logical devices according to ESS Naming Convention.

Naming backend

Naming backend is a web application implemented as a REST style web service backed by a relational database. The web service is implemented as a Spring Boot application and the database is available as PostgreSQL.

See docs and sub folders to learn how ESS Naming Convention is implemented in Naming backend.

• what an ESS name is and how to think about it (to better understand how to work with it)
• concepts & terminology
• application & database, architecture & design
• flow of code
• user & developer perspectives

Environment

Tools

• Java 17 - openjdk
• Maven 3.8+
• PostgreSQL - 9.6 client lib
• Docker - engine 18.06.0+ or later, compose 1.29.2 or later, compose file version 3.7 to be supported
• Git

Dependencies

• postgresql
• springdoc
• springframework
• testcontainers

In addition, Hibernate is used through Springframework.

Set up development environment and test

Checkout and build

• git clone https://gitlab.esss.lu.se/ics-software/naming-backend.git
• cd directory
• mvn clean install

Start application

For first time users, recommended way to start application is with Docker and database with demo content. See Note for more on configuration.

Either with Docker

• start application & database
  • existing database container
    • docker-compose up --build
  • empty
    • docker-compose -f docker-compose-integrationtest.yml up --build
  • demo content
    • docker-compose -f docker-compose-demo.yml up --build
• browse to http://localhost:8080/swagger-ui.html

or with java -jar

• make sure database available as in src/main/resources/application.properties
• start application
  • java -jar target/naming-backend-*.jar
  • java -jar -Dspring.datasource.url=jdbc:postgresql://localhost:5432/discs_names target/naming-backend-*.jar
• browse to http://localhost:8080/swagger-ui.html

Integration tests with Docker containers

Purpose of integration tests is to ensure REST API works as expected for parts and as a whole by running tests against running instances of application and database.

See src/test/java and packages

• org.openepics.names.docker
• org.openepics.names.docker.complex

JUnit tests start a docker container for the application (Naming backend) and another docker container for the database (Postgresql) through docker-compose-integrationtest.yml.

    @Container
    public static final DockerComposeContainer<?> ENVIRONMENT =
        new DockerComposeContainer<>(new File("docker-compose-integrationtest.yml"))
            .waitingFor(ITUtil.NAMING, Wait.forLogMessage(".*Started NamingApplication.*", 1));

Thereafter a number of http requests (GET) and curl commands (POST, PUT, PATCH, DELETE) are run towards the application to test behavior (CRUD - create, read, update, delete) and replies are received and checked if content is as expected.

Note

• Do not
  • commit sensitive data
  • modify application properties and docker-compose files unless necessary - there are multiple dependencies
• Not yet
  • Authentication / Authorization
  • Flyway
• If tools need to be installed or upgraded, recommendation is to install or upgrade to most recent versions that are available, unless otherwise stated.
• Configuration
  • Application and database may be started separately, with or without Docker, in which case configuration set by environment variables, docker compose files and application.properties must reflect this. An example of this is hostname/ip address/port for database that is to be available for application. Configuration must not be in conflict with environment in which application and database run.
• Pre-populated database to be available if data to be available at start of application. Otherwise database may be populated through curl at command line or Swagger UI.
  • See src/main/resources and src/test/resources and sub folders for database scripts. This includes scripts for database schema, migration and example content.
  • If no prior database is available, see integration tests for examples on how to populate database. E.g. tests may be debugged and database content may be examined at any debug point. It's possible to backup database at such debug point and later restore it outside test. In such way, database may be set to state of choice.

  postgres:
    volumes:
      - ./src/test/resources/db/data/dump-discs_names_namesit.sql:/docker-entrypoint-initdb.d/dump-discs_names_namesit.sql

Recommentation

• Have local docker-compose files - .gitignore contains docker-compose-local*
  • for application and database together that may contain local configuration
  • for database alone if there is need to backup or restore database