Skip to content

Latest commit

 

History

History
193 lines (132 loc) · 8.23 KB

development.md

File metadata and controls

193 lines (132 loc) · 8.23 KB

Development

We recommend using Docker to get an instance running locally. 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 (/letter_opener) to access the development email outbox and retrieve the login code.

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 browser or VS Code access 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. Run bin/dev. If you can't open the link that is printed in the terminal, ensure the 3000 port is public under the PORTS tab in your terminal.

After creating your codespace, run bundle install and bin/rails db:migrate. This will finish preparing HCB for development.

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

  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 wkhtmltopdf

# Mac specific instruction:
brew install wkhtmltopdf

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

Staging access

All PRs are deployed in a staging enviroment using Heroku. Login using the email [email protected]. Visit #hcb-staging on the Hack Club Slack for the code.

Credentials

External contributors should provide credentials via a .env.development file (view example).

HCB relies on two services for the majority of it's financial features: Stripe and Column. We recommend creating a US Stripe account in "test mode". Read more here: docs.stripe.com/test-mode. 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.