From 0cfabecbce6d13d397e9d24263bb81ece8bf020f Mon Sep 17 00:00:00 2001
From: Lars Johansson <lars.johansson@ess.eu>
Date: Fri, 8 Apr 2022 15:14:11 +0200
Subject: [PATCH] Add README.md content
---
README.md | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 76 insertions(+), 1 deletion(-)
diff --git a/README.md b/README.md
index ce055d65..42037c1f 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,77 @@
-# naming-backend
+# 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.
+
+Background and motivation, application and database design, and more is available through content in docs folder.
+
+### Environment
+
+Tools
+* Java 17 (openjdk)
+* Maven 3.8+ (e.g. 3.8.5)
+* PostgreSQL (9.6 client lib)
+* Docker (docker, docker-compose)
+* Git
+
+Dependencies
+* postgresql
+* springdoc
+* springframework
+* testcontainers
+
+### 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 (with database)
+
+Either
+
+* start the application and database
+ * ```docker-compose up --build```
+
+or
+
+* make sure database available as in ```src/main/resources/application.properties```
+* start the application
+ * ```java -jar target/naming-backend-*.jar```
+
+Then
+
+* browse to ```http://localhost:8080/swagger-ui.html```
+
+#### Integration tests with Docker containers
+
+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-it-db-schema-migration.yml```.
+
+```
+ @Container
+ public static final DockerComposeContainer<?> ENVIRONMENT =
+ new DockerComposeContainer<>(new File("docker-compose-it-db-schema-migration.yml"))
+ .waitingFor(ITUtil.NAMING, Wait.forLogMessage(".*Started NamingApplication.*", 1));
+```
+
+Thereafter a number of http requests (GET) and curl commands (PUT, POST, 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
+
+* 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 sub folders for database scripts.
+ * 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.
+
+#### Recommentation
+
+* Have local docker-compose file for database alone if there is need to backup or restore database.
--
GitLab