Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
226 lines (165 loc) · 9.22 KB

CONTRIBUTING.md

File metadata and controls

226 lines (165 loc) · 9.22 KB

Developer guidelines for contributing to UCBEARS

TODO:

  • Switch to a publicly accessible IIPImage distribution
  • Stop hard-coding Berkeley-specific SSO configuration

Table of Contents

Maintaining code quality

Before submitting a merge request, make sure:

  1. all tests pass (rake spec)
  2. code complies with RuboCop style guidelines as configured in .rubocop.yml
    • bundle exec rubocop to run the checks
    • bundle exec rubocop -a to auto-fix the easy ones (use with caution!)
  3. all code is covered by tests (rake coverage)

It's good practice to make sure existing tests pass even before committing to your feature branch, as it's easiest to fix failures immediately after they're introduced. Likewise with style checks.

Ideally, all development would be test-driven and code coverage would be 100% even on your feature branch, but this isn't always feasible, especially when you're still experimenting with an implementation or with a UI.

That said, it's better to commit code (to a feature branch!) with a build that doesn't pass, than to lose your work to a disk failure or to your own mistakes. 🙂

Setting up a Docker development environment

Requirements

Windows developers should also consider installing the Windows Subsystem for Linux. See “Docker Desktop WSL 2 backend” for instructions on integrating Docker Desktop with WSL.

Instructions

Add ENV File

Create a .env file and add
SECRET_KEY_BASE=[your key]
(Your key can be generated locally using rake secret or a completely fabricated string)

Building the Docker stack

To build a Docker stack based on the included docker-compose.yml file, run the command:

docker compose build --pull

This will build or pull images for the following services:

Service Ports Protocol Description
adminer 8080 http a web-based database administration tool (used for debugging)
db 5432 native (api) a PostgreSQL database
app 3000 http the Rails application (built from the Dockerfile in this repository
iipsrv 8180 http IIPImage server (used for controlled digital lending)
selenium 4444 http (api) Selenium Grid hub (used for system tests)
selenium-chrome 55900 vnc Selenium Grid node running Chrome (used for system tests)
updater temporary Rails application instance used to run rails setup

Note: The "Port" column indicates the host port (i.e., the port as seen from outside the Docker stack).

Starting the Docker stack

To start up the Docker stack, run the command:

docker compose up

Note: If anything else is already running on one of the ports listed above, that service will fail to start.

Accessing the server

Navigate to http://localhost:3000/home.

Note: On first run, the database will not exist and assets (javascript/css) will not be precompiled. To set up the database and precompile the assets, you can use docker-compose exec to run the relevant Rake tasks in the application container.

docker compose exec -u root app rails db:setup assets:precompile

Running commands in the application container

With the Docker stack up and running, use docker-compose exec app and follow it with the command, e.g.:

command purpose
docker compose exec app rake -T list available Rake tasks
docker compose exec app rails console open the running server's Rails console
docker compose exec app bundle exec rubocop run RuboCop style checks

Debugging system test failures

The Selenium node running Chrome has a VNC server running on port 55900. To access it, open vnc://localhost:55900 in the macOS Screen Sharing app, or any other VNC client.

To launch your own instance of Chrome inside the Selenium node:

docker compose exec -u root selenium-chrome \
  sudo -u seluser google-chrome \
    --disable-dev-shm-usage \
    --disable-gpu \
    --auto-open-devtools-for-tabs

(You'll see a bunch of Failed to connect to the bus errors, which can be safely ignored.)

To run just the system tests in the app container:

docker compose exec -e RAILS_ENV=test app rake spec:system

It may be convenient to also include -e CAPYBARA_SERVER_PORT=<some port> so it's easier to navigate to the server Capybara starts.

Setting up a standalone development environment

Requirements

  • Ruby (see .ruby-version for the required version
  • node.js
    • recommended: a Node version manager such as nvm
  • PostgreSQL
    • Note: In some cases it may be more convenient to keep the database in Docker even while running the app locally, as it avoids having to switch the database URL between test and development environments.
  • For system tests: ChromeDriver and Google Chrome
  • IIPImage or another IIIF-compatible image server

MacOS developers should consider installing Homebrew, which makes downloading and installing these other tools much simpler.

Windows developers should considering installing the Windows Subsystem for Linux.

Environment variables

Variable Format Purpose
DATABASE_URL postgres://<user>:<password>@<host>/<database-name> application database
LIT_LENDING_ROOT directory path root directory for UCBEARS data
LIT_IIIF_BASE_URL HTTP or HTTPS URL IIIF service URL

Instructions

  1. Set up the development database:

    DATABASE_URL='postgres://<user>:<password>@<host>/<database-name>' rails db:setup

  2. Start the server:

    DATABASE_URL='postgres://<user>:<password>@<host>/<database-name>' rails s

Note: Placing DATABASE_URL and other environment variables in a .env file can simplify development. However, you may run into issues using the same database for development and testing. You can work around this using Docker for just the database -- see below.

Using a Dockerized database for local development

For local development against a Docker database, you can start just the database service from the docker-compose.yml stack:

  1. ensure Postgres is not running, or at any rate not running on its default port of 5432.

  2. run docker compose up -d db to start the Postgres service, and only the Postgres service, in detached (background) mode.

  3. Edit /etc.hosts and add the line:

    127.0.0.1 db

    so that db now resolves to your local machine.

You should now be able to run rails db:setup from the project root to create dev and test databases in the Dockerized Postgres.

Accessing the server

Navigate to http://localhost:3000/.