Start adding documentation (setup, configuration, etc)

livraria-papelaria-espaco · Dec 11, 2022 · 810e3d4 · 810e3d4
1 parent 2b17b4e
commit 810e3d4
Show file tree

Hide file tree

Showing 6 changed files with 196 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -9,9 +9,13 @@ The GraphQL API is used most of the time from the frontend, and the data is stor
 
 For the frontend, [NextJS](https://nextjs.org) was used, along with the [Material-UI](https://material-ui.com) design library.
 
-
 ## Contribute
 
 Feel free to open issues if you find any bugs or want to suggest an improvement.
 
 If you have the knowledge to do so, you can also open a pull request to fix some issues!
+
+## Documentation
+
+Documentation on how to setup the project locally, as well as deploying it, can be
+found on the [docs](./docs) folder.
diff --git a/docs/01-requirements.md b/docs/01-requirements.md
@@ -0,0 +1,33 @@
+# System Requirements
+
+Running this website requires the following:
+
+- Node.js 14 LTS
+- Yarn package manager
+- A MongoDB database
+- Docker (for Meilisearch only)
+
+## Setting up a temporary MongoDB database with Docker
+
+This method is aimed at a development environment.
+
+Create a new folder and place `docker-compose.yml` inside it:
+
+```yml
+version: '3.8'
+
+services:
+  mongodb:
+    image: mongo
+    container_name: mongodb
+    volumes:
+      - ./database:/data/db
+    ports:
+      - 27017:27017
+```
+
+Then run `sudo docker-compose up -d` to start the database.  
+This database does not start automatically on PC startup and can be stopped
+at any time with `sudo docker-compose down`.
+
+A `database` folder is created and used to persist data across reboots.
diff --git a/docs/02-configuration.md b/docs/02-configuration.md
@@ -0,0 +1,64 @@
+# Configuration
+
+The backend, frontend and meilisearch can all be configured through environment
+variables.
+For development, the easiest way is to create a `.env` file under each directory,
+with the following format:
+
+```env
+ENV_VARIABLE_NAME1=value1
+ENV_VARIABLE_NAME2=value2
+```
+
+## Backend
+
+The following environment variables are available:
+
+| Name                | Default Value                          | Description                                                                                          |
+| ------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `ADMIN_JWT_SECRET`  | _none_                                 | **REQUIRED**. The JWT secret for the admin panel authentication                                      |
+| `JWT_SECRET`        | `357b676e-c5f4-44a1-8446-348e0ff0b25d` | **RECOMMENDED**. The JWT secret for site authentication. If not changed, poses a high security risk. |
+| `HOST`              | `0.0.0.0`                              | Where the app will listen                                                                            |
+| `PORT`              | `3337`                                 | Port where the app will listen                                                                       |
+| `EUPAGO_TOKEN`      | `demo-f9ee-b006-8de5-8e8`              | Token for the EuPago payment provider                                                                |
+| `FRONTEND_URL`      | `http://localhost:3000`                | URL of the frontend. Used for links in emails                                                        |
+| `PREVIEW_SECRET`    | _none_                                 | Must be the same as `PREVIEW_SECRET` on frontend. Used to enable CMS preview mode for a user         |
+| `DATABASE_HOST`     | `127.0.0.1`                            | Host of the MongoDB database                                                                         |
+| `DATABASE_PORT`     | `27017`                                | Port of the MongoDB database                                                                         |
+| `DATABASE_NAME`     | `backend`                              | Name of the MongoDB database                                                                         |
+| `DATABASE_USERNAME` | _none_                                 | Username for the MongoDB database                                                                    |
+| `DATABASE_PASSWORD` | _none_                                 | Password for the MongoDB database                                                                    |
+| `DATABASE_AUTH`     | _none_                                 | Authentication database for the MongoDB database                                                     |
+| `DATABASE_SSL`      | _none_                                 | (boolean) whether or not to force SSL for connecting with the MongoDB database                       |
+| `SMTP_HOST`         | `localhost`                            | Host of the SMTP mail server                                                                         |
+| `SMTP_PORT`         | `25`                                   | Port of the SMTP mail server                                                                         |
+| `SMTP_USERNAME`     | _none_                                 | Username for the SMTP mail server                                                                    |
+| `SMTP_PASSWORD`     | _none_                                 | Password for the SMTP mail server                                                                    |
+| `MEILI_HOST`        | `http://127.0.0.1:7700`                | URL of the Meilisearch instance                                                                      |
+| `MEILI_API_KEY`     | _none_                                 | The API key to interact with Meilisearch                                                             |
+
+JWT secrets should be random strings, ideally more than 64 chars in length.
+
+## Frontend
+
+The following environment variables are available:
+
+| Name             | Default Value           | Description                                                                                 |
+| ---------------- | ----------------------- | ------------------------------------------------------------------------------------------- |
+| `API_URL`        | `http://localhost:3337` | The URL of the backend. Used for server side rendering                                      |
+| `GA_ID`          | _none_                  | The property ID for Google Analytics                                                        |
+| `TAWKTO_ID`      | _none_                  | The property ID for tawk.to live chat                                                       |
+| `PREVIEW_SECRET` | _none_                  | Must be the same as `PREVIEW_SECRET` on backend. Used to enable CMS preview mode for a user |
+
+## Meilisearch
+
+The env file should be `meili.env` and **NOT** `.env`.
+There is a `meili.sample.env` with sensible defaults.
+
+The following environment variables are available:
+
+| Name                 | Default Value | Description                                  |
+| -------------------- | ------------- | -------------------------------------------- |
+| `MEILI_ENV`          | `production`  | Set to `development` to enable the web UI    |
+| `MEILI_MASTER_KEY`   | _none_        | The master key for this Meilisearch instance |
+| `MEILI_NO_ANALYTICS` | `true`        | Whether to disable telemetry                 |
diff --git a/docs/03-running.md b/docs/03-running.md
@@ -0,0 +1,25 @@
+# Running the website
+
+The `package.json` on the top-level folder has a bunch of useful scripts
+for quick development.
+
+Start by installing all the dependencies using
+
+```sh
+yarn && yarn setup
+```
+
+Then, to start the development servers for both the frontend and the backend, run
+
+```sh
+yarn dev
+```
+
+By default, the backend is available on http://localhost:3337 and the frontend
+on http://localhost:3000.
+
+Meilisearch can be started using `docker-compose` in the `meilisearch` folder:
+
+```sh
+sudo docker-compose up -d
+```
diff --git a/docs/04-bootstrap.md b/docs/04-bootstrap.md
@@ -0,0 +1,66 @@
+# Bootstraping
+
+The app does not do any kind of setup when it is turned on for the first time (yet!).
+Therefore, the frontend won't be able to get any data from the backend.
+
+This requires the following actions to be performed on the first run.
+
+## Setting Up Permissions
+
+Permissions need to be setup to allow access to certain endpoints.
+
+Go to **Settings -> Users & Permissions Plugin -> Roles**.
+
+For the **Public** role, add the following permissions for each section:
+
+- Application plugin
+  - Category: `count`, `find`, `findone`
+  - Global-Discounts: `find`
+  - Home-Page: `find`
+  - IPN: `eupago`
+  - Newsroom: `find`
+  - Privacy-Policy: `find`
+  - Product: `count`, `findone`, `findoneslug`, `searchenhanced`
+  - Product-Highlights: `find`, `findone`
+  - Store-Config: `find`
+  - Terms-Of-Service: `find`
+- Users-Permissions plugin
+  - Auth: `callback`, `connect`, `emailconfirmation`, `forgotpassword`, `register`,
+    `resetpassword`
+  - User: `me`
+
+For the **Authenticated** role, add the following permissions for each section:
+
+- Application plugin
+  - Category: `count`, `find`, `findone`
+  - Global-Discounts: `find`
+  - Home-Page: `find`
+  - Newsroom: `find`
+  - Order: `calculateshipping`, `count`, `create`, `findone`, `findown`
+  - Privacy-Policy: `find`
+  - Product: `count`, `findone`, `findoneslug`, `searchenhanced`
+  - Product-Highlights: `find`, `findone`
+  - Store-Config: `find`
+  - Terms-Of-Service: `find`
+- Users-Permissions plugin
+  - Auth: `connect`
+  - User: `me`
+
+## Instanciating Single-Types
+
+Single-Types are empty by default, which means they return `null` and/or `undefined`
+on some situations.
+
+This can be avoided by saving each Single Type at least once, even with default
+values.
+
+## Other
+
+A category named `Livraria` must be created, otherwise book imported from POS
+system will not have a category.
+
+## Setting up Meilisearch
+
+An `products` index must be created.
+
+// TODO
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,3 @@
+# LPE Website Documentation
+
+1. [System Requirements](./re)
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# LPE Website Documentation

		1. [System Requirements](./re)