Note that there is similar guidance in https://github.com/samvera/hyrax/blob/main/CONTAINERS.md#hyrax-engine-development and the two should probably be combined and deduplicated. It may be useful to consult both.

Prerequisites:

• What are the prerequisites?

Start/Stop Hyrax:

• How do I start the test app?
• How do I stop the test app?

Hyrax in the Browser:

• How can I access Hyrax in my browser?
• How can I log in as an admin user?
• How can I log in as a basic user?

Testing and Debugging Hyrax:

• How do I set a breakpoint?
• How do I run tests?
• How do I modify code in the docker container app?
• How can I explore the application code?
• How can I view the application log?
• How can I explore the database?
• How can I explore the solr?
• How do I fix a flaky test?

Debugging Docker:

• How can I tell if all the containers are running?
• How can I view the logs for a container?
• What to try if the test app doesn't fully start?
• Where can I find official Docker documentation?

Installing Docker for Mac & Windows:

• (recommended) For Mac & Windows, installing Docker Desktop will install the required Docker Engine and Docker Compose. It provides a Dashboard UI where you can view the state of each container, view of logs for each container, start/restart/stop each container, and more. You can install Docker Engine and Docker Compose individually if you prefer. See the links below for other systems.

Installing Docker for other systems:

NOTE: These are required for all systems, but if you installed Docker Desktop on Mac or Windows, these were installed as part of that process.

• (required) Install Docker Engine with CLI client
• (required) Install Docker Compose

Configuring Docker: Docker Desktop allots 1GB of ram to virtual machines by default. You'll need to increase this to at least 4GB to run the hyrax stack. You may need 8GB to also successfully run the full test suite.

Find the Memory allocation in the Preferences menu under Resources

All systems:

• (required) Clone hyrax from GitHub.

The images must be built first. This is done the first time you use a container and again if major changes are made and you want to update the container. To do this, execute the following from the root of the hyrax app...

docker-compose build

To start the services defined in docker-compose.yml, execute the following from the root of the hyrax app...

docker-compose up -d

To stop the services defined in docker-compose.yml, execute the following from the root of the hyrax app...

docker-compose down

http://localhost:3000

There is a predefined admin user:

• username: [email protected]
• password: _defined in app/utils/hyrax/test_data_seeders/user_seeder.rb

There are two predefined basic users:

• username: [email protected]
• username: [email protected]
• password: _defined in app/utils/hyrax/test_data_seeders/user_seeder.rb

Set breakpoints using byebug just as you usually would.

Attaching to the application container

• get the name of the application container
  • list all containers with:

docker container ls -a

• note the container id or name for the container with name like hyrax_app_1
• attach to the application (assumes the container name is hyrax_app_1):

docker attach hyrax_app_1

NOTE: There won't be any output in the terminal window after executing attach until an action is taken in the browser that causes output.

TO DETACH:

• In the terminal window where you executed the attach command, execute key sequence...

<CTRL><P>
<CTRL><Q>

CAUTION: If you type <CTRL><C>, the container will be stopped which is generally undesirable.

Debugging in the browser

• Use the instructions above to attach to the application container.
• When you run the application in the browser, output will now be displayed in the terminal window where the attach command was executed.
• Any byebug breakpoints set in the code will interrupt execution in this terminal.
• When done, use the instructions above to detach from the application container.

Debugging in a test

• Use the instructions above to attach to the application container.
• Run a test in a separate terminal window that will trigger a break point. See How do I run tests?
• Any byebug breakpoints set in the code will interrupt execution in the terminal where you ran the test.
• When done, use the instructions above to detach from the application container.

NOTE: It will take a bit for any output from the test to be shown in the terminal where you ran the test. Be patient, once the test starts running, there will be output.

See also How do I set a breakpoint?.

NOTE: Before running these commands, you need to run docker-compose up.

Run all tests

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

Run all tests in a spec file

docker-compose exec -w /app/samvera/hyrax-engine app sh -c "bundle exec rspec spec/path/to/spec.rb"

where, spec/path/to/spec.rb is a path like spec/controllers/hyrax/dashboard_controller_spec.rb

Run one test in a spec file

docker-compose exec -w /app/samvera/hyrax-engine app sh -c "bundle exec rspec spec/path/to/spec.rb:18"

where, spec/path/to/spec.rb is a path like spec/controllers/hyrax/dashboard_controller_spec.rb and 18 is the first line number of the test you want to run.

Simply make changes to the code on your localhost where you installed Hyrax using git clone. The code in the container is synced to your local code. Generally speaking, there is no need to stop and restart the container after making changes. You might need to do this if you change initializers or other code that only runs at application start up.

Start a sh shell on the app service using:

docker-compose run app sh

NOTE: The command automatically puts you in the WORKDIR defined in Dockerfile (e.g. /app/samvera/hyrax-webapp).

Type exit to end the sh shell when done.

Docker Dashboard

• click Containers / Apps in left side menu
• click the arrow to the left of hyrax to expand it to see the services
• click on hyrax_app_1 and the log will be displayed

Through Command Line

