Contributing

This document is meant to be a complete set of instructions on how to contribute to Repeater World, including everything you need to know to get it up and running on your own computer. If the instructions here don't work, please update this document or report an issue to https://github.com/flexpointtech/repeater_world/issues. If you have any questions you can ask on https://github.com/flexpointtech/repeater_world/discussions.

Repeater World is a Ruby on Rails application, developed as a monolith, with HTML served from the server following the Hotwire pattern. To develop you need to run:

• A PostgreSQL database.
• The Rails Server.
• The Tailwind CSS compiler.

The PostgreSQL database, and all other services, will be run from a docker-compose file that's distributed with the code.

Install Docker

On Windows

You can just install Docker Desktop from https://www.docker.com/get-started. Make sure it's running before you try to develop. If it's configured to not start on boot, it might not be running.

On MacOS

TODO

On Linux

TODO

PostgreSQL

Even though we use a dockerized database, pg gem depends on libraries which come with Postgres installed on the host machine:

Windows

Assuming that Postgres also needs to be installed on Linux (see Mac), it probably needs to be installed with:

sudo apt-get install libpq-dev

or similar, but note that I haven't tried this.

MacOS

brew install postgresql

Ruby

You need Ruby, 3.1.1 or so.

On Windows

On Windows, the recommended way to install Ruby is to install the Windows Subsystem for Linux: https://docs.microsoft.com/en-us/windows/wsl/install

The recommended Linux to use is Ubuntu.

To install Ruby, install rbenv using rbenv-installer

On MacOS

???

On Linux

???

Running for the first time

First check out the code:

git clone [email protected]:flexpointtech/repeater_world.git
cd repeater_world

You first need to install dependencies:

bundle install

Now run the database (and any other services we may have added):

docker-compose up

That should leave PostgreSQL running on port 10401. The credentials can be found in docker-compose.yml

Create the databases:

rake db:create

Run the migrations:

rake db:migrate

Generate sample data:

rake db:seed

Run the tests (or specs if you want to be fancy):

rake spec

If all of that worked you are in good shape.

Now run the server in development mode:

./bin/dev

Once that's done starting up, you can go to http://localhost:10400 and you'll see your local version of RecruitesWTF running.

bin/dev is a script that runs two commands using foreman and reading Procfile.dev, one is rails server which runs Rails itself and the other one is rake tailwindcss:watch which compiles the TailwindCSS CSS as you change them. The latter is technically not needed if you are not changing CSS, but we all forget to start it and spent half an hour wondering why the margin is not getting wider.

Environment Variables

To configure the app.

• DATABASE_URL: the full database url with credentials to connect to, only used in production.
• ALLOW_SAMPLE_DATA_GENERATION: if it's "true", generating sample data is allowed, something that blanks the database first. This should never be turned on in prod.
• DELIVER_EMAILS: if it's "true" emails will be delivered normally, if not, the headers will be re-written to be delivered to SAFE_EMAIL_DEST.
• SAFE_EMAIL_DEST: email address used in staging, review apps, dev, etc. that should receive emails when we are avoiding sending them to real users.
• GOOGLE_ANALYTICS_ID: the ID of the Google Analytics stream. When absent, Google Analytics is not loaded (good for dev, testing, staging).
• FATHOM_ID: the id to report analytics to Fathom. It's presence enables fathom.
• HELPSCOUT_BEACON_ID: the id of the HelpScout beacon (the chat bubble). It's presence enables the beacon.
• SENTRY_DSN: the DSN (aka key) for talking to Sentry for the backend end.
• SENTRY_DSN_FE: the DSN (aka key) for talking to Sentry for the front end.

Defined by third parties and used

These are defined by render.com:

• IS_PULL_REQUEST: "true" if it's a pull request, that is, a review app.
• RENDER: "true" if the application is running in render.com.
• RENDER_SERVICE_NAME: the name of the service in render.com, this could be web, or queue or background job or something like that.

These are defined by github actions:

• CI: always "true" while running in Github actions.

These are defined by Heroku:

• HEROKU_RELEASE_VERSION: version number set by Heroku, it's used by Sentry (at least).
• HEROKU_APP_NAME: application name set by Heroku, it's used by Sentry (at least).