Skip to content

Latest commit

 

History

History
278 lines (187 loc) · 12 KB

README.md

File metadata and controls

278 lines (187 loc) · 12 KB
Raw

Bloom by Chayn

Bloom Backend CI Pipeline

Bloom is a remote trauma support service from Chayn, a global, award-winning charity designing open-source tools to support the healing of survivors across the world. Since 2013, Chayn has reached over 500,000 survivors worldwide with our trauma-informed, survivor-centred, and intersectional approaches in utilizing tech for social impact. Bloom is our flagship product; a free, web-based, secure support service designed to aid in the healing of survivors. Through a combination of online video-based courses, anonymous interaction, and 1:1 chat, Bloom provides tailored information, self-help guidance, everyday tools, and comfort to cope with traumatic events.

Explore Chayn's website, research, resources, projects, impact, and support services directory. 💖

Support Our Work

Chayn is proudly open-source and built with volunteer contributions. We are grateful for the generosity of the open-source community and aim to provide a fulfilling experience for open-source developers.

Please give this repository a star ⭐ and follow our GitHub profile 🙏 to help us grow our open-source community and find more contributors like you!

Support our mission further by sponsoring us on GitHub, exploring our volunteer programs, and following Chayn on social media: - Linktree: https://linktr.ee/chayn - Twitter: @chaynhq - Instagram: @chaynhq - Youtube: @chaynhq - Facebook: @chayn - LinkedIn: @chayn.

Bloom Backend Contribution Docs:

By making an open-source contribution to Chayn, you have agreed to our Code of Conduct.

Happy coding! ⭐

Technologies Used:

Visit the /docs directory for an overview of Bloom's backend architecture and key concepts.

  • NestJS - NodeJs framework for building scalable and reliable server-side applications
  • PostgreSQL - Object-relational SQL database system
  • TypeORM - Object Relational Mapper library
  • Firebase - User authentication
  • Storyblok - Headless CMS for pages and courses content
  • Simplybook - Appointment booking system used for therapy
  • Slack - Slack webhooks to send messages to the team
  • Rollbar - Error reporting
  • Crisp - User messaging
  • Mailchimp - Transactional email
  • Docker - Containers for api and db
  • Heroku - Build, deploy and operate staging and production apps
  • GitHub Actions - CI pipeline
  • ESLint and Prettier for linting and formatting.

Local development

Summary

To run Bloom's backend: install prerequisites, configure environment variables, install dependencies, then run in a Dev Container, with Docker, or manually.

Most contributions (and running Cypress integration tests from the frontend) require populating your local database with test data.

Prerequisites

Configure Environment Variables

Create a new .env file and fill it with the required environment variables:

# Variables for building and running tests.
# Provided variables are read-only and subject to change.
#===============================================================
# REQUIRED VARIABLES FOR LOCAL DEVELOPMENT
#---------------------------------------------------------------
# CORE ENVIRONMENT VARIABLES
PORT=35001
DATABASE_URL=postgres://<username>:<password>@<host>:<port>/<db>
NODE_ENV=development

# FIREBASE AUTH AND ANALYTICS
FIREBASE_TYPE=service_account
FIREBASE_PROJECT_ID=
FIREBASE_PRIVATE_KEY_ID=
FIREBASE_PRIVATE_KEY=
FIREBASE_CLIENT_EMAIL=
FIREBASE_CLIENT_ID=
FIREBASE_AUTH_URI=https://accounts.google.com/o/oauth2/auth
FIREBASE_TOKEN_URI=https://oauth2.googleapis.com/token
FIREBASE_CERT_URL=https://www.googleapis.com/oauth2/v1/certs
FIREBASE_CLIENT_CERT=
FIREBASE_API_KEY=
FIREBASE_AUTH_DOMAIN=
FIREBASE_PROJECT_ID=
FIREBASE_STORAGE_BUCKET=
FIREBASE_MESSAGING_SENDER_ID=
FIREBASE_API_ID=
FIREBASE_MEASUREMENT_ID=

# REQUIRED VARIABLES FOR TESTING
#---------------------------------------------------------------
# MOCK VALUES (can replace with real values or new mocks in same format)
SIMPLYBOOK_CREDENTIALS='{"login":"testlogin","password":"testpassword","company":"testcompany"}'
SIMPLYBOOK_COMPANY_NAME=testcompany

