Our goal is to provide a practical, reusable reference environment for applications. The first step is providing an on-ramp for Hyrax engine development. Then providing help with Hyrax-based application development. Finally, providing better guidance around deployment.
See the Troubleshooting section if you encounter any issues.
Hyrax Engine Development
We support a
docker-compose-based development environment for folks working on
the Hyrax engine. This environment is substantially more like a Hyrax production
setup than the older
Within your cloned repository, tell Docker to get started installing your development environment:
docker-compose build docker-compose up
This starts containers for:
hyraxtest application (
- SideKiq (for background jobs)
It also runs database migrations. This will also bring up a development application on
To stop the containers for the Hyrax-based application, type Ctrl+c. To restart the containers you need only run
Note: Starting and stopping Docker in this way will preserve your data between restarts.
Code Changes and Testing
docker-compose up running, any changes you make to your cloned Hyrax code-base should show up in
http://localhost:3000; There may be cases where you need to restart your test application (e.g. stop the containers and start them up again).
Any changes you make to Hyrax should be tested. You can run the full test suite using the following command:
docker-compose exec -w /app/samvera/hyrax-engine app sh -c "bundle exec rspec"
Let's break down the above command:
- Tell docker to run the following:
- In the working directory "/app/samvera/hyrax-engine" (e.g. your cloned Hyrax repository)
- of the container named "app"
- run the following shell script
"bundle exec rspec"
- run the rspec test suite
bundle exec rspec portion of the command runs the whole test suite. See the rspec command documentation for how to refine your test runs.
/app/samvera/hyrax-webapp is analogous to the
.internal_test_app that we generate as part of the Hyrax engine Continuous Integration.
The Docker Container Named "app"
As a developer, you may need to run commands against the Hyrax-based application and/or the Hyrax engine. Examples
of those commands are
rails db:migrate and
rspec. You would run
rails db:migrate on the Hyrax-based
rspec on the Hyrax engine.
In the engine development
app container, the
.dassie test Hyrax-based application is setup as a docker
bind mount to
/app/samvera/hyrax-webapp, and your local development copy of Hyrax (eg. the clone samvera/hyrax) is bound to
/app/samvera/hyrax-engine. Those directories are defined as part of the Dockerfile configuration.
What does this structure mean? Let's look at an example. The following command will list the rake tasks for the Hyrax-based application running in Docker:
docker-compose exec -w /app/samvera/hyrax-webapp app sh -c "bundle exec rake -T"
And this command lists the rake tasks for the Hyrax engine that is in Docker:
docker-compose exec -w /app/samvera/hyrax-engine app sh -c "bundle exec rake -T"
In the two examples, note the difference in the
-w switch. In the first case, it's referencing the Hyrax-based application. In the latter case, it's referencing the Hyrax engine.
If you are interested in running Hyrax in debug mode, this requires a somewhat different approach than running Hyrax bare-metal. You need to use
docker attach to debug the running docker instance.
docker-compose uprunning open a new Terminal session.
- In that new Terminal session, using
docker container lsfind the "CONTAINER ID" for the
- With the "CONTAINER ID", run
docker attach <CONTAINER ID>.
This advice comes from Debugging Rails App With Docker Compose: How to use Byebug in a dockerized rails app.
Bad Address SOLR
docker-compose up running, if you see the following, then there may be issues with file permissions:
db_migrate_1 | waiting for solr:8983 db_migrate_1 | nc: bad address 'solr'
Check the Docker application logs and look for permission errors:
Executing /opt/docker-solr/scripts/precreate-core hyrax_test /opt/solr/server/configsets/hyraxconf cp: cannot create directory '/var/solr/data/hyrax_test': Permission denied
The solution that appears to work is to
docker-compose down --volumes; This will tear down the docker instance, and remove the volumes. You can then run
docker-compose up to get back to work. Note: the
--volumes switch will remove all custom data.
Errors building the Docker image
If you encounter errors running
docker-compose build, try running
bundle update in
./hyrax as well as within
./hyrax/.dassie. That can help clear up the problem of a failure to build a particular gem.
Containers do not all start
If any of the services fail to start on
docker-compose up, try clearing out any
Gemfile.lock files that might exist in
./hyrax/.dassie and run
docker-compose build again, then
docker-compose up again.
Docker Image for Hyrax-based Applications
We also provide a base image which can be reused for your Hyrax applications:
echo "FROM samveralabs/hyrax" > Dockerfile
This is for applications that mount Hyrax and is separate from the docker containers for Hyrax engine development.
We publish several Hyrax images to hub.docker.com under the
samveralabs group. To build them, do:
# build an image for an app using Postgresql (`gem 'pg'`) docker build --target hyrax --tag samveralabs/hyrax:(git rev-parse HEAD) . docker push samveralabs/hyrax:(git rev-parse HEAD) # or; build a development image with sqlite docker build --target hyrax --tag samveralabs/hyrax:(git rev-parse HEAD)-sqlite --build-arg DATABASE_APK_PACKAGE="sqlite" . docker push samveralabs/hyrax:(git rev-parse HEAD)-sqlite
We also publish an image for the stable test application
docker build --target hyrax-engine-dev --tag samveralabs/dassie:(git rev-parse HEAD) . docker tag samveralabs/dassie:(git rev-parse HEAD) samveralabs/dassie:$HYRAX_VERSION docker push samveralabs/dassie:(git rev-parse HEAD) docker push samveralabs/dassie:$HYRAX_VERSION
Deploying to Production
Also under development is a Helm chart, which we are developing into a robust, configurable production environment for Hyrax applications.
If you have a Kubernetes cluster configured (
kubectl cluster-info), you can
dassie test applications with:
helm dependency update chart/hyrax helm install -n hyrax --set image.tag=(git rev-parse HEAD) dassie chart/hyrax