From f151b1f351bebdeb449f8b22c20c5019a1c4519f Mon Sep 17 00:00:00 2001 From: Andrei Punko Date: Mon, 30 Sep 2024 20:56:26 +0300 Subject: [PATCH] Rewrite and adjust READMEs --- README.MD | 142 ++++++++++++++++++++++++----------------- elk-filebeat/README.MD | 29 ++++----- 2 files changed, 96 insertions(+), 75 deletions(-) diff --git a/README.MD b/README.MD index 84aa9e4..6b05d69 100644 --- a/README.MD +++ b/README.MD @@ -1,17 +1,16 @@ -# Spring Boot backend app (Test task) +# Test task (Apple): Spring Boot backend app [![Java CI](https://github.com/andrei-punko/articles-backend-app/actions/workflows/maven.yml/badge.svg)](https://github.com/andrei-punko/articles-backend-app/actions/workflows/maven.yml) [![Coverage](.github/badges/jacoco.svg)](https://github.com/andrei-punko/articles-backend-app/actions/workflows/maven.yml) [![Branches](.github/badges/branches.svg)](https://github.com/andrei-punko/articles-backend-app/actions/workflows/maven.yml) +--- +## Requirements This should be purely a REST endpoints backend application without UI, but feel free to attach Swagger UI for convenience. -_Build tool_: Maven - -_DB_: Postgres - -_Source Control:_ GitHub (public) - -_Application name:_ articles-backend-app +- Build tool: Maven +- DB: Postgres +- Source Control: GitHub (public) +- Application name: articles-backend-app Application must be implemented using Spring Data (JPA/Hibernate) layer for communication with DB. @@ -21,28 +20,23 @@ Application should have no authentication. Application will allow to create, update and delete Articles. -Application will have " **authors**" entity with the following properties: - +Application will have `authors` entity with the following properties: - First Name - Last Name **Article** will have the following properties: Editable properties (updatable via endpoints): - - **Title** , text limited to 100 characters - **Summary** , text limited to 255 characters - **Text** , text with no specific limit - **Author:** relation with the **authors** table **. ONLY** updatable at creation. Should not be updatable after Article has been created Non-Editable properties, updated automatically by Application: - - Date Created - Date Updated - Application should expose REST endpoints that allow the following operations: - - Create new Article - Update existing Article - Only one property at the time should be updatable. @@ -51,13 +45,12 @@ Application should expose REST endpoints that allow the following operations: The Article JSON Payload returned by endpoint(s) must contain all properties of Article listed above. - Business Logic layer of the Application must enforce the following rules: - +Business Logic layer of the Application must enforce the following rules: - Non-editable properties cannot be updated/set via the create or update endpoints -- Article cannot be created or update with empty Title or Text or Author Id +- Article cannot be created or update with empty Title or Text or Author ID - Article cannot be created with specified author id that does not exist in the **authors** table -Any business logic constraint violation or any runtime error should return a HTTP 500 error with short description. +Any business logic constraint violation or any runtime error should return an HTTP 500 error with short description. (Guys confirmed that 400 errors could be used instead when needed as more appropriate) The implementation must contain adequate unit tests to cover business requirements and edge cases such as missing arguments etc. @@ -66,26 +59,32 @@ Application must build and produce an executable jar containing all dependencies The **authors** table should not be updatable via endpoints. Feel free to populate it with an arbitrary data via SQL. -## Additional functional +## Additional requirements (added by me) - Operation for getting existing Article -- Add pagination support for 'Retrieve all articles' operation +- Add pagination support for `Retrieve all articles` operation - Operations for getting authors +--- ## Prerequisites - Maven 3 - JDK 21 -## Build instructions - -#### Build application: - mvn clean install +--- +## Build an application: +```bash +mvn clean install +``` +Result `jar` placed into [target](target) folder -#### Build Docker image with application inside: - docker build ./ -t articles-backend-app +## Build Docker image with application inside: +```bash +docker build ./ -t articles-backend-app +``` -## How to start application +Result Docker image has name `articles-backend-app` as mentioned in command -#### Start application using Maven (vs in-memory DB H2): +--- +## Start application using Maven (vs in-memory DB H2): mvn spring-boot:run -Dspring-boot.run.arguments="\ --spring.datasource.url=jdbc:h2:mem:testdb \ --spring.datasource.username=sa \ @@ -96,7 +95,7 @@ Or next way, using `dev` spring profile: mvn spring-boot:run -Dspring-boot.run.arguments=--spring.profiles.active=dev -#### Start application by running executable jar (vs in-memory DB H2): +## Start application by running executable jar (vs in-memory DB H2): java -jar target/articles-backend-app-0.0.1-SNAPSHOT.jar \ --spring.datasource.url=jdbc:h2:mem:testdb \ --spring.datasource.username=sa \ @@ -108,54 +107,77 @@ Or next way, using `dev` spring profile: java -jar target/articles-backend-app-0.0.1-SNAPSHOT.jar \ --spring.profiles.active=dev -#### Start two Docker containers: one with Postgres DB and another with application: +### Start two Docker containers - with Postgres DB and application: docker-compose up -## Logs location +--- +## Link for quick check: +http://localhost:8099/api/v1/articles + +## Swagger documentation: +http://localhost:8099/swagger-ui.html -#### Check logs when start without Docker: +--- +## Check logs when start without Docker: less ./logs/spring-boot-logger.log -#### Check logs inside Docker container: +## Check logs when start using Docker: docker exec -it articles-backend-app sh less /logs/spring-boot-logger.log +--- -#### Swagger documentation situated here: - http://localhost:8099/swagger-ui.html +## Useful CURL commands -#### New article addition: - curl -i -H "Accept: application/json" -H "Content-Type: application/json" -d '{ "title": "Some tittle", "text": "Some text", "author": { "id": 1 } }' -X POST http://localhost:8099/api/v1/articles +### New article addition: +```bash +curl -i -X POST -H "Accept: application/json" -H "Content-Type: application/json" -d '{ "title": "Some tittle", "text": "Some text", "author": { "id": 1 } }' http://localhost:8099/api/v1/articles +``` -#### Get existing article: - curl -i http://localhost:8099/api/v1/articles/1 +### Get existing article: +```bash +curl -i http://localhost:8099/api/v1/articles/1 +``` -#### Update existing article: - curl -i -H "Accept: application/json" -H "Content-Type: application/json" -d '{ "title": "Another tittle" }' -X PATCH http://localhost:8099/api/v1/articles/2 +### Update existing article: +```bash +curl -i -X PATCH -H "Accept: application/json" -H "Content-Type: application/json" -d '{ "title": "Another tittle" }' http://localhost:8099/api/v1/articles/2 +``` -#### Get list of all articles: - curl -i http://localhost:8099/api/v1/articles +### Get list of all articles: +```bash +curl -i http://localhost:8099/api/v1/articles +``` -#### Get list of articles with pagination support: - curl -i 'http://localhost:8099/api/v1/articles?size=2&page=4&sort=author.firstName,DESC' +### Get list of articles with pagination support: +```bash +curl -i 'http://localhost:8099/api/v1/articles?size=2&page=4&sort=author.firstName,DESC' +``` -#### Deletion of article: - curl -i -X DELETE http://localhost:8099/api/v1/articles/1 +### Deletion of article: +```bash +curl -i -X DELETE http://localhost:8099/api/v1/articles/1 +``` -#### Get existing author: - curl -i http://localhost:8099/api/v1/authors/4 +### Get existing author: +```bash +curl -i http://localhost:8099/api/v1/authors/4 +``` -#### Get list of all authors: - curl -i http://localhost:8099/api/v1/authors +### Get list of all authors: +```bash +curl -i http://localhost:8099/api/v1/authors +``` -## To run functional tests: +--- +## Run functional tests: cd func-test ./gradlew clean build Check Spock report at `func-test/build/spock-reports/index.html` -## To run performance tests: - +--- +## Run performance tests: Gradle-based: cd load-test @@ -170,11 +192,11 @@ Or Maven-based: Based on https://gatling.io/docs/3.0/extensions/maven_plugin -## To check Web-Sockets functionality: - -Just enter in `http://localhost:8099` and click `Connect`. +--- +## Check Web-Sockets functionality: +Just open page http://localhost:8099 and click `Connect`. Check heartbeat logs in browser developer console. -## To taste ELK stack with logs providing by Filebeat: - -Check [ELK README](elk-filebeat/README.MD) +--- +## Taste ELK stack with logs providing by Filebeat: +Check [ELK README](elk-filebeat/README.MD) with details diff --git a/elk-filebeat/README.MD b/elk-filebeat/README.MD index d39942c..c4d56fd 100644 --- a/elk-filebeat/README.MD +++ b/elk-filebeat/README.MD @@ -1,27 +1,26 @@ -# ELK stack for service logs monitoring. Communication performing by Filebeat +# ELK stack for service logs monitoring -### Start containers with ELK stack and Filebeat: +Communication performing by Filebeat + +## Start containers with ELK stack and Filebeat: +From [elk-filebeat](.) folder: docker compose up -### Build and start article-backend-service -From project root: +## Build and start `article-backend-service` application +From project [root](..) folder: mvn clean install docker compose up -### Check saved logs via Kibana dashboard: - - http://localhost:5601 - -Using next login/password: `elastic/yourstrongpasswordhere` - -Choose `Discover` -> `Create index pattern`, and enter `filebeat-*` - -Take a look on saved records +## Check saved logs via Kibana dashboard: +- Open page http://localhost:5601 +- Use next `login/password` : `elastic/yourstrongpasswordhere` +- Choose `Discover` -> `Create index pattern`, and enter `filebeat-*` +- Take a look on saved records -### How to destroy ELK containers and volumes (with stored data): -From `elk-filebeat` folder: +## Destroy ELK containers and volumes (with stored data): +From [elk-filebeat](.) folder: docker-compose down --volumes