add documentation

docs/auth0.md

@@ -0,0 +1,51 @@
+# AUTH0 Setup
+The web app uses auth0 in order to handle the user authentication. In order to create the web app it is necessary to create an auth0 account or to use an existing one (https://auth0.com/). 
+Login to auth0, go to your dashboard, create an application and configure it for the vue.js use following the guide in the quick start section.You just have to create an application and an api giving them names.
+Inside the populate `auth0-config.js` and `.env` with the following data:
+- `domain`: The domain used by the created application (can be found in the settings section of the app)
+- `clientId`: The client ID used by the created application (can be found in the settings section of the app)
+- `audience`: The api identifier found in the api section.
+- `client_secret`: The client_secret of the app (can be found in the api settings inside the auth0 application)
+- `grant_type`: "client_credentials",
+- `client_id_api`: The api id of the application (can be found in the api settings inside Auth0)
+- `app_url`: The application's url (it's the same as the domain but with the addition of "https://")
+
+
+Add the next urls to the callback urls inside the application in auth0: http://localhost:8080/callback, http://localhost:8080/myTiles. Add http://localhost:8080 in the callback, logout, weborigins, allowed origins fields in the settings of the application on Auth0. Check the guidelines of Auth0 if you want to change them.
+
+**NOTE**: if you are deploying on a custom domain, replace `http://localhost:8000` with your actual domain.
+
+In the Dashboard of the application linked to Auth0 you'll have to add a custom action called `storeFirstNickName` that needs to be called during the login. This action will create a field called `signUpName` inside the user data so that it is associated to the user in the gamification engine. The code for the custom action in the dashboard is this:
+```js
+exports.onExecutePostLogin = async (event, api) => { 
+  if (event.user.user_metadata.signUpName!=null) { 
+    console.log(Skipping the expensive task because it already occurred for ${event.user.email}.); 
+    return; 
+  } // do and expensive task 
+  api.user.setUserMetadata("signUpName", event.user.nickname); 
+};
+```
+
+Then you have to add a second action called `saveUserSignUpName` with code:
+```js
+exports.onExecutePreUserRegistration = async (event, api) => { 
+  //console.log(event.user)
+  api.user.setAppMetadata("signUpName", event.user.nickname)
+  console.log(api.user); 
+};
+```
+Then you have to add a rule that lets auth0 get the metadata `signUpName` every time you want to get the user info. This rule has the code:
+```js
+function (user, context, callback) {
+  const namespace = 'myUserID'; 
+  user.user_metadata = user.user_metadata || {}; 
+  user.user_metadata.signUpName = user.user_metadata.signUpName || null; 
+  context.idToken[${namespace}signUpName] = user.user_metadata.signUpName; 
+  callback(null, user, context);
+}
+```
+
+Inside the section `Actions/flow` inside auth0 you can go to login and add the rule and the action `storeFirstNickName` created.
+Insite the section `Actions/flow/PreuserRegistration` add the action `saveUserSignUpName`.
+
+If you'd like to activate the email verification you can just go in the `authGuard.js` file and remove the comment from line 9 to 28.

docs/deploy.md

