Skip to content

FAQ for Dassie Docker Test App

Jump to bottom
hackartisan edited this page Mar 2, 2022 · 37 revisions

Frequently Asked Questions

Prerequisites:

Start/Stop Hyrax:

Hyrax in the Browser:

Testing and Debugging Hyrax:

Debugging Docker:

What are the prerequisites?

Docker

** 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.

** 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

Hyrax

All systems:

  • (required) Clone hyrax from GitHub.

How do I start the test app?

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

How do I stop the test app?

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

docker-compose down

How can I test Hyrax in my browser?

http://localhost:3000

How can I log in as an admin user?

There is a predefined admin user:

How can I log in as a basic user?

There are two predefined basic users:

How do I set a breakpoint?

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.

How do I run tests?

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.

How do I modify code in the docker container app?

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.

How can I explore the application code?

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.

How can I view the application log?

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.

How can I explore the database?

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.

How can I explore the solr?

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/

How can I tell if all the containers are running?

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

How can I view the logs for a container?

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

What to try if the test app doesn't fully start?

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.

Where can I find official Docker documentation?

Learn more about Hyrax!

Clone this wiki locally