From a8c7bffe9f6d57db5a55762ff42ea61fbac26556 Mon Sep 17 00:00:00 2001 From: Ricardo Campos Date: Fri, 1 Nov 2024 20:57:43 -0300 Subject: [PATCH] chore: improve readme and automations (#133) --- CONTRIBUTING.md | 81 +++++++++++ README.md | 140 ++------------------ client/Dockerfile.dev | 2 +- client/package.json | 2 +- client/run-from-docker.sh | 37 ++++++ client/src/constants/languages_available.ts | 12 ++ client/src/views/Landing/index.tsx | 41 ++---- client/src/views/Landing/styles.scss | 1 + server/Dockerfile.dev | 2 +- server/run-from-docker.sh | 34 +++++ server/run.dev.sh | 6 - tools/check-backend.sh | 5 +- tools/check-frontend.sh | 3 + tools/run-create-env.sh | 25 ++++ tools/run-docker-client.sh | 19 ++- tools/run-docker-db.sh | 7 + tools/run-docker-server.sh | 7 + tools/run-local-client.sh | 8 -- tools/run-local-server.sh | 10 -- 19 files changed, 255 insertions(+), 187 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 client/run-from-docker.sh create mode 100644 client/src/constants/languages_available.ts create mode 100755 server/run-from-docker.sh delete mode 100755 server/run.dev.sh create mode 100644 tools/check-frontend.sh create mode 100644 tools/run-create-env.sh delete mode 100644 tools/run-local-client.sh delete mode 100644 tools/run-local-server.sh diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..7367789 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,81 @@ +# 🤝 Contributing + +Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. + +This project is an opensource project, meaning you can contribute as many times as you want! We work with the **Fork & Merge** flow. + +If you want to contribute, please create a fork and a Merge Request. Take a look [here to learn more.](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) + +## Steps to Contribute + +1. Fork the Project +2. Clone it on your local (`git clone https://github.com/ricardo-campos-org/react-typescript-todolist`) +3. Develop your amazing feature/changes +4. Make sure your name is set (`git config user.name 'YOUR NAME'; git config user.email 'YOUR EMAIL'`) +5. Commit your changes (`git commit -m 'Add some amazing feature'`) +6. Push to the Branch (`git push`) +7. Open a Merge Request + +## 🏃‍♀️ Running locally + +> If your OS is Microsoft Windows, make sure to run this on a Linux VM over WSL2. + +The easiest way of having the app up and running is using [Docker](https://www.docker.com/). Once you're all set, follow these steps to see it live locally: + +1. Start the database engine (PostgreSQL) + ```sh + bash tools/run-docker-db.sh + ``` +2. Start the back-end engine (Java & Spring Boot) + ```sh + bash tools/run-docker-server.sh + ``` +3. Start the app server + ```sh + bash tools/run-docker-client.sh + ``` + +> Remember to follow up logs with 'docker ps' and 'docker logs -f ' + +If everything went well, you can head to [http://localhost:5000](http://localhost:5000) and create your user. + +## 🦾 Automation + +Once you finish your changes, just create a Merge Request to get started. + +This project has workflows to ensure quality code, including linting, testing and security checks. Your changes will be merged only after all check passes. + +You can check locally if changes are passing: + +1. Back-end + ```sh + bash tools/check-backend.sh + ``` +2. Front-end + ```sh + bash tools/check-frontend.sh + ``` + +> Remember to follow up logs with 'docker ps' and 'docker logs -f ' + +## Debugging Java + +You might need to create a `launch.json` file. Here's a working one + +```json +{ + // Use IntelliSense to learn about possible attributes. + // Hover to view descriptions of existing attributes. + // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 + "version": "0.2.0", + "configurations": [ + { + "type": "java", + "name": "Debug (Attach)", + "request": "attach", + "hostName": "localhost", + "port": 5005 + } + ] +} +``` diff --git a/README.md b/README.md index 01dc420..d516c44 100644 --- a/README.md +++ b/README.md @@ -16,18 +16,20 @@ ## 📝 About the Project -TaskNote was created to make our lives easier. In a nutshell, you can manage your TODOs and your -Notes. +TaskNote was firstly created to meet my personal needs of having a simple tool to manage tasks and notes. Clean and minimal. However after a couple of weeks I was assigned a challenge to finish within one month a set of tasks, technical tasks, that I decided to put it practice here, at this project. At the end of that month, I got most the app ready. -A key feature is that you can `#tag` a todo or note and search or filter later. - -TODO: add GIF or screenshot of the app +Then I decided keep going, found a host and a name. And that's it. Here we are! ## ✨ Features -- Create and manage TODO items -- Create and manage Notes -- Tag TODOs and Notes +- Current features + - Create and manage TODO items + - Create and manage Notes + - Search by any matching text + - A key feature is that this tool is super simple, but effective. +- Upcoming features + - `#tag` a task or note + - Improved search filters ## 🚀 Tech Stack @@ -36,125 +38,9 @@ TODO: add GIF or screenshot of the app - **Database:** PostgreSQL, Flyway - **Other Technologies:** Docker, Docker Compose, Caddy -## 🛠 Installation +## 🛠 Contributing -1. Clone the repo - ```sh - git clone https://github.com/ricardo-campos-org/react-typescript-todolist - ``` -2. Install NPM packages - ```sh - npm install - ``` -3. Start the development server - ```sh - npm start - ``` - -## 🏃‍♀️ Running locally - -### Locally without Docker - - **Client:** - - ```sh - cd client - npm install - npm start - ``` - - **Server - Java API:** - ```sh - cd server - ./mvnw spring-boot:run \ - -Dspring-boot.run.jvmArguments="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005" - ``` - - PS: You have the option to define four environment variables for the database connection. In case - you decide not to do, they'll be set to default. They are: - - ``` - POSTGRES_HOST=localhost - POSTGRES_DB=tasknote - POSTGRES_USER=tasknoteuser - POSTGRES_PASSWORD=default - ``` - - PS2: Java API needs a running database to work. You can leverage Docker Compose for this, running - this command: - - ```sh - docker-compose up --profile dev postgres -d - ``` - - **Checking if it's running:** - - - You can head to the Actuator Health page at: http://localhost:8585/actuator/health - - And you want, you can open up the Swagger UI at: http://localhost:8585/swagger-ui/index.html - -### Locally with Docker Compose - **All at once:** - ```sh - docker compose --profile dev up -d - ``` - - **Cleaning up:** - ```sh - docker compose --profile dev down --remove-orphans - ``` - -## 🦾 Automation - -### Client - -Unit tests: Client relies on these libraries: - - React-Testing-Library - - Vitest - -Here's how you can run locally: - -```sh -cd client -npm run test -``` - -**Integration tests** - -Not available. - -**Code style enforcement** - -Here, ESlint, Airbnb - -### Java API - -**Unit tests** - -Here - -**Integration tests** - -Here - -**Code style enforcement** - -Google Checkstyle - -## 🎮 Usage - -Once you're in the home screen, you can click the button to create your first TODO item. - -## 🤝 Contributing - -Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. - -### Steps to Contribute: - -1. Fork the Project -2. Create your Feature Branch (`git checkout -b feat/amazing-feature`) -3. Commit your Changes (`git commit -m 'Add some amazing feature'`) -4. Push to the Branch (`git push origin feat/amazing-feature`) -5. Open a Pull Request +Please refer to the [CONTRIBUTING](CONTRIBUTING.md) file for more information about how to run this application from source, and/or how to contribute. ## 📄 License @@ -162,4 +48,4 @@ Distributed under GPLv3 License. See `LICENSE` for more information. ## 📞 Contact -Ricardo Campos on X - [@RicardoMpcInc](https://twitter.com/RicardoMpcInc) +Reach out on X [@XerifeRicWoody](https://twitter.com/XerifeRicWoody) or email me ricardocampos@gmail.com diff --git a/client/Dockerfile.dev b/client/Dockerfile.dev index 17c18b0..6c839bb 100644 --- a/client/Dockerfile.dev +++ b/client/Dockerfile.dev @@ -1,4 +1,4 @@ FROM node:20.18-bookworm WORKDIR /app HEALTHCHECK CMD timeout 10s bash -c 'true > /dev/tcp/127.0.0.1/5000' -ENTRYPOINT [ "npm", "start" ] +CMD ["sh", "run-from-docker.sh"] diff --git a/client/package.json b/client/package.json index 11d4f31..b7a7752 100644 --- a/client/package.json +++ b/client/package.json @@ -35,7 +35,7 @@ "start": "vite --host", "build": "tsc && vite build", "preview": "vite build && vite preview", - "test": "vitest -u", + "test": "vitest --watch=false", "test:coverage": "vitest run --coverage --watch=false", "lint": "./node_modules/.bin/eslint", "lint:fix": "./node_modules/.bin/eslint --fix" diff --git a/client/run-from-docker.sh b/client/run-from-docker.sh new file mode 100644 index 0000000..0c425e0 --- /dev/null +++ b/client/run-from-docker.sh @@ -0,0 +1,37 @@ +#!/bin/bash +# Client - Front-end + +npm install +if [ $? -eq 1 ]; then + echo "Issues when installing dependencies. Please review.." + exit 1 +fi + +if [ -z "$CHECK" ]; then + npm start +else + echo "Running checks..." + echo "1/3 - Lint started..." + npm run lint:fix + if [ $? -eq 1 ]; then + echo "Issues when running lint. Please review.." + exit 1 + fi + + echo "2/3 - Build started..." + npm run build + if [ $? -eq 1 ]; then + echo "Issues when running build. Please review.." + exit 1 + fi + + echo "3/3 - Tests started..." + npm run test + if [ $? -eq 1 ]; then + echo "Issues when running test. Please review.." + exit 1 + fi + + echo "You're good to go! Good job!" + exit 0 +fi diff --git a/client/src/constants/languages_available.ts b/client/src/constants/languages_available.ts new file mode 100644 index 0000000..4308212 --- /dev/null +++ b/client/src/constants/languages_available.ts @@ -0,0 +1,12 @@ +import USER_LANG from '../types/UserLangs'; + +export interface LangAvailable { + lang: string; + key: string; +} + +export const languages: LangAvailable[] = [ + { lang: USER_LANG.ENGLISH, key: 'landing_btn_english' }, + { lang: USER_LANG.PORTUGUESE, key: 'landing_btn_portuguese' }, + { lang: USER_LANG.SPANISH, key: 'landing_btn_spanish' } +]; diff --git a/client/src/views/Landing/index.tsx b/client/src/views/Landing/index.tsx index 8c8a450..a2a03fb 100644 --- a/client/src/views/Landing/index.tsx +++ b/client/src/views/Landing/index.tsx @@ -3,10 +3,10 @@ import { Button, Container } from 'react-bootstrap'; import { useNavigate } from 'react-router-dom'; import { useTranslation } from 'react-i18next'; import AuthContext from '../../context/AuthContext'; -import USER_LANG from '../../types/UserLangs'; import { handleDefaultLang } from '../../lang-service/LangHandler'; import { setDefaultLang } from '../../storage-service/storage'; import './styles.scss'; +import { LangAvailable, languages } from '../../constants/languages_available'; /** * Landing page component. @@ -77,7 +77,7 @@ function Landing(): JSX.Element { - - - - + {languages.map((lang: LangAvailable) => ( + + ))} diff --git a/client/src/views/Landing/styles.scss b/client/src/views/Landing/styles.scss index 392da0f..7b0aae9 100644 --- a/client/src/views/Landing/styles.scss +++ b/client/src/views/Landing/styles.scss @@ -41,6 +41,7 @@ $dark-text: #343a40; .btn-lg { font-size: 1rem; padding: 0.75rem 1.5rem; + min-width: 10rem; } .btn-primary { diff --git a/server/Dockerfile.dev b/server/Dockerfile.dev index 84061d7..11ad02d 100644 --- a/server/Dockerfile.dev +++ b/server/Dockerfile.dev @@ -1,4 +1,4 @@ FROM maven:3.9.9-eclipse-temurin-17 WORKDIR /app HEALTHCHECK CMD timeout 10s bash -c 'true > /dev/tcp/127.0.0.1/8585' -ENTRYPOINT [ "./run.dev.sh" ] +CMD ["sh", "run-from-docker.sh"] diff --git a/server/run-from-docker.sh b/server/run-from-docker.sh new file mode 100755 index 0000000..ae4fa14 --- /dev/null +++ b/server/run-from-docker.sh @@ -0,0 +1,34 @@ +#!/bin/bash +# Server - Back-end + +if [ -z "$CHECK" ]; then + ./mvnw -ntp \ + spring-boot:run \ + -Dspring-boot.run.jvmArguments="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=*:5005" \ + -Dmaven.plugin.validation=VERBOSE +else + echo "Running checks..." + echo "1/3 - Check Style started..." + ./mvnw --no-transfer-progress checkstyle:checkstyle -Dskip.checkstyle=false + if [ $? -eq 1 ]; then + echo "Issues when running Check Style. Please review.." + exit 1 + fi + + echo "2/3 - Build started..." + ./mvnw --no-transfer-progress clean compile -DskipTests + if [ $? -eq 1 ]; then + echo "Issues when running build. Please review.." + exit 1 + fi + + echo "3/3 - Tests started..." + ./mvnw --no-transfer-progress clean verify -P tests --file pom.xml + if [ $? -eq 1 ]; then + echo "Issues when running test. Please review.." + exit 1 + fi + + echo "You're good to go! Good job!" + exit 0 +fi diff --git a/server/run.dev.sh b/server/run.dev.sh deleted file mode 100755 index 1d06d6a..0000000 --- a/server/run.dev.sh +++ /dev/null @@ -1,6 +0,0 @@ -#!/bin/bash - -./mvnw -ntp \ - spring-boot:run \ - -Dspring-boot.run.jvmArguments="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=*:5005" \ - -Dmaven.plugin.validation=VERBOSE diff --git a/tools/check-backend.sh b/tools/check-backend.sh index ce51afe..e2d240e 100755 --- a/tools/check-backend.sh +++ b/tools/check-backend.sh @@ -1,6 +1,3 @@ #!/bin/bash -cd server -./mvnw --no-transfer-progress clean compile -DskipTests && \ - ./mvnw --no-transfer-progress checkstyle:checkstyle -Dskip.checkstyle=false && \ - ./mvnw --no-transfer-progress clean verify -P tests --file pom.xml \ No newline at end of file +docker run -it --rm --name server -e CHECK="TRUE" -v ./server:/app server:nightly diff --git a/tools/check-frontend.sh b/tools/check-frontend.sh new file mode 100644 index 0000000..637e3f2 --- /dev/null +++ b/tools/check-frontend.sh @@ -0,0 +1,3 @@ +#!/bin/bash + +docker run -it --rm --name client -e CHECK="TRUE" -v ./client:/app client:nightly diff --git a/tools/run-create-env.sh b/tools/run-create-env.sh new file mode 100644 index 0000000..b798a28 --- /dev/null +++ b/tools/run-create-env.sh @@ -0,0 +1,25 @@ +#!/bin/bash + +TARGET="$1" + +if [ "$TARGET" == "back" ]; then + echo "Creating basic env file for database and back-end" + cd server + + echo "POSTGRES_DB=postgres" >> .env + echo "POSTGRES_HOST=localhost" >> .env + echo "POSTGRES_USER=postgres" >> .env + echo "POSTGRES_PASSWORD=default" >> .env + echo "POSTGRES_PORT=5432" >> .env + echo "SERVER_SERVLET_CONTEXT_PATH=/" >> .env + echo "CORS_ALLOWED_ORIGINS=http://localhost:5000" >> .env +if [ "$TARGET" == "front" ]; then + echo "Creating basic env file for the front-end app" + cd client + + echo "VITE_BACKEND_SERVER=http://localhost:8585" >> .env + echo "VITE_BUILD=nightly" >> .env +else + echo "Wrong parameter..." +fi +echo "Done!" diff --git a/tools/run-docker-client.sh b/tools/run-docker-client.sh index 4225b0f..874c0b9 100644 --- a/tools/run-docker-client.sh +++ b/tools/run-docker-client.sh @@ -1,5 +1,12 @@ #!/bin/bash +if [ ! -f "server/.env" ]; then + echo "No env file found for front-end. Creating one for you.." + bash tools/run-create-env.sh "front" +else + echo "Env file in place. Moving on.." +fi + echo "Getting env vars and making them visible" cd client/ export $(cat .env | xargs) @@ -9,14 +16,24 @@ cd .. docker build --file client/Dockerfile.dev --tag client:nightly . +if [ $? -eq 1 ]; then + echo "Issues when building Docker image. Please review.." + exit 1 +fi + SERVER_HOST="http://"$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' server)":8585" +if [ "$SERVER_HOST" == "http://:8585" ]; then + echo "Back-end server not running. Make sure to run it before starting the web app." + exit 0 +fi + echo "SERVER_HOST=$SERVER_HOST" docker run -d --rm \ --name client \ -p 5000:5000 \ -e VITE_BACKEND_SERVER="$SERVER_HOST" \ - -e VITE_BUILD=nightly \ + -e VITE_BUILD="$VITE_BUILD" \ -v ./client:/app \ client:nightly diff --git a/tools/run-docker-db.sh b/tools/run-docker-db.sh index 1956fb1..225013e 100644 --- a/tools/run-docker-db.sh +++ b/tools/run-docker-db.sh @@ -1,5 +1,12 @@ #!/bin/bash +if [ ! -f "server/.env" ]; then + echo "No env file found for back-end. Creating one for you.." + bash tools/run-create-env.sh "back" +else + echo "Env file in place. Moving on.." +fi + echo "Getting env vars and making them visible" cd server/ export $(cat .env | xargs) diff --git a/tools/run-docker-server.sh b/tools/run-docker-server.sh index 145aa0e..c9074fa 100644 --- a/tools/run-docker-server.sh +++ b/tools/run-docker-server.sh @@ -1,5 +1,12 @@ #!/bin/bash +if [ ! -f "server/.env" ]; then + echo "No env file found for back-end. Creating one for you.." + bash tools/run-create-env.sh "back" +else + echo "Env file in place. Moving on.." +fi + echo "Getting env vars and making them visible" cd server/ export $(cat .env | xargs) diff --git a/tools/run-local-client.sh b/tools/run-local-client.sh deleted file mode 100644 index fb6a203..0000000 --- a/tools/run-local-client.sh +++ /dev/null @@ -1,8 +0,0 @@ -#!/bin/bash - -echo "Getting env vars and making them visible" -cd client/ -export $(cat .env | xargs) -echo "Done!" - -npm start diff --git a/tools/run-local-server.sh b/tools/run-local-server.sh deleted file mode 100644 index 8f5c6b0..0000000 --- a/tools/run-local-server.sh +++ /dev/null @@ -1,10 +0,0 @@ -#!/bin/bash - -echo "Getting env vars and making them visible" -cd server/ -export $(cat .env | xargs) -echo "Done!" - -./mvnw -ntp spring-boot:run \ - -Dspring-boot.run.jvmArguments="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=*:5005" \ - -Dmaven.plugin.validation=VERBOSE