@@ -0,0 +1,140 @@
+# Deploy
+Deployment is requires `docker compose`, the official images can be found on [Github](https://github.com/orgs/DigitalCommonsLab/packages?repo_name=bikingimprover).
+
+## Directory structure
+For a production deployment the following structure is advised:
+```bash
+.
+├── docker-compose.yml
+├── .env
+├── gamification.env
+└── volumes
+    ├── auth0-conf.js
+    ├── data
+    │   └── [YOUR_CITY_NAME].xml
+    ├── databases
+    ├── engine-config
+    │   └── users.yml
+    ├── engine-logs
+    ├── letsencrypt
+    │   └── acme.json
+    ├── mongo-data
+    └── pbfFiles
+```
+
+The following `docker-compose.yml` could be used as template:
+```yml
+version: "3.9"
+
+services:
+  mongo:
+    image: mongo:3.6.2-jessie
+    volumes:
+      - ./volumes/mongo-data:/data/db
+
+  gamification-engine:
+    image: ghcr.io/digitalcommonslab/gamification-engine:docker
+    depends_on:
+      - mongo
+    links:
+      - mongo:mongodb
+    env_file: 
+      - ./gamification.env
+    volumes:
+      - ./volumes/engine-logs:/app/game-engine.web/logs
+      - ./volumes/engine-config:/app/config
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.gamification-engine.rule=Host(`gamification.bikingimprover.example.com`)"
+      - "traefik.http.routers.gamification-engine.entrypoints=websecure"
+      - "traefik.http.routers.gamification-engine.tls.certresolver=myresolver"
+      - "traefik.http.services.gamification-engine.loadbalancer.server.port=8010"
+
+  setup-gamification-engine:
+    image: ghcr.io/digitalcommonslab/gamification-engine-setup:docker
+    depends_on:
+      - gamification-engine
+    env_file: 
+      - ./.env
+    profiles:
+      - setup
+
+  web:
+    image: ghcr.io/digitalcommonslab/bikingimprover:docker
+    command: node server.js
+    env_file:
+      - ./.env
+    volumes:
+      - ./volumes/auth0-conf.js:/app/dist/auth0-conf.js
+      - ./volumes/databases:/app/databases
+      - ./volumes/pbfFiles:/app/pbfFiles
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.web.rule=Host(`bikingimprover.example.com`)"
+      - "traefik.http.routers.web.entrypoints=websecure"
+      - "traefik.http.routers.web.tls.certresolver=myresolver"
+      - "traefik.http.services.web.loadbalancer.server.port=8080"
+
+  setup_web:
+    profiles:
+      - setup
+    command: /data/[YOUR_CITY_NAME].xml
+    image: ghcr.io/digitalcommonslab/bikingimprover-setup:docker
+    env_file:
+      - ./.env
+    volumes:
+      - ./volumes/data:/data
+      - ./volumes/pbfFiles:/app/out/pbfFiles
+      - ./volumes/databases:/app/out/databases
+
+  traefik:
+    image: "traefik:v2.9"
+    container_name: "traefik"
+    command:
+      - "--api.insecure=true"
+      - "--providers.docker=true"
+      - "--providers.docker.exposedbydefault=false"
+      - "--entrypoints.web.address=:80"
+      - "--entrypoints.websecure.address=:443"
+      - "--certificatesresolvers.myresolver.acme.httpchallenge=true"
+      - "--certificatesresolvers.myresolver.acme.httpchallenge.entrypoint=web"
+      - "--certificatesresolvers.myresolver.acme.email=[YOUR_EMAIL_ADDRESS]"
+      - "--certificatesresolvers.myresolver.acme.storage=/letsencrypt/acme.json"
+    ports:
+      - "80:80"
+      - "443:443"
+      - "8080:8080"
+    volumes:
+      - "./volumes/letsencrypt:/letsencrypt"
+      - "/var/run/docker.sock:/var/run/docker.sock:ro"
+```
+
+You can use as template to copy and customize the example files in the repository: `example.env`, `gamification.env` and `auth0-conf.example.js`.
+
+## Loading Data and configuration
+In order to populate the database with initial data and spatial datasets, you need to upload an openstreetmap XML export of a city inside the `volumes/data` folder. You should name it with the city name.
+
+Inside `volumes/engine-config` put `users.yml` (you can get a copy from `docker/engine/config/users.yml`).
+
+## Setup Phase
+A first step is required to setup the system:
+```bash
+docker compose --profile setup pull
+docker compose --profile setup up -d
+```
+Using the profile `setup` two more containers will be deployed:
+- `setup-gamification-engine` will setup the gamification engine, check its log to get the `ID_GAME_ENGINE`, you have to put this value inside `.env`.
+- `setup-web` will setup the app database and will create the `pbfFiles` needed by the application.
+
+When both the containers ends processing - you can check using `docker compose --profile setup logs -f setup-web` - you can stop the process with `docker compose --profile setup stop`.
+
+## Auth0 Setup
+Refer to documentation specific to [auth0](./auth0.md)
+
+## Execution Phase
+Run the following command:
+```bash
+docker compose up -d
+```
+
+**NOTE**: Always use this command after first initialization