Angels Among Us

Overview

Angels Among Us's mission is to save animals from shelters and owner surrenders. The purpose of this tool is to decouple the placement process of foster animals from the nonprofit's current platform, allowing quicker and improved matching of fosters to volunteers.

Repo Walkthrough

Visit this Notion page.

Setup

Using Docker (recommended)

For those that use WSL on Windows, there are known bugs that can prevent the web app from connecting to your Mongo database. It is strongly encouraged that you set up the repository using Docker.

1. Download MongoDB Compass to view your database documents in a GUI.

2. Obtain the Bitwarden password from your EM. Create a file named .env.local in the root directory of the respository and fill it using the the following commands (or ask your EM). You will need Bitwarden CLI installed for this:

   bw login product@bitsofgood.org
   bw get item 78839bf2-878b-4d5d-9129-af9300699ddf | npx fx .notes > .env.local

3. Boot up the Docker containers:

   docker-compose up -d

   This may take a while on your first build. It is also expected that the web image takes a bit to start up as it depends on a healthy database with proper replica sets.

   To stop your Docker containers and remove their processes, run:

   docker-compose down

   You can see currently running containers with docker ps -a.

4. Once everything has spun up successfully, connect to your database on MongoDB compass with the connection URL:

   mongodb://localhost:30001/?directConnection=true

   Keep in mind that our Docker instance of MongoDB runs on a different port (30001) to prevent collisions with a local instance of MongoDB, if you have that installed (which runs on 27017 by default).

5. Add a document to the accounts collection, with email and role fields like this:

    {
      _id: ...,
      email: "YOUR_EMAIL_HERE",
      lowerEmail: "YOUR_EMAIL_HERE",
      role: "admin"
    }

   The value of the email field should be the email address you will be logging in with via gmail. You have now added yourself as a valid account with an admin role. The value of lowerEmail should be your email but all lowercase.

6. Navigate to localhost:3000 using your web browser. Click "Sign in with Google" and log into using the email you used to make the account document.

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: "./scripts/env-init.sh": permission denied: unknown or process: exec: "./scripts/rs-init.sh": permission denied: unknown), run chmod +x ./scripts/rs-init.sh or chmod +x ./web/scripts/env-init.sh to make the shell files executables.

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

Manual setup

1. Install MongoDB Community Server to host a local instance of MongoDB. Download MongoDB Compass to view the state of your database using a GUI.

2. Run yarn in the root directory of the repository. If you get an error specifying that the command is not found, install yarn:

   npm install --global yarn

   then attempt yarn again.

   Run the following commands.

   cd web
   yarn

   You have now installed all the dependencies required to run the project.

3. Acquire the .env file by navigating to the web directory and running the following based on your OS:

   yarn secrets:linux # MacOS/Linux
   yarn secrets:windows # Windows

   You will need to obtain a password from your engineering leadership to complete this process.

4. Connect to your MongoDB database using MongoDB compass. Use the connection URL:

   mongodb://localhost:27017/

   Create a document within the accounts collection with the fields:

    {
      _id: ...,
      email: "YOUR_EMAIL_HERE",
      role: "admin"
    }

   The value of the email field should be the email address you will be logging in with via gmail. You have now added yourself as a valid account with an admin role.

5. Configure MongoDB session transactions using this Notion doc.

6. Start the Next.js development server by running:

   yarn dev

   in the web directory.

7. Navigate to localhost:3000 using your web browser. Click "Sign in with Google" and log into using the email you used to make the account document.

Testing

We use jest for testing. See the web/__tests__ directory for our unit and integration tests. Currently, our tests are mostly limited to testing backend functionality.

To run all test suites, navigate to the web directory and run yarn jest. To generate a coverage report, run:

yarn jest --coverage --collectCoverageFrom='./**/*.{ts,tsx}'

Code Formatting

Install and enable Prettier in VSCode. This repository is also configured with a pre-commit hook that automatically formats any code you commit to ensure formatting consistency throughout the codebase.