GeorgiaCORE

GeorgiaCORE is a state-wide 501c3 whose mission is to promote cancer research, detect cancer earlier, and help conduct more clinical trials for cancer. They have thousands of actively-diagnosed cancer patients, survivors, doctors, and other cancer-related specialists use their website. Unfortunately, over time the website has become bloated and hard to navigate. We aim to create a solution that makes the website easier to navigate.

Resources for Developers

Feature Branches will be named with your first name followed by a short description of what you are working on ex: manu/analytics-engine-bug-fix

Stack

React.js: Front-end
Next.js: API routes and server-side rendering
MongoDB: Permanently storing info
iron-session: Authentication session handling for SSR/SSG
eslint: Automatically identifying and fixing code errors
prettier: Setting a common code style and fixing any issues. If you would like to adjust any prettier settings like quote style or include semicolons, look in .prettierrc
yarn: Package management. If you do not have yarn, run npm install -g yarn to install yarn globally.

Setup

Initializing Env Vars

If you are an EM setting up a project for the first time, read the Bitwarden guide here before continuing forward.
Run yarn secrets to sync development secrets from Bitwarden and save them to a local .env.local file. Contact a leadership member for the Bitwarden password.
- Note: If you are using Windows, enter yarn secrets:login and then yarn secrets:sync instead of the above script.

Updating Env Vars

For dev, update .env.local and next.config.js
For production, add the env vars to your host, NEVER commit .env.local to your version control system.

MongoDB

A running instance of MongoDB is required this project.

Decide if you want to run MongoDB locally or remotely
Locally (Docker (RECOMMENDED))
1. Download Docker Desktop
2. Run docker run --name mongodb -d -p 27017:27017 mongo in your terminal
3. Open Docker Desktop and confirm that your MongoDB image is running. It should exist on port 27017, and can be accessed.
Locally (Non-Docker)
1. Download MongoDB Community Server
2. Go through the installation instructions.
  - Leave the port at default 27017
Remotely
1. Create a MongoDB instance on MongoDB Atlas
2. In Security → Network Access: add the IP address 0.0.0.0/0 (all IPs)
3. In Security → Database Access: Add new database user
4. In Data Storage → Clusters: Find your cluster and click Connect → Connect your application and copy the connection string, set the username and password, and set this as MONGO_DB in .env.local
Create the nextjs database. (or choose another name, but make sure to change it in .env.local)
It's very helpful to install MongoDB Compass to see your database contents

Node

Clone this project to your computer
Navigate to this project in terminal and enter yarn
Rename example.env to .env.local and fill it out with the dev config

Running

Development

To understand this code better, read the Code Tour.

Run yarn
Run yarn dev

Production

Setup your host/vm and the necessary env vars
Run yarn install
Run yarn start

Other Info

Styling

This is dated info. We are on Next 11 now.
By default, this repository uses Next ^9.2.0 for styles, which includes native support for global CSS and CSS modules
However, this version only allows global css to be in pages/_app.js, which can cause issues with external packages
If you face this error, the solution is installing @zeit/next-css and adding it to next.config.js, however you cannot use css modules and global css together with this package (and it defaults to global).

Deployment

This repository has a Vercel CD pipeline set up in the main.yml workflow. For first time set up, run npx vercel after installing all packages. This will trigger the Vercel CLI and deploy the repository onto Vercel.

Once the repository has been deployed for the first time, three secrets must be loaded into GitHub: ORG_ID, PROJECT_ID, and VERCEL_TOKEN. The first two can be found within the project.json file within the .vercel folder, generated by the Vercel CLI. The third VERCEL_TOKEN can be found under your Vercel account on the Vercel website.

Having configured these values, this repository will generate a Vercel deployment for every PR/push into the main or production branches. Three GitHub deployment environments are used: Production (for pushes to production), Preview (for pushes to open PRs into main or production), and Development (for pushes to main).

There exists a more detailed guide regarding deployment on the Bits of Good Notion (must be a member of BoG to access).

Run With Docker

Install Docker
Obtain the Bitwarden password from your EM. Create a bitwarden.env file and fill it in with the following contents:
```
BW_PASSWORD=<your bitwarden password>
```
This only needs to be done on your first run. After that, you should delete the file from your repository to avoid pushing it to Github.
Start the application with Docker Compose: docker compose up

If you make any changes to the packages, you may need to rebuild the images. To do this, append --build to the above docker compose up command.

The Dockerized application will have live-reloading of changes made on the host machine.

Note: On linux-based operating systems, if you come across an entrypoint permission error (i.e. process: exec: "./entrypoint.sh": permission denied: unknown), run chmod +x ./entrypoint.sh to make the shell file an executable.

Windows Users: If you come across this error exec ./entrypoint.sh: no such file or directory when running the docker compose command, please follow this Stackoverflow thread to fix it.

GTBitsOfGood / georgiaCORE