Developer Quickstart

The console commands below assume you are developing on a Debian-based Linux system and were tested with Ubuntu 22.04.1; modify to suit your particular setup.

Install base requirements

To run this code, you will need:

• git (source code upload/download)
• Node.js (code runtime; we suggest the latest runtime supported by AWS lambda; as of 13/09/22 v16)
• MySQL (database instance)

sudo apt -y install curl
curl -sL https://deb.nodesource.com/setup_16.x | sudo bash -
sudo apt update
sudo apt -y install git nodejs mysql-server

Clone the repo and install dependencies

git clone https://github.com/agolden/cck-volunteer-web-app
cd cck-volunteer-web-app
npm install

Browser

We suggest installing and using Chromium as your principal browser for development purposes.

sudo apt install -y chromium-browser

IDE

We suggest installing and using Visual Studio Code as your integrated development environment (IDE).

Development environment setup

Environment variables

To successfully run this application, you must set several environment variables.

The .env.local file must be present in the root of the directory. You can use the example environment variables file as a starting point:

cp example.env.local .env.local
ln -s .env.local .env

In this file, there are several default variables that may be changed (and several others that may be added):

• DB_HOST - (required❗) - The database instance's fully qualified domain name
• DB_MASTER_USER - (required❗) - The database master user (required for db user creation)
• DB_MASTER_PASSWORD - (required❗) - The database master user's password
• DB_NAME - (required❗) - The name of the application's database
• DB_PIPELINE_USER - (required❗) - The database pipeline user (required for schema migrations)
• DB_PIPELINE_PASSWORD - (required❗) - The database pipeline user's password
• DB_USER - (required❗) - The application's database username
• DB_PASSWORD - (required❗) - The application's database password
• JWT_SS - (required❗) - The secret used in generating / validating JSON web tokens (for authentication/authorization purposes)
• DEBUG - Enables debugging functionality, e.g., logging one time passwords to console
• NO_DB_SSL - Disables SSL connections to the database. Should likely only be set to 'true' when connecting to localhost.

Helper scripts

A series of (optional) scripts are provided that will simplify the process of setting up your local development environment. Execute them in the following sequence:

A script has been provided to randomly generate passwords for your .env.local file:

./scripts/generate-passwords.sh

A script has been provided to update the database's root user's password from the .env.local file:

sudo ./scripts/update-master-db-password.sh

A script has been provided to create the application's database and database user:

./scripts/create-db.sh

Application scripts

The package.json defines a number of scripts for use in development:

• dev - Runs the development environment locally on port 3000
• build - Builds the code for deployment. All code must successfully build or else it cannot be deployed.
• lint - Helps keep your code nice and tidy! All code must pass lint or it cannot be deployed.
• test - Runs unit tests. The pipeline will ultimately reject anything that doesn't pass tests.
• update-schema - After changes are made to the schema.prisma file - or when first configuring your environment, this script should be run to deploy the schema to the database.
• seed-db - Seeds database with basic cck data (i.e., organization, event types, etc.)

Run the scripts as follows:

npm run <<script>>

For example:

npm run update-schema

Database management

Stack management

The AWS cloudformation stack can be created / updated / deleted using the AWS CLI, for example:

aws cloudformation create-stack --stack-name my-awesome-stack-name --template-body file://aws/aws-cloudformation.yml --capabilities CAPABILITY_NAMED_IAM
aws cloudformation update-stack --stack-name my-awesome-stack-name --template-body file://aws/aws-cloudformation.yml --capabilities CAPABILITY_NAMED_IAM
aws cloudformation delete-stack --stack-name my-awesome-stack-name

Once the stack has been successfully deployed, the relevant secrets can be retrieved as follows:

aws secretsmanager get-secret-value --secret-id aws-arn:aws:secretsmanager:eu-west-2:myaccountid:secret:my-credential-id

Database backup

Here is an example of backing up the contents of the MySQL server:

mysqldump -h "myawesome.database.instance.com" --all-databases --triggers --routines --events --user=admin -p > dump.sql