docker-compose logs app

OR

Start a sh shell on the app service and explore logs/development.log there.

Start a bash shell on the database service using:

docker-compose run postgres bash

In the bash shell, start the postgres CLI using:

psql -h postgres -U hyrax_user -d hyrax

NOTE: If this command doesn't work, look at docker-compose.yml to see if postgres configuration has changed.

Quit postgres with:

\q

Type exit to end the bash shell when done.

There are 4 cores created for solr:

• hyrax - Hyrax application writes to this core.
• hyrax_test - rspec tests write to this core.
• hyrax-valkyrie-dev - If Hyrax is configured to use Valkyrie to write to solr, the application will also write to this core.
• hyrax-valkyrie-test - rspec tests that test using Valkyrie to write to solr write to this core.

You can access the solr UI for all cores at: http://localhost:8983/solr/

If running specs locally or in CircleCI sometimes fails randomly on a spec unrelated to your work, you have likely encountered a "flaky" test. Flaky tests can be caused by a spec changing the state of the application in a way that adversely affects another spec. The order that specs are run in are randomized to catch this problem. Note: Feature specs and other code that relies on asynchronous code execution can also result in flaky tests depending on system load rather than execution order.

In order to begin fixing a flaky test, we must first identify the cause using rspec's --bisect option. We will also need to use the same randomization seed that was generated by rspec when the flaky test failed. e.g. bundle exec rspec --bisect --seed 12345. If you were testing specific specs, also include the same list of specs.

If a flaky test is reported by CircleCI, then we need to identify which spec files were being tested together. CircleCI allows specs to be split up and run in parallel, and that list needs to be retained when recreating the failure locally. First, check that you are looking at the parallel run on which the flaky test was run. CircleCI reports the full command line used to run rspec in the output of the "RSpec Tests" step, near the beginning. It should be a very long line that begins with + bundle exec rspec spec/.... Copy that entire line (except the +) into your own command line, and insert the --bisect and --seed options using the same seed used on CircleCI.

Note: Check that the copied command is complete! If the end is truncated, then it has exceed your system's limit on command line length. This can be worked around by saving the full command to a script file and running that instead.

When rspec is done bisecting it should output a command to run only the specs needed to recreate the failing flaky test. Running that command with the -f d option will include the spec descriptions as they are run to make finding them in code easier. You should now be set to begin fixing the flaky test. It is likely something in the 1st spec is conflicting with the 2nd spec. Good luck!

NOTE: hyrax_db_migrate_1 and hyrax_sidekiq_1 will show EXITED (0). These are used for initial migration and then stop.

In Docker Desktop:

• Go to Containers/Apps (left side menu)
• expand hyrax (main content area) - This lists all the containers and their state (e.g. RUNNING, EXITED)

Using the Command Line The following command will list all containers started as services by docker compose. It will list the state of each service (e.g. Up, Exit).

docker-compose ps

In Docker Desktop:

• click Containers / Apps in left side menu
• click the arrow to the left of hyrax to expand it to see the services
• click on a service in the list and the log for that service will be displayed

Sometimes all the various containers and services do not fully start and connections between containers fail. If this happens, you can try the following in increasing levels of time required for the step to complete. You may not need to do all of this to make your system happy again.

Generally, after trying each step, start the services back up and see if the problem is fixed.

After each step, start services with:

docker-compose up

NOTE: The following lists commands to execute in the terminal from the root of hyrax. There are ways to do most of this through Docker Desktop that are not described here.

restart docker compose

docker-compose down
docker-compose up

restart docker

Easiest way is through the Docker Desktop Dashboard.

• Click the troubleshooting bug in the banner bar of the Desktop app.
• Click Restart button next to Restart Docker Desktop.

Most of the time, this is sufficient to get things working again.

prune containers

If all your containers were created by docker compose for hyrax, then there won't be any running after executing the docker-compose down command. But if you use docker for other projects, there may be some hanging around that you don't need.

NOTE: This will delete all stopped containers for all projects, so exercise some caution.

docker-compose down
docker container prune

remove images

List images:

docker image ls

This will list all images. If a container does not start, you can remove the image for that container. Copy the image ID from the listing and use it in place of IMAGE_ID in the following command.

docker image remove _IMAGE_ID_ .

If the image is a public image from Docker Hub, then it will be downloaded again when you run docker-compose up. If you needed to remove the image for the Hyrax app, then you will need to rebuild the image first using docker-compose build.

Remove Networks

WARNING! This will remove:

• all stopped containers
• all networks not used by at least one container
• all dangling images
• all dangling build cache

docker-compose down
docker system prune

Last Resort - kill everything

WARNING! This is a last resort.

• Pruning docker volumes will reset all data that generally is persisted when taking the system down and back up.
• Pruning images will require all images to be down loaded or rebuilt which is time consuming.

docker-compose down
docker container prune
docker volume prune
docker image prune -a 
docker system prune

Perform the steps in How do I start the test app? to start fresh.

• Dockerfile reference
• docker-compose.yml reference
• docker CLI reference
• docker-compose CLI reference