Hyrax WG setup notes for a Mac

Table of Contents Hyrax WG setup notes for a Mac To run hyrax To use hyrax To run rails console To use byebug To run rubocop To run a rspec test To run all rspec tests A few helpful commands Tear down and rebuild Docker container Docker Desktop notes

Hyrax WG setup notes for a Mac

2022/03/10 - Fritz Freiheit

These instructions are for a Mac (macOS Catalina v10.15.7, Quad-Core Intel i5, 16 GB memory)

References:

• https://github.com/samvera/hyrax/wiki/Hyrax-Development-Guide
• https://github.com/samvera/hyrax/blob/main/CONTAINERS.md
• https://github.com/samvera/hyrax/wiki/FAQ-for-Dassie-Docker-Test-App

Note: docker-compose and docker compose are used interchangeably.

• ensure you've got Docker Desktop installed ( https://docs.docker.com/desktop/mac/install/ )
• using Docker Desktop, check for and perform updates if necessary
• Increase memory: Docker Desktop --> (gear icon in top bar) --> Preferences --> Resources --> Increase memory to 8GB (this worked for me)
• select or create a working directory, for this example I'll use: ~/github
• clone hyrax

cd ~/github
git clone https://github.com/samvera/hyrax.git
cd ~/github/hyrax
git remote add upstream https://github.com/samvera/hyrax.git

To run hyrax

Run hyrax app from shell to see log. In shell window:

cd ~/github/hyrax
docker compose up

You can also start it from Docker Desktop, but you won't see the log.

When finished, in shell window: Control-C, then wait for app to shutdown before docker compose down

^C
docker compose down

You can also stop the app from Docker Desktop.

To use hyrax

With hyrax app container running, visit: http://localhost:3000/

To run rails console

With hyrax app container running in separate shell (see above):

In new shell window:

cd ~/github/hyrax
docker-compose exec app rails console

Or, start up a shell in the hyrax app container:

cd ~/github/hyrax
docker-compose exec -w /app/samvera/hyrax-webapp app sh

From /app/samvera/hyrax-webapp #

bundle exec rails console

This will shutdown when the hyrax app container stops.

To use byebug

Insert into code. The hyrax app container can be running. Usually updates to the code will take affect next time you visit a hyrax page. If it there is a problem, try stopping and restarting the hyrax app container.

To interact with byebug, attach to hyrax-app-1 in a separate shell window:

cd ~/github/hyrax
docker attach hyrax-app-1

Nothing will happen in this window until you visit a page, then the log will echo in the shell window.

To run rubocop

Start a shell window:

cd ~/github/hyrax
docker compose exec -w /app/samvera/hyrax-engine app sh

From /app/samvera/hyrax-engine #

bundle exec rubocop ./path/to/file

Or all at once:

docker compose exec -w /app/samvera/hyrax-engine app sh -c "bundle exec rubocop ./path/to/file"

To run a rspec test

Start a shell window:

cd ~/github/hyrax
docker compose exec -w /app/samvera/hyrax-engine app sh

From /app/samvera/hyrax-engine #

bundle exec rspec ./path/to/file

To run without the warnings/errors (if it silently fails, rerun without redirecting to /dev/null):

bundle exec rspec 2>/dev/null

To run all rspec tests

Ensure Docker Desktop will allocate enough memory (see above)

cd ~/github/hyrax
docker compose exec -w /app/samvera/hyrax-engine app sh

From /app/samvera/hyrax-engine #

bundle exec rspec

Or all at once:

docker-compose exec -w /app/samvera/hyrax-engine app sh -c "bundle exec rspec"

To run without the warnings/errors (if it silently fails, rerun without redirecting to /dev/null):

bundle exec rake rspec 2>/dev/null

A few helpful commands

• To list running components: docker compose ps
• To list running apps: docker compose ls

Tear down and rebuild Docker container

After updating docker to latest and deleting all data/images through the Docker Desktop app.

• Docker Desktop --> Containers/Apps --> hyrax (trashcan icon)

Or for the bigger hammer:

• Docker Desktop --> (bug icon in top bar) --> Troubleshoot --> "Clean/Purge Data"

docker-compose build --no-cache
docker compose up

Docker Desktop notes

If you lose access to Docker Desktop (that is, you can't get to its window anymore), shut it down via the Mac top icon bar, then restart it. It seems to behave better if you shut it down from the Docker Desktop icon in Mac top icon bar.