Skip to content

Latest commit

 

History

History
225 lines (154 loc) · 7.79 KB

README.md

File metadata and controls

225 lines (154 loc) · 7.79 KB
Raw

BOM-node-server

Dependancy Version Note
Node 8.x (LTS)
npm 6.x Observe Node Releases
MySQL 5.7 Primary DataStore
Redis - Session Store (Coming Soon)

Configuration & Setup

Local (Dev) Install Steps

  1. If you don't have mysql installed already be sure to follow the steps below Localhost MYSQL

  2. Create an AWS-S3 bucket & IAM Role as outlined below

  3. Setup dot env file: cp .env.sample .env.local and populate .env.local with your environment's configuration options.

  4. Run NODE_ENV=local npm install to install all dependencies (optional & development)

Environment Variables

  • NODE_ENV: (required) Which node environment are you using (currently: development, acceptance, production, test or local). Values local and test have the following special conditions:
    • test are for running [mocha] tests
    • local adds optional & dev dependancies through postinstall.sh. Requires .env.local to be setup before install
  • PORT: (optional): Which port the server should listen to. Defaults: 3000
  • VCAP_SERVICES: (required for production) Used for PCF deployment which should be an encoded JSON. Refer to their documentation/configuration
  • DB_*: (required if VCAP_SERVICES is not set): MySQL Database settings
    • DB_USER: Username
    • DB_PASS: Password
    • DB_HOST: Host
    • DB_NAME: Database Name (steps below suggest myAppDb)
    • DB_PORT: Database Port DB_PORT=3306 (defaults to 3306)
  • AWS_S3_* AWS S3 Configuration
    • AWS_S3_BUCKET: S3 Bucket Name
    • AWS_S3_SDK_KEY: Key of the API Key-Pair
    • AWS_S3_SDK_SECRET: Secret of the API Key-Pair
    • AWS_S3_REGION: AWS Region (defaults to us-east-1)
  • SESSION_SECRET: Session Salt
  • REQUEST_LOGGING_*: Logging details into the pino logger
    • REQUEST_LOGGING: Enables the HTTP Request logging. This value aliases to a boolean env-1. Defaults to false
    • REQUEST_LOGGING_SESSION: Request logging will include Session Data. This value aliases to a boolean env-1, env-2 Defaults to false
    • REQUEST_LOGGING_COOKIE: Request logging will include Cookie strings. This value aliases to a boolean env-1, env-2 Defaults to false
    • REQUEST_LOGGER_ASSETS: Request logging will include static file asset Data. This value aliases to a boolean env-1, env-2 Defaults to false
    • REQUEST_LOGGING_MASK: Request logging will mask object content with descriptor strings. This value aliases to a boolean env-1. Defaults to true
  • DEBUG_SQL: Enables the Sequelize debugging of raw queries. This value aliases to a boolean env-1. Defaults to false
  • VERBOSE: Enables extra logging including. This value aliases to a boolean env-1 or string all. Defaults to false
  • FRONTEND_URL: Configure for CORS Ajax requests; can be comma separated but ignores PORT from origin
  • SKIPPOSTINSTALL: is exclusively used for postinstall.sh to avoid install recursion

Localhost MYSQL

Install

Install MYSQL via OSX Brew: brew install [email protected] or otherwise use your favourite binary or package installer.

Default Database Configuration

For convenience its recommended you setup a username, password and database as follows.

  1. Login into MYSQL shell using your root credentials mysql -u root -p and you will be prompted for your MYSQL root password.

  2. Create the Database CREATE DATABASE myAppDb;

  3. Specify the new user CREATE USER 'myAppUser'@'localhost' IDENTIFIED BY 'somethingSecret555111222';

  4. Add permissions (Choose One):

  • to all databases GRANT ALL PRIVILEGES ON * . * TO 'myAppUser'@'localhost';

  • OR

  • to specific databases with our default name GRANT ALL PRIVILEGES ON myAppDb . * TO 'myAppUser'@'localhost';

  1. Flush Permissions FLUSH PRIVILEGES;

  2. Exit MYSQL Terminal quit

Debugging Queries

In app setup we configure each connection to change a SQL Variable. Use the following in you SQL manager's raw query terminal:

SET SESSION sql_mode=(SELECT REPLACE(@@sql_mode,'ONLY_FULL_GROUP_BY',''));

# YOUR DEBUG SQL GOES AFTER THIS LINE

AWS S3 Storage

Create an IAM Role with the following settings

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "1",
            "Effect": "Allow",
            "Action": [
                "s3:CreateBucket",
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Resource": "arn:aws:s3:::*"
        },
        {
            "Sid": "2",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:DeleteObject"
            ],
            "Resource": "arn:aws:s3:::*/*"
        }
    ]
}

You can test your test IAM permissions. Additionally you can change the portion(s) "Resource": "arn:aws:s3:::*" can be arn:aws:s3:::<BUCKETNAME> if you don't want to give open access to your IAM role; however the given example is required to is postinstall.js to automatically create the bucket for you.

Scripts

Use npx <script> or npm run <script> and replace '<script>' with any of the below

  • build Trigger babel to compile code into dist/ directory

  • start Start the Application using the compiled babel code (set NODE_ENV environment variable); npm run build needs to be ran first

  • dev:*

    • dev Start the application with nodemon with NODE_ENV set to 'local'

    • dev:debug Same as above with attached debugger

  • postinstall Runs automatically after npm install but calls postinstall.sh which eventually calls postinstall.jsdb-1.

  • teardown Executes uninstall.sh which removes node dependancies, caches, builds and data storesdb-1.

  • docs Generate documentation

  • lint:*

    • lint Runs npm run lint

    • lint:prod Runs above but will error if any warnings are triggered

  • db:*

    • db:migrate Run sequelize migrations

    • db:setup:fixture Run sequelize seed data sets for local development

    • db:seed Run sequelize Seeds but path to the seed needs to be passed npm run db:seed -- --seed path/to/seed.js

    • db:drop Run sequelize undo all; run all 'down' steps for migrations & seeds`

    • db:sync (Coming Soon) Sync files with Data-Stores/Caches

    • db:sync:s3 (Coming Soon) Sync MySQL records with S3 Store

  • test:*

    • test Run Mocha test with NODE_ENV set to 'test'

    • test:debug Same as base 'test' (above) with attached debugger

    • test:watch Same as base 'test' (above) with 'watch mode' to refresh after files change

    • test:coverage Same as base 'test' (above) with a coverage report

  • coverage Same as npm run test:coverage with coverage report opened in your default browser

Project Structure

  • _cache/ For temporary files such as uploaded files and local store of served S3 files

  • dist/ build directory after compiling babel

  • dev/ SQL migrations, seeds and other assets such as place holder images

  • jsdocs/ JSDOCs documentation

  • src/ Application codebase

  • tests/ Mocha-Unit-Tests

  • coverage/ Istanbul coverage report files (html)

Footnotes

env-1 This environment variable takes values as boolean.

  • Boolean value of true aliases as true, yes or 1.
  • Boolean value of false aliases as false, no or 0.

env-2 Becomes equivalent to true when VERBOSE is set to all.

db-1 Set NODE_ENV but will default to 'local' if not set