fix: improve README instructions for local installation (#421)

* fix: add db:migrate, db:reset and db:seed scripts

* fix: rename env.template to .env.template

* fix: move .env documentation to .env.template

* fix: improve README instructions for local installation

* fix: apply text formatting to README.md

* fix: add link to server/knexfile.js

README.md

@@ -9,111 +9,68 @@
 | [`next`](https://github.com/dhis2/app-hub/tree/next)     | staging     | https://staging.apps.dhis2.org/ | ![app-hub staging](https://github.com/dhis2/app-hub/workflows/dhis2-docker%20ci/badge.svg?branch=next)      |
 | [`master`](https://github.com/dhis2/app-hub/tree/master) | production  | https://apps.dhis2.org/         | ![app-hub production](https://github.com/dhis2/app-hub/workflows/dhis2-docker%20ci/badge.svg?branch=master) |
 
-# Setup
+# Getting started
 
-## Clone the repo
+## Docker Compose
 
-```bash
-git clone https://github.com/dhis2/app-hub.git
-```
-
-## With Docker Compose
-
--   See docs in [dhis2/docker-compose/app-hub](https://github.com/dhis2/docker-compose/blob/master/app-hub/README.md).
-
-## With Postgres
-
-### Create & seed test-database
-
-Create a database `apphub` in postgres
-
-#### Migrate/create tables
-
-```bash
-npx knex migrate:latest
-```
-
-#### Seed testdata
-
-```bash
-npx knex seed:run
-```
-
-#### Reset & recreate database
-
-```bash
-cd packages/server
-npx knex migrate:rollback && npx knex migrate:latest && npx knex seed:run
-```
-
-## Create back-end config file (optional)
-
-The back-end config file contain credentials for database, AWS S3 bucket and Auth0.
+See docs in [dhis2/docker-compose/app-hub](https://github.com/dhis2/docker-compose/blob/master/app-hub/README.md).
 
-Env vars (.env), see .env.template
+## Local Installation
 
-```bash
-
-#Set auth strategy used in backend, to use auth0 for example set this to 'jwt' and fill in the other auth0 vars
-AUTH_STRATEGY
+1. Install dependencies with `yarn install`
+2. Copy `server/.env.template` to `server/.env` (`cp server/.env.template server/.env`) and edit `server/.env`. For development, your config will
+   probably look something like:
+    ```
+    NODE_ENV=development
+    RDS_USERNAME=postgres
+    RDS_PASSWORD=postgres
+    NO_AUTH_MAPPED_USER_ID=true
+    ```
+3. Create database tables with `yarn db:migrate`.
+4. Seed the database with `yarn db:seed`
 
-#Only need to set this if no auth is used (dev/test), to map requests against a database user by its id
-#This needs to be set if AUTH_STRATEGY is not set
-NO_AUTH_MAPPED_USER_ID
+### Run
 
-#Secrets for signing jwt token
-AUTH0_SECRET
-AUTH0_M2M_SECRET
+`yarn start`
 
-#The m2m api must use the same audience as the web app, specify the audience to use here
-AUTH0_AUDIENCE
+### Reset database
 
-#Auth0 domain, usually https://{tenant}.{region}.auth0.com
-AUTH0_DOMAIN
+`yarn db:reset`
 
-#algorithm used for signing the jwt-tokens for example HS256
-AUTH0_ALG
+## Backend config file
 
-#For the S3 storage where application files will be stored, if using S3.
-AWS_REGION
-AWS_ACCESS_KEY_ID
-AWS_SECRET_ACCESS_KEY
-AWS_BUCKET_NAME
+The backend config file `server/.env` contains credentials for the database, AWS S3 bucket and Auth0.
 
-#EBS will inject these so no need to set them manually in EBS Environments, in local/other environments set these to the database to use for the app-store backend.
-RDS_HOSTNAME
-RDS_USERNAME
-RDS_PASSWORD
-RDS_DB_NAME
-```
+Available options are documented in [`.env.template`](server/.env.template).
 
-See knexfile.js to change database connections/credentials or server which will be used depending on process.env.NODE_ENV
+See [`server/knexfile.js`](server/knexfile.js) to specify which database connections/credentials or server to use depending on the value of `process.env.NODE_ENV`.
 
 ## Frontend config
 
 The frontend needs to know some basic information about the server to configure routes and API endpoints.
-This is located in `app/default.config.js`.
+This is located in [`client/default.config.js`](client/default.config.js).
 
 You can rename or copy this file to override the settings.
-Tries to load config files in the following order:
 
-1. default.config.js
-2. config.js
+Config files are loaded in the following order:
+
+1. `default.config.js`
+2. `config.js`
 
-Environment specific configurations are also supported, and are loaded if environment is set to either `development` or `production`.
+Environment specific configurations are also supported, and are loaded if `process.env.NODE_ENV` is set to either `development` or `production`.
 
--   development.config.js
--   production.config.js
+-   `development.config.js`
+-   `production.config.js`
 
 Note that the exported objects from each config file are merged with the previous, so any options not changed are kept from the previous config.
 
 _Note: If you make any changes, you will need to rebuild or restart webpack-dev-server for the changes to take effect._
 
 ### Example Development Config
 
-`development.config.js`
-
 ```javascript
+// development.config.js
+
 module.exports = {
     api: {
         baseURL: 'http://localhost:3000/api/',
@@ -146,30 +103,29 @@ api.baseURL: 'http://localhost:3000/api/',
 The URL to be used when auth0 has successfully logged in a user, and is redirected back to the page. Note that this URL needs to be whitelisted on the auth0 side aswell.
 
 ```javascript
- api.redirectURL: 'http://localhost:3000/user/'
+api.redirectURL: 'http://localhost:3000/user/'
 ```
 
 # Run the project
 
-### Start the backend and frontend
+`yarn start` will start both the frontend and backend.
 
+Frontend available at `localhost:8080`.
 Web API available at `localhost:3000/api/v1`.
 
 Swagger UI available at `localhost:3000/documentation`
 Swagger specs available at `localhost:3000/swagger.json`
 
-Frontend at `localhost:3000/`.
-
 # Clone the existing production App Hub (approved/published apps) to your own local App Hub
 
 ```bash
- yarn start
+yarn start
 ```
 
 and then in another terminal:
 
 ```bash
- yarn run clone
+yarn run clone
 ```
 
 # Release

package.json

@@ -10,6 +10,9 @@
         "tools"
     ],
     "scripts": {
+        "db:migrate": "yarn workspace server db:migrate",
+        "db:reset": "yarn workspace server db:reset",
+        "db:seed": "yarn workspace server db:seed",
         "build": "yarn workspace client build",
         "start": "concurrently -n w: \"yarn:dev:*\"",
         "dev:server": "yarn workspace server start:dev",

server/.env.template

@@ -0,0 +1,38 @@
+# Server config.
+HOST=
+PORT=
+NODE_ENV=
+
+# Database config.
+# If using AWS EBS, these environmental variables will be injected automatically
+# (i.e. no need to set them manually in EBS environments). In local/other
+# environments configure these for the postgres database to use for the app hub
+# backend.
+RDS_HOSTNAME=
+RDS_USERNAME=
+RDS_PASSWORD=
+RDS_DB_NAME=
+RDS_DB_PORT=
+
+# Authentication config.
+# Set `NO_AUTH_MAPPED_USER_ID=true` if no auth is used (such as in development).
+# `AUTH_STRATEGY` sets the auth strategy used by the backend -- to use auth0 set
+# this to 'jwt' and fill in the other `AUTH0_` vars. If not set then
+# `NO_AUTH_MAPPED_USER_ID` must be true.
+AUTH_STRATEGY=
+# `AUTH0_SECRET` and `AUTH0_M2M_SECRET` are secrets used for signing JWT tokens.
+AUTH0_SECRET=
+AUTH0_M2M_SECRET=
+# The M2M API must use the same audience as the web app, specify the audience to use here.
+AUTH0_AUDIENCE=
+# Auth0 domain, usually https://{tenant}.{region}.auth0.com
+AUTH0_DOMAIN=
+# Algorithm used for signing the jwt-tokens (e.g. HS256)
+AUTH0_ALG=
+
+# AWS S3 config (optional).
+# Specifies where application files will be stored if using S3.
+AWS_REGION=
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+AWS_BUCKET_NAME=

server/package.json

@@ -12,6 +12,7 @@
         "start:dev": "cross-env DEBUG=knex:tx,apphub* NODE_ENV=development nodemon --watch ./src --inspect src/main.js",
         "test": "cross-env NODE_ENV=test yarn db:reload && lab -a @hapi/code -v -I 'core,__core-js_shared__,k,FinalizationRegistry,WeakRef'",
         "test:coverage": "cross-env NODE_ENV=test yarn db:reload && lab -c -a @hapi/code -t 80 -r html -o coverage/coverage.html",
+        "db:migrate": "knex migrate:latest",
         "db:reset": "knex migrate:rollback && knex migrate:latest",
         "db:seed": "knex seed:run",
         "db:reload": "yarn db:reset && yarn db:seed"