# OPTIONAL VARIABLES
#---------------------------------------------------------------
ROLLBAR_ENV=development # Rollbar logging
ROLLBAR_TOKEN= # Rollbar logging
ZAPIER_TOKEN= # Zapier automation
SLACK_WEBHOOK_URL= # Slack messaging bots
CRISP_TOKEN= # Crisp chat
MAILCHIMP_API_KEY= # Email messaging
RESPOND_IO_CREATE_CONTACT_WEBHOOK= # RESPOND.IO
RESPOND_IO_DELETE_CONTACT_WEBHOOK= # RESPOND.IO

How to Configure Firebase Variables:

Bloom's required Firebase variables are obtained by creating a Firebase project, then generating a private key file in JSON format. First, create a Firebase project in the Firebase console here (Google account required). Next, follow these directions to generate your private key file.

Install dependencies with yarn

yarn

Run in Docker - Recommended

Bloom's backend is containerized and can be run solely in Docker - both the PostgreSQL database and NestJS app. To run the backend locally, make sure your system has Docker installed - you may need Docker Desktop if using a Mac or Windows.

First, make sure the Docker app is running (just open the app). Then run

docker-compose up

You should see this in the shell output:

Listening on localhost:35001, CTRL+C to stop

Note: you can use an application like Postman to test the apis locally

Run in Dev Container - Recommended for Visual Studio Users

This method will automatically install all dependencies, IDE settings, and postgres container in a Dev Container (Docker container) within Visual Studio Code.

Directions for running a dev container:

  1. Meet the system requirements
  2. Follow the installation instructions
  3. Check the installation
  4. After you've verified that the extension is installed and working, click on the "Remote Status" bar icon and select "Reopen in Container". From here, the option to "Re-open in Container" should pop up in notifications whenever opening this project in VS.
  5. Configure your environment variables and develop as you normally would.

The dev Container is configured in the .devcontainer directory:

  • docker-compose.yml file in this directory extends the docker-compose.yml in the root directory.
  • devcontainer.json configures the integrations with Visual Studio Code, such as the IDE extensions and settings in the vscode directory.

See Visual Studio Code Docs: Developing Inside a Dev Container for more info.

Run Manually

Manage postgres locally to populate the database, then run:

yarn start:dev

You should see this in the shell output:

Listening on localhost:35001, CTRL+C to stop

Unit Testing

To run all unit tests

yarn test

To have your unit tests running in the background as you change code:

yarn test:watch

Format and Linting

Linting and formatting are provided by ESLint and Prettier. We recommend VSCode users to utilize the workspace settings in .vscode/settings.json and install the extensions in .vscode/extensions for automated consistency.

We strongly recommend maintaining consistent code style by linting and formatting before every commit:

To run linting

yarn lint

To lint and fix

yarn lint:fix

Run format and fix:

yarn format

Populate Database

Most open-source contributions (like running Cypress integration tests from the frontend) require adding test data to your local database. To do this, navigate to our Chayn Tech Wiki Guide to obtain a backup file and follow directions there to populate your local database.

Chayn staff with access to Heroku, you also have the option to seed the database via the following script. Before you start, make sure:

  1. bloom-local-db container is running in Docker

  2. you are logged into the Heroku via your terminal. Read more about the Heroku Cli here

  3. Replace <HEROKU_APP_NAME> with the correct Heroku app name in the seed-local-db.sh file

  4. Run chmod +x ./seed-local-db.sh in your terminal to make the file executable

    After the above has been confirmed, run

    bash seed-local-db.sh

Database Migrations

A migration in TypeORM is a single file with SQL queries to update a database schema as updates/additions are made. Read more about migrations here.

Migrations are automatically run when the app is built docker (locally) or Heroku for staging and production apps.

You'll need to generate and run a migration each time you add or update a database field or table.

To generate a new migration

yarn migration:generate

Add the new migration import into typeorm.config.ts

To run (apply) migrations

yarn migration:run

To revert a migration

yarn migration:revert

Note that when running the app in Docker, you may need to run migration commands from the docker terminal/Exec

New environment variables must be added to Heroku before release.

Git Flow and Deployment

The develop branch is our source of truth, not main.

Create new branches from the develop base branch. There is no need to run the build command before pushing changes to GitHub, simply push and create a pull request for the new branch. GitHub Actions will run build and linting tasks automatically. Rebase and merge feature/bug branches into develop.

This will trigger an automatic deployment to the staging app by Heroku.

When changes have been tested in staging, merge develop into main. This will trigger an automatic deployment to the production app by Heroku.

Swagger

Swagger automatically reflects all of the endpoints in the app, showing their urls and example request and response objects.

To access Swagger simply run the project and visit http://localhost:35001/swagger

License

Bloom and all of Chayn's projects are open source. The core tech stack included here is open source however some external integrations used in the project require subscriptions.