Skip to content

Latest commit

 

History

History
225 lines (157 loc) · 11.3 KB

development.md

File metadata and controls

225 lines (157 loc) · 11.3 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 [email protected]. 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://[email protected]: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

There are two different ways you can accomplish the first step of getting an OAuth token, either using a webpage, or the terminal depending on your preference. Both described here use the authorization_code grant type, but HCB also supports the device_code grant type. See the device grant gem docs for instructions on how to use this flow, keeping in mind that HCB uses a scope of api/v4/oauth instead of just oauth.

  1. Go to localhost:3000/api/v4/oauth/applications. Press "New Application" and then set the name to anything of your choosing, the redirect URI to http://localhost:3000/, and scopes to read write. For the purposes of this guide, you should leave confidential checked (see more context here). Press "Submit" and then save the info on the new page that appears and press "Authorize."

  2. Open the rails console by running bin/rails c. Then, run app = Doorkeeper::Application.create(name: "tester", redirect_uri: "http://localhost:3000/", scopes: ["read", "write"], confidential: false) inside the console and save the output (you will need this later). After this, open http://localhost:3000/api/v4/oauth/authorize?client_id=<UID>&redirect_uri=http://localhost:3000/&response_type=code&scope=read write.

Press the button to approve access on the page, then copy the code that appears in the address bar after being redirected. Now, send a POST request to http://localhost:3000/api/v4/oauth/token with a content type of application/x-www-form-urlencoded (you can use a tool like Postman to do this!). The request body fields are as follows:

grant_type=authorization_code
code=<CODE>
client_id=<UID>
client_secret=<SECRET>
redirect_uri=http://localhost:3000/

This request will return your OAuth access token. It can then be passed into future API requests in the Authorization header. Ex. Authorization: Bearer <ACCESS TOKEN>