docs: readme - how to use. Env example files (#54)

.env.example

@@ -0,0 +1,17 @@
+# database host value
+DB_HOST=localhost
+
+# admin username
+DB_ROOT_USER=admin
+
+# admin password
+DB_ROOT_PASSWORD=password
+
+# user with lower privileges
+DB_USER=dcuser
+
+# password for the user 
+DB_PASSWORD=password
+
+# database name
+DB_NAME=dc

README.md

@@ -13,19 +13,71 @@
 
 ## Table of Contents
 
-- [Code of Conduct](#-code-of-conduct)
-- [How to Contribute](#-how-to-contribute)
-- [License](#-license)
-- [Contributors](#contributors-)
+- [Table of Contents](#table-of-contents)
+- [❗ Code of Conduct](#-code-of-conduct)
+- [🙌🏻  How to Contribute](#--how-to-contribute)
+- [🏃  How to Run - Dev mode](#--how-to-run---dev-mode)
+  - [Requirements](#requirements)
+  - [Env files](#env-files)
+  - [Database](#database)
+  - [Backend](#backend)
+  - [Frontend](#frontend)
+  - [Usage](#usage)
+- [📝 License](#-license)
+- [Contributors ✨](#contributors-)
 
 ## ❗ Code of Conduct
 
 We expect everyone to abide by our [**Code of Conduct**](.github/CODE_OF_CONDUCT.md). Please read it. 🤝
 
-## 🙌🏻 How to Contribute
+## 🙌🏻  How to Contribute
 
 Check out our [**Contributing Guide**](.github/CONTRIBUTING.md) for information on contributing.
 
+## 🏃  How to Run - Dev mode
+
+To run the project you will need the requirements listed below and configure the env files as described in the example.
+In the near future all applications will be dockerized.
+
+### Requirements
+
+1. Node
+2. Docker
+3. Env files
+
+### Env files
+An .env file must be in the project root folder where the docker compose file is located and the others in each app folder (frontend and backend).
+This files are already provisioned as an example (`.env.example`) in the respective folders and you can use and edit them.
+
+The frontend .env file have two parameters named _JWT_SIGNING_KEY_ and *JWT_SIGNING_KEY_ID* that are required by next-auth on the frontend and to generate them just run the following command `npm install -g node-jose-tools` in the shell and after the installation, run `jose newkey -s 512 -t oct -a HS512`. Source: [Next-auth](https://next-auth.js.org/v3/warnings#jwt_auto_generated_signing_key).  
+After executing the last command an object is returned as:
+```
+{"kty": "oct","kid": "JWT_SIGNING_KEY_ID","alg": "HS512","k": "JWT_SIGNING_KEY"} 
+```
+The **kid** is the *JWT_SIGNING_KEY_ID* from the env file and **k** the *JWT_SIGNING_KEY*.
+
+### Database
+
+Since the database is the only app that is containerized, to run it step into the project root folder and run `docker-compose up -d`.
+The mongo image is downloaded, built and the database is created with the name that is passed as described in the env file parameter called *DB_NAME*. After the container is built, the init script that's inside the database folder runs in order to create a user to manage and connect to the database from the backend.
+
+### Backend
+
+To run this application for the first time run `npm i` inside the backend folder. Once you have installed the dependencies, simply run: `npm run start:dev`
+
+### Frontend
+
+To run this application for the first time run `npm i` inside the frontend folder. Once you have installed the dependencies, simply run: `npm run dev`
+
+### Usage
+
+The backend will run on `http://localhost:BACKEND_PORT` and the frontend on `http://localhost:3000`. Be aware the frontend root page ("/") is the landing page and has not yet been built so you must manually enter one of the following routes:
+
+- "/dashboard": dashboard
+- "/auth": authentication
+
+You must register to access the dashboard page
+
 ## 📝 License
 
 Licensed under the [MIT License](./LICENSE).

backend/.env.example

@@ -0,0 +1,29 @@
+# database host value
+DB_HOST=localhost
+
+# user with lower privileges
+DB_USER=admin
+
+# password for the user 
+DB_PASSWORD=password
+
+# database name
+DB_NAME=dc
+
+# database port
+DB_PORT=27017
+
+# backend port
+BACKEND_PORT=3200
+
+# a strong secret to sign the access tokens
+JWT_ACCESS_TOKEN_SECRET=a_strong_secret
+
+# expiration time of refresh token in seconds
+JWT_ACCESS_TOKEN_EXPIRATION_TIME=900
+
+# a strong secret to sign the refresh tokens
+JWT_REFRESH_TOKEN_SECRET=another_strong_secret
+
+# expiration time of refresh token in days
+JWT_REFRESH_TOKEN_EXPIRATION_TIME=1

frontend/.env.example

@@ -0,0 +1,14 @@
+# backend url exposed to the browser
+NEXT_PUBLIC_BACKEND_URL=http://localhost:3200
+
+# backend internal url
+BACKEND_URL=http://backend:3200
+
+# auth url exposed to the browser
+NEXTAUTH_URL=http://localhost:3000
+
+# key id to sign the JWT token
+JWT_SIGNING_KEY_ID=asxguiSEmbzqr9oukSY4uGYooG-sB4XMQB9uhRbbnQ0
+
+# key secret to sign the JWT token
+JWT_SIGNING_KEY=_Syz4zpGrqQCbwky4AkUQSm8FE8mpO4-Mwowr42sPeppnJmpKFLr8q6tlETXYpZ0rz8kwYx3VswXJiHOCDykCg