Skip to content

development.md

Latest commit

 

History

History
211 lines (146 loc) · 9.35 KB

development.md

File metadata and controls

211 lines (146 loc) · 9.35 KB

Development

We recommend using GitHub Codespaces to get an instance running. It should work out-of-the-box and is how most contributors work on HCB.

Running HCB locally

Once HCB is running locally, log in into your local instance using the email admin@bank.engineering. Use Letter Opener to access the development email outbox and retrieve the login code. Letter Opener can be accessed at localhost:3000/letter_opener.

Code style

Thank you for contributing! Please make sure to follow the code style guide here.

Quickstart with GitHub Codespaces

Open in GitHub Codespaces

GitHub Codespaces allows you to run a development environment without installing anything on your computer, allows for multiple instances, creates an overall streamlined and reproducible environment, and enables anyone with VS Code to contribute.

To get started, whip up a codespace, open the command palette(CTRL+SHIFT+P), and search Codespaces: Open in VS Code Desktop. HCB does not work on the web version of Codespaces.

You can then run bin/dev to launch HCB. If you can't open the link that is printed in the terminal, navigate to the PORTS tab in your terminal and set port 3000 to public and then back to private.

Automated setup with Docker

If you are running macOS or Ubuntu, you can clone the repository and run the docker_setup.sh script to automatically setup a development environment with Docker. Append --with-solargraph to the command to also setup Solargraph, a language server for Ruby. You may also need to install the Solargraph extension for your editor.

./docker_dev_setup.sh
# or with Solargraph
./docker_dev_setup.sh --with-solargraph

Then, to start the development server:

./docker_start.sh
# or with Solargraph
./docker_start.sh --with-solargraph

Manual setup with Docker

Copy .env file

cp .env.development.example .env.development

Run Docker

env $(cat .env.docker) docker-compose build
env $(cat .env.docker) docker-compose run --service-ports web bundle exec rails db:create db:migrate
env $(cat .env.docker) docker-compose run --service-ports web bundle exec rails s -b 0.0.0.0 -p 3000

(Optional) Run Solargraph in Docker

Solargraph is a tool that provides IntelliSense, code completion, and inline documentation for Ruby. You may also need to install the Solargraph extension for your editor.

env $(cat .env.docker) docker-compose -f docker-compose.yml -f docker-compose.solargraph.yml build
env $(cat .env.docker) docker-compose -f docker-compose.yml -f docker-compose.solargraph.yml up -d solargraph

Native setup

Before beginning this process, please ensure you have both Ruby and Node installed, as well as a PostgreSQL database running.

[Step 1] Prerequisite: Install Ruby and Node

See .ruby-version and .node-version for which versions you need installed. I personally recommend using a version manager like rbenv for ruby, nvm for node, or asdf for both.

[Step 2] Prerequisite: Install and run PostgreSQL

We recommend you use version 15.12 as that's what running in production. If you're on MacOS, I recommend using Homebrew to get Postgres up and running. If you are on another OS or dislike Homebrew, please refer to one of the many guides out there on how to get a simple Postgres database running for local development.

How to install Postgres using Homebrew

brew install postgresql@15 # You only need to run this once
brew services start postgresql@15

[Step 3] HCB-specific instructions

Now that you have Ruby, Node, and Postgres installed, we can begin with the HCB-specific setup instructions.

  1. Clone the repository

    git clone https://github.com/hackclub/hcb.git

  2. Set up your environment variables

    cp .env.development.example .env.development

    Since you're running HCB outside of Docker, you will need to update the DATABASE_URL environment variable located in .env.development. The default caters towards Docker and GitHub Codespaces users. Please update it to

    postgres://postgres@127.0.0.1:5432

  3. Install ruby gems

    bundle install

    If you're on a Mac you may need to install a few Homebrew dependencies to get bundle install to succeed:

    brew install pkg-config cairo libpq

  4. Install node packages

    yarn install

  5. Prepare the database This creates the necessary tables and seeds it with example data.

    bin/rails db:prepare

  6. Run Rails server

    bin/dev

    Yay!! HCB will be running on port 3000. Browse to localhost:3000.

    Optionally, if you want to run HCB on a different port, try adding -p 4000 to the command.

Additional installs for local development:

Install ImageMagick

# Mac specific instruction:
brew install imagemagick

Testing

Automated testing w/ RSpec

HCB has a limited set of tests created using RSpec. Run them using:

bundle exec rspec

Credentials

External contributors should provide credentials via a .env.development file (view example). Developers using the devcontainer setup (eg. in GitHub Codespaces), will need to rebuild the container after modifying the .env.development file to pull in the new variables.

HCB relies on two services for the majority of its financial features: Stripe and Column. Follow the Stripe testing guide to setup Stripe. You can register for a Column account here; after their onboarding questions, select "Skip to Sandbox".

We also include OpenAI and Twilio keys in our .env.development file. Information about obtaining these keys is available in these articles on help.openai.com and twilio.com.

Internally, we use Doppler to manage our credentials; if you have access to Doppler, you can set a DOPPLER_TOKEN in your .env file to load in credentials from Doppler.

Production data

We've transitioned to using development keys and seed data in development, but historically we have used production keys and data on development machines. We do not recommend rolling back to using production data & keys in development, but if absolutely necessary a HCB engineer can take the following steps:

  • Use a DOPPLER_TOKEN with development access, this can be generated here.

  • Override the LOCKBOX, ACTIVE_RECORD__ENCRYPTION__DETERMINISTIC_KEY, ACTIVE_RECORD__ENCRYPTION__KEY_DERIVATION_SALT, and ACTIVE_RECORD__ENCRYPTION__PRIMARY_KEY secrets by defining them in .env.development. Use the values from the production enviroment in Doppler.

  • Run the docker_setup.sh script to set up a local environment with Docker. The script will use a dump of our production database from Heroku.

Pulling data from production

On the postgres server:

su - postgres
pg_dump -Fc --no-acl --no-owner -h localhost -U rails -d hcb_production -f /tmp/hcb_production.dump

On your laptop:

scp hcb-postgres-3:/tmp/hcb_production.dump hcb_production.dump
pg_restore --verbose --clean --no-acl --no-owner -h localhost -U postgres -d bank_development hcb_production.dump

Flipper

Flipper is used to toggle feature flags on HCB. Flipper can be accessed at localhost:3000/flipper/features. To enable a flag, press "Add Feature", paste in the name of a feature from this list, and then press "Fully Enable".

Getting an OAuth token

See the v4 API Standards — Authentication section for full instructions on creating an OAuth application and obtaining an access token.