From f7492c51769ded084a0b123d8cc860baa9a63c5d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A9di-R=C3=A9mi=20Hashim?= <4295266+mediremi@users.noreply.github.com> Date: Mon, 18 Jan 2021 13:55:54 +0000 Subject: [PATCH] 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 | 120 ++++++++++++++----------------------------- package.json | 3 ++ server/.env.template | 38 ++++++++++++++ server/env.template | 24 --------- server/package.json | 1 + 5 files changed, 80 insertions(+), 106 deletions(-) create mode 100644 server/.env.template delete mode 100644 server/env.template diff --git a/README.md b/README.md index 72d7230d9..c019da6bb 100644 --- a/README.md +++ b/README.md @@ -9,101 +9,58 @@ | [`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. @@ -111,9 +68,9 @@ _Note: If you make any changes, you will need to rebuild or restart webpack-dev- ### 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 diff --git a/package.json b/package.json index 5caa66080..c4571c06f 100644 --- a/package.json +++ b/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", diff --git a/server/.env.template b/server/.env.template new file mode 100644 index 000000000..f3fd7ce03 --- /dev/null +++ b/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= diff --git a/server/env.template b/server/env.template deleted file mode 100644 index c538d2b08..000000000 --- a/server/env.template +++ /dev/null @@ -1,24 +0,0 @@ -# server -HOST= -PORT= - -# authentication -AUTH_STRATEGY= -AUTH0_SECRET= -AUTH0_M2M_SECRET= -AUTH0_AUDIENCE= -AUTH0_DOMAIN= -AUTH0_ALG= - -# aws -AWS_REGION= -AWS_ACCESS_KEY_ID= -AWS_SECRET_ACCESS_KEY= -AWS_BUCKET_NAME= - -# database -RDS_HOSTNAME= -RDS_USERNAME= -RDS_PASSWORD= -RDS_DB_NAME= -RDS_DB_PORT= \ No newline at end of file diff --git a/server/package.json b/server/package.json index a4e6c45b7..21bd6cd32 100644 --- a/server/package.json +++ b/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"