hyrax 3.0.1 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '081daeb5064ca757527e98cfbbea41846b8a15440a26a2d152b1ad7a1c7f395b'
-  data.tar.gz: 70e52823ff8ef7546510db08f28c22207488952f146be3bb63b9ecba440ebb81
+  metadata.gz: 95d9c34fb76fd8e3ac06d6605962c16bbdad32ffa2c1f5ab24958740fc175507
+  data.tar.gz: 8be6a02dc887f93076d84a5dc47b8e4cc7ecf916415e23fd00df24078f20ebbf
 SHA512:
-  metadata.gz: a36054d54da990c0ea0ab03ce538a903ceed121026e1ac160b1dc2226a21fc12a8b8d422d99b71e545048af33318ab86ae90e8e3a906b6bcb1061983059ac4d4
-  data.tar.gz: 5b8b6759915c77982125b0c33b6f8681dd7ea61c0cce63b0665567fd00e47be468d097e6653cdfd65df5db35ff1ac4f01c98cb39b12d774c741b8cd6ff086e1a
+  metadata.gz: b6e519190cda4bdcdb4a68577b682ad6fd138756da25ce69228429755e3ee3a2fb3ac95d9140831d623f75e0aa8a9115d378abafe8f301850c200fb8080b9942
+  data.tar.gz: 90610095bd1b82e79bc7ebaa8de11a2f3c8452803a15d60a4595308b67ab85724b118c7343b2a46fb2bafb3a138365fdb94540e948965cc1a96d4259fd8b07d6

data/.circleci/config.yml

@@ -12,7 +12,7 @@ jobs:
         default: 1.17.3
       rails_version:
         type: string
-        default: '5.2.2'
+        default: '5.2.6'
     executor:
       name: 'samvera/ruby'
       ruby_version: << parameters.ruby_version >>
@@ -22,10 +22,20 @@ jobs:
       NOKOGIRI_USE_SYSTEM_LIBRARIES: true
     steps:
       - samvera/cached_checkout
-      - samvera/bundle_for_gem:
+
+      - run:
+          name: Check for a branch named 'master'
+          command: |
+            git fetch --all --quiet --prune --prune-tags
+            if [[ -n "$(git branch --all --list master */master)" ]]; then
+              echo "A branch named 'master' was found. Please remove it."
+              echo "$(git branch --all --list master */master)"
+            fi
+            [[ -z "$(git branch --all --list master */master)" ]]
+
+      - samvera/bundle:
           ruby_version: << parameters.ruby_version >>
           bundler_version: << parameters.bundler_version >>
-          project: hyrax
 
       # Run rubocop in parallel with caching
       # This should get added to the orb once proven here
@@ -63,7 +73,7 @@ jobs:
         default: 1.17.3
       rails_version:
         type: string
-        default: '5.2.2'
+        default: '5.2.6'
     executor:
       name: 'samvera/ruby_fcrepo_solr_redis_postgres'
       ruby_version: << parameters.ruby_version >>
@@ -78,10 +88,9 @@ jobs:
           at: ~/
       - samvera/engine_cart_generate:
           cache_key: v1-internal-test-app-{{ checksum "hyrax.gemspec" }}-{{ checksum ".regen" }}-{{ checksum ".circleci/config.yml" }}-<< parameters.rails_version >>-<< parameters.ruby_version >>
-      - samvera/bundle_for_gem:
+      - samvera/bundle:
           ruby_version: << parameters.ruby_version >>
           bundler_version: << parameters.bundler_version >>
-          project: hyrax
       - persist_to_workspace:
           root: ~/
           paths:
@@ -117,24 +126,38 @@ jobs:
           solr_config_path: .internal_test_app/solr/conf
           core_name: hyrax-valkyrie-test
       # Rerun bundler in case this is a different ruby version than bundle and build steps
-      - samvera/bundle_for_gem:
+      - samvera/bundle:
           ruby_version: << parameters.ruby_version >>
           bundler_version: << parameters.bundler_version >>
-          project: hyrax
       - run:
           command: bundle exec rake app:db:migrate
       - samvera/parallel_rspec
 
+# Trigger a workflow on the nurax repository that will deploy the most recent hyrax gem code to https://nurax-dev.curationexperts.com/
+  deploy:
+    docker:
+      - image: ubuntu
+    steps:
+      - run:
+          name: Install curl
+          command: apt-get update && apt-get install -y curl
+      - run:
+          name: "Trigger Nurax deploy"
+          command: |
+            curl -X POST https://circleci.com/api/v2/project/gh/curationexperts/nurax/pipeline \
+            --header "Circle-Token: $NURAX_CIRCLECI_TOKEN" \
+            --header 'Accept: text/plain'    \
+            --header 'Content-Type: application/json'
 workflows:
   version: 2
   ruby2-5-8:
     jobs:
       - bundle:
           ruby_version: "2.5.8"
-          rails_version: "5.2.4.3"
+          rails_version: "5.2.6"
       - build:
           ruby_version: "2.5.8"
-          rails_version: "5.2.4.3"
+          rails_version: "5.2.6"
           requires:
             - bundle
       - test:
@@ -146,10 +169,10 @@ workflows:
     jobs:
       - bundle:
           ruby_version: "2.6.6"
-          rails_version: "5.2.4.3"
+          rails_version: "5.2.6"
       - build:
           ruby_version: "2.6.6"
-          rails_version: "5.2.4.3"
+          rails_version: "5.2.6"
           requires:
             - bundle
       - test:
@@ -163,21 +186,28 @@ workflows:
           hyrax_valkyrie: "true"
           requires:
             - build
-  ruby2-7-2:
+  ruby2-7-4:
     jobs:
       - bundle:
-          ruby_version: "2.7.2"
-          rails_version: "5.2.4.3"
+          ruby_version: "2.7.4"
+          rails_version: "5.2.6"
           bundler_version: "2.1.4"
       - build:
-          ruby_version: "2.7.2"
-          rails_version: "5.2.4.3"
+          ruby_version: "2.7.4"
+          rails_version: "5.2.6"
           bundler_version: "2.1.4"
           requires:
             - bundle
       - test:
-          name: "ruby2-7-2"
-          ruby_version: "2.7.2"
+          name: "ruby2-7-4"
+          ruby_version: "2.7.4"
           bundler_version: "2.1.4"
           requires:
             - build
+  nurax-dev_deploy:
+    jobs:
+      - deploy:
+          filters:
+            branches:
+              only:
+                - main

data/.dassie/.env

@@ -1,4 +1,3 @@
 MEMCACHED_HOST=memcached
-HYRAX_ANALYTICS=1
 REDIS_PROVIDER=SIDEKIQ_REDIS_URL
-SIDEKIQ_REDIS_URL=redis://redis:6379/0
+SIDEKIQ_REDIS_URL=redis://redis:6379/0

data/.dassie/Gemfile

@@ -1,14 +1,21 @@
-source 'https://rubygems.org'
+# frozen_string_literal: true
+# Attempts to determine if a global gem source has ready been added by another Gemfile
+if @sources.global_rubygems_source == Bundler::SourceList.new.global_rubygems_source
+  Bundler.ui.info '[Dassie] Adding global rubygems source.'
+  source 'https://rubygems.org'
+else
+  Bundler.ui.info "[Dassie] Global rubygems source already set: #{@sources.global_rubygems_source.inspect}"
+end
 git_source(:github) { |repo| "https://github.com/#{repo}.git" }
 
-ruby '2.7.2'
+ruby '2.7.4'
 
 # Bundle edge Rails instead: gem 'rails', github: 'rails/rails'
 gem 'rails', '~> 5.2.4', '>= 5.2.4.4'
 # Use postgresql as the database for Active Record
 gem 'pg', '>= 0.18', '< 2.0'
 # Use Puma as the app server
-gem 'puma', '~> 3.11'
+gem 'puma', '~> 4.3.8'
 # Use SCSS for stylesheets
 gem 'sass-rails', '~> 5.0'
 # Use Uglifier as compressor for JavaScript assets
@@ -43,15 +50,17 @@ end
 # Windows does not include zoneinfo files, so bundle the tzinfo-data gem
 gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby]
 
-begin # this is a hack to allow `eval_gemfile` to work correctly
-  gem 'hyrax', path: ENV.fetch('HYRAX_ENGINE_PATH', '..')
-rescue; end
+gemspec name: 'hyrax', path: ENV.fetch('HYRAX_ENGINE_PATH', '..')
 
-gem 'rsolr', '>= 1.0', '< 3'
 gem 'bootstrap-sass', '~> 3.0'
-gem 'twitter-typeahead-rails', '0.11.1.pre.corejavascript'
-gem 'jquery-rails'
 gem 'devise'
 gem 'devise-guests', '~> 0.6'
+gem 'jquery-rails'
+gem 'pry-byebug'
+gem 'pry-doc'
+gem 'pry-rails'
+gem 'pry-rescue'
 gem 'riiif', '~> 2.1'
+gem 'rsolr', '>= 1.0', '< 3'
 gem 'sidekiq', '~> 6.0'
+gem 'twitter-typeahead-rails', '0.11.1.pre.corejavascript'

data/.dassie/app/controllers/catalog_controller.rb

@@ -5,6 +5,8 @@ class CatalogController < ApplicationController
 
   # This filter applies the hydra access controls
   before_action :enforce_show_permissions, only: :show
+  # Allow all search options when in read-only mode
+  skip_before_action :check_read_only
 
   def self.uploaded_field
     "system_create_dtsi"
@@ -28,6 +30,10 @@ class CatalogController < ApplicationController
     config.view.gallery.partials = [:index_header, :index]
     config.view.slideshow.partials = [:index]
 
+    # Because too many times on Samvera tech people raise a problem regarding a failed query to SOLR.
+    # Often, it's because they inadvertently exceeded the character limit of a GET request.
+    config.http_method = :post
+
     ## Default parameters to send to solr for all search-like requests. See also SolrHelper#solr_search_params
     config.default_solr_params = {
       qt: "search",

data/.dassie/app/models/user.rb

@@ -5,8 +5,6 @@ class User < ApplicationRecord
   include Hyrax::User
   include Hyrax::UserUsageStats
 
-
-
   if Blacklight::Utils.needs_attr_accessible?
     attr_accessible :email, :password, :password_confirmation
   end

data/.dassie/config/analytics.yml

@@ -1,6 +1,13 @@
 analytics:
-  app_name: My App Name
-  app_version: 0.0.1
-  privkey_path: /tmp/privkey.p12
-  privkey_secret: s00pers3kr1t
-  client_email: oauth@example.org
+  google:
+    analytics_id: <%= ENV['GOOGLE_ANALYTICS_ID'] %>
+    app_name: <%= ENV['GOOGLE_OAUTH_APP_NAME'] %>
+    app_version: <%= ENV['GOOGLE_OAUTH_APP_VERSION'] %>
+    privkey_path: <%= ENV['GOOGLE_OAUTH_PRIVATE_KEY_PATH'] %>
+    privkey_secret: <%= ENV['GOOGLE_OAUTH_PRIVATE_KEY_SECRET'] %>
+    client_email: <%= ENV['GOOGLE_OAUTH_CLIENT_EMAIL'] %>
+  matomo: 
+    base_url: <%= ENV['MATOMO_BASE_URL'] %>
+    site_id: <%= ENV['MATOMO_SITE_ID'] %>
+    auth_token: <%= ENV['MATOMO_AUTH_TOKEN'] %>
+    

data/.dassie/config/environments/development.rb

@@ -29,6 +29,8 @@ Rails.application.configure do
     config.cache_store = :null_store
   end
 
+  config.web_console.whitelisted_ips = ['172.18.0.0/16', '172.27.0.0/16', '0.0.0.0/0']
+
   # Store uploaded files on the local file system (see config/storage.yml for options)
   config.active_storage.service = :local
 

data/.dassie/config/initializers/hyrax.rb

@@ -5,6 +5,8 @@ Hyrax.config do |config|
   # Defaults to false.  See README for more info
   config.arkivo_api = true
 
+  config.analytics = ActiveModel::Type::Boolean.new.cast(ENV.fetch('HYRAX_ANALYTICS', 'false'))
+  config.analytics_provider = ENV.fetch('HYRAX_ANALYTICS_PROVIDER', 'google')
   # Injected via `rails g hyrax:work GenericWork`
   config.register_curation_concern :generic_work
   # Injected via `rails g hyrax:work NamespacedWorks::NestedWork`
@@ -39,6 +41,11 @@ Hyrax.config do |config|
   ##
   # Set the system-wide virus scanner
   config.virus_scanner = Hyrax::VirusScanner
+
+  ##
+  # To index to the Valkyrie core, uncomment the following two lines.
+  # config.query_index_from_valkyrie = true
+  # config.index_adapter = :solr_index
 end
 
 Date::DATE_FORMATS[:standard] = "%m/%d/%Y"

data/.dassie/config/role_map.yml

@@ -1,4 +1,6 @@
 development:
+  admin:
+    - admin@example.com
   archivist:
     - archivist1@example.com
 

data/.dassie/db/migrate/20210921150120_enable_uuid_extension.valkyrie_engine.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+# This migration comes from valkyrie_engine (originally 20160111215816)
+class EnableUuidExtension < ActiveRecord::Migration[5.0]
+  def change
+    enable_extension 'uuid-ossp'
+  end
+end

data/.dassie/db/migrate/20210921150121_create_orm_resources.valkyrie_engine.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+# This migration comes from valkyrie_engine (originally 20161007101725)
+class CreateOrmResources < ActiveRecord::Migration[5.0]
+  def options
+    if ENV["VALKYRIE_ID_TYPE"] == "string"
+      { id: :text, default: -> { '(uuid_generate_v4())::text' } }
+    else
+      { id: :uuid }
+    end
+  end
+
+  def change
+    create_table :orm_resources, **options do |t|
+      t.jsonb :metadata, null: false, default: {}
+      t.timestamps
+    end
+    add_index :orm_resources, :metadata, using: :gin
+  end
+end

data/.dassie/db/migrate/20210921150122_add_model_type_to_orm_resources.valkyrie_engine.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+# This migration comes from valkyrie_engine (originally 20170124135846)
+class AddModelTypeToOrmResources < ActiveRecord::Migration[5.0]
+  def change
+    add_column :orm_resources, :resource_type, :string
+  end
+end

data/.dassie/db/migrate/20210921150123_change_model_type_to_internal_model.valkyrie_engine.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+# This migration comes from valkyrie_engine (originally 20170531004548)
+class ChangeModelTypeToInternalModel < ActiveRecord::Migration[5.1]
+  def change
+    rename_column :orm_resources, :resource_type, :internal_resource
+  end
+end

data/.dassie/db/migrate/20210921150124_create_path_gin_index.valkyrie_engine.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+# This migration comes from valkyrie_engine (originally 20171011224121)
+class CreatePathGinIndex < ActiveRecord::Migration[5.1]
+  def change
+    add_index :orm_resources, 'metadata jsonb_path_ops', using: :gin
+  end
+end

data/.dassie/db/migrate/20210921150125_create_internal_resource_index.valkyrie_engine.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+# This migration comes from valkyrie_engine (originally 20171204224121)
+class CreateInternalResourceIndex < ActiveRecord::Migration[5.1]
+  def change
+    add_index :orm_resources, :internal_resource
+  end
+end

data/.dassie/db/migrate/20210921150126_create_updated_at_index.valkyrie_engine.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+# This migration comes from valkyrie_engine (originally 20180212092225)
+class CreateUpdatedAtIndex < ActiveRecord::Migration[5.1]
+  def change
+    add_index :orm_resources, :updated_at
+  end
+end

data/.dassie/db/migrate/20210921150127_add_optimistic_locking_to_orm_resources.valkyrie_engine.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+# This migration comes from valkyrie_engine (originally 20180802220739)
+class AddOptimisticLockingToOrmResources < ActiveRecord::Migration[5.1]
+  def change
+    add_column :orm_resources, :lock_version, :integer
+  end
+end

data/.dassie/db/migrate/20211130181150_create_default_administrative_set.rb

@@ -0,0 +1,8 @@
+class CreateDefaultAdministrativeSet < ActiveRecord::Migration[5.2]
+  def change
+    create_table :hyrax_default_administrative_set do |t|
+      t.string :default_admin_set_id, null: false
+      t.timestamps null: false
+    end
+  end
+end

data/.dassie/db/schema.rb

@@ -10,10 +10,11 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema.define(version: 2020_08_21_212903) do
+ActiveRecord::Schema.define(version: 2021_11_30_181150) do
 
   # These are extensions that must be enabled in order to support this database
   enable_extension "plpgsql"
+  enable_extension "uuid-ossp"
 
   create_table "bookmarks", id: :serial, force: :cascade do |t|
     t.integer "user_id", null: false
@@ -139,6 +140,12 @@ ActiveRecord::Schema.define(version: 2020_08_21_212903) do
     t.index ["machine_id"], name: "index_hyrax_collection_types_on_machine_id", unique: true
   end
 
+  create_table "hyrax_default_administrative_set", force: :cascade do |t|
+    t.string "default_admin_set_id", null: false
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
+  end
+
   create_table "hyrax_features", force: :cascade do |t|
     t.string "key", null: false
     t.boolean "enabled", default: false, null: false
@@ -225,6 +232,18 @@ ActiveRecord::Schema.define(version: 2020_08_21_212903) do
     t.index ["namespace"], name: "index_minter_states_on_namespace", unique: true
   end
 
+  create_table "orm_resources", id: :uuid, default: -> { "uuid_generate_v4()" }, force: :cascade do |t|
+    t.jsonb "metadata", default: {}, null: false
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
+    t.string "internal_resource"
+    t.integer "lock_version"
+    t.index ["internal_resource"], name: "index_orm_resources_on_internal_resource"
+    t.index ["metadata"], name: "index_orm_resources_on_metadata", using: :gin
+    t.index ["metadata"], name: "index_orm_resources_on_metadata_jsonb_path_ops", opclass: :jsonb_path_ops, using: :gin
+    t.index ["updated_at"], name: "index_orm_resources_on_updated_at"
+  end
+
   create_table "permission_template_accesses", force: :cascade do |t|
     t.bigint "permission_template_id"
     t.string "agent_type"

data/.dassie/db/seeds.rb

@@ -6,7 +6,7 @@
 #   movies = Movie.create([{ name: 'Star Wars' }, { name: 'Lord of the Rings' }])
 #   Character.create(name: 'Luke', movie: movies.first)
 
-Hyrax::Engine.load_seed
+Hyrax::Engine.load_seed unless ActiveModel::Type::Boolean.new.cast(ENV["SKIP_HYRAX_ENGINE_SEED"])
 
 puts "\n== Loading users"
 User.where(email: 'admin@example.com').first_or_create do |f|

data/.dockerignore

@@ -10,3 +10,6 @@ Dockerfile
 artifacts/*
 coverage/*
 chart/*
+
+Gemfile.lock
+.dassie/Gemfile.lock

data/.env

@@ -1,15 +1,17 @@
-CAPYBARA_SERVER=http://app:3010
+ANALYTICS_START_DATE=2021-08-21
 CHROME_HEADLESS_MODE=false
 DATABASE_CLEANER_ALLOW_REMOTE_DATABASE_URL=true
 DATABASE_TEST_URL=postgresql://hyrax_user:hyrax_password@postgres/hyrax_test?pool=5
 DATABASE_URL=postgresql://hyrax_user:hyrax_password@postgres/hyrax?pool=5
-DB_PORT=5432
 DB_HOST=postgres
-FCREPO_PORT=8080
+DB_PORT=5432
 FCREPO_HOST=fcrepo
-FCREPO_REST_PATH=fcrepo/rest
+FCREPO_PORT=8080
+FCREPO_REST_PATH=rest
 FCREPO_TEST_BASE_PATH=/test
 HUB_URL=http://chrome:4444/wd/hub
+HYRAX_ANALYTICS=false
+HYRAX_ANALYTICS_PROVIDER=google
 HYRAX_DERIVATIVES_PATH=/app/samvera/hyrax-webapp/derivatives/
 HYRAX_ENGINE_PATH=/app/samvera/hyrax-engine
 HYRAX_UPLOAD_PATH=/app/samvera/hyrax-webapp/uploads/
@@ -18,9 +20,9 @@ RACK_ENV=development
 RAILS_ENV=development
 RAILS_ROOT=.dassie
 REDIS_HOST=redis
-SOLR_PORT=8983
 SOLR_HOST=solr
+SOLR_PORT=8983
 SOLR_TEST_URL=http://solr:8983/solr/hyrax_test
 SOLR_URL=http://solr:8983/solr/hyrax
-VALKYRIE_SOLR_PORT=8983
 VALKYRIE_SOLR_HOST=solr
+VALKYRIE_SOLR_PORT=8983

data/.github/workflows/main.yml

@@ -0,0 +1,17 @@
+name: Trigger Nurax build
+on:
+  workflow_dispatch:
+  push:
+
+jobs:
+  trigger:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: peter-evans/repository-dispatch@v1
+      with:
+         token: ${{ secrets.NURAX_ACCESS_TOKEN }}
+         event-type: push
+         repository: curationexperts/nurax
+         client-payload: '{"ref": "${{ github.ref }}", "sha": "${{ github.sha }}"}'
+
+

data/.github/workflows/release.yml

@@ -0,0 +1,17 @@
+name: Trigger Nurax build
+on:
+  workflow_dispatch:
+  release:
+
+jobs:
+  trigger:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: peter-evans/repository-dispatch@v1
+      with:
+         token: ${{ secrets.NURAX_ACCESS_TOKEN }}
+         event-type: release
+         repository: curationexperts/nurax
+         client-payload: '{"ref": "${{ github.ref }}", "sha": "${{ github.sha }}"}'
+
+

data/.gitignore

@@ -82,3 +82,4 @@ lib/bundler/man
 spec/reports
 /spec/examples.txt
 node_modules
+.env.*

data/.regen

@@ -1 +1 @@
-36
+40

data/.rubocop.yml

@@ -41,6 +41,10 @@ Metrics/BlockLength:
 Style/AsciiComments:
   Enabled: false
 
+# rubocop suggests !thing.nil? instead, but that is NOT equivalent
+Style/DoubleNegation:
+  Enabled: false
+
 Style/CollectionMethods:
   PreferredMethods:
     collect: 'map'

data/CONTAINERS.md

@@ -1,14 +1,11 @@
 Hyrax-in-a-Container
 ====================
 
-Our goal is to provide a practical, reusable "reference environment for applications.  The first step is providing
-on on-ramp for Hyrax engine development.  Then providing help with Hyrax-based application development.  Finally,
-providing better guidance around deployment.
+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.
 
-Where are we at?  It's complicated.  What we have below is experimental support, but one that we want to push
-towards.  We need your help to keep pushing in this direction.  So dig in and prepare to get your hands dirty.
+The [Hyrax Engine Development](#hyrax-engine-development) is further along than the [Docker Image for Hyrax-based Applications](#docker-image-for-hyrax-based-applications) which is further along than [Deploying to Production](#deploying-to-production).
 
-The [Hyrax Engine Development](#hyrax-engine-development) is further along than the [Docker Image for Hyrax-based Applications](docker-image-for-hyrax-based-applications) which is further along than [Deploying to Production](#deploying-to-production).
+See the [Troubleshooting](#troubleshooting) section if you encounter any issues.
 
 <!-- NOTE: This title is referenced in the top-level README.md. Keep that in mind if you change it. -->
 ## Hyrax Engine Development
@@ -42,8 +39,6 @@ To stop the containers for the Hyrax-based application, type <kbd>Ctrl</kbd>+<kb
 
 _**Note:** Starting and stopping Docker in this way will preserve your data between restarts._
 
-_**Note:** I (Jeremy) encountered a problem using `docker-compose build`. I ran `bundle update` in `./hyrax` as well as within `./hyrax/.dassie`. That appeared to clear up the problem of a failure to build a gem._
-
 ### Code Changes and Testing
 
 With `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).
@@ -99,7 +94,7 @@ In the two examples, note the difference in the `-w` switch. In the first case,
 
 ### Debugging
 
-I (Jeremy) find myself wanting to debug the application.  This requires a somewhat different approach than running Hyrax bare-metal.  You need to use `docker attach` to debug the running docker instance.
+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.
 
 1. With `docker-compose up` running open a new Terminal session.
 2. In that new Terminal session, using `docker container ls` find the "CONTAINER ID" for the `hyrax-engine-dev`.
@@ -107,6 +102,34 @@ I (Jeremy) find myself wanting to debug the application.  This requires a somewh
 
 This advice comes from [Debugging Rails App With Docker Compose: How to use Byebug in a dockerized rails app](https://medium.com/gogox-technology/debugging-rails-app-with-docker-compose-39a3767962f4).
 
+### Troubleshooting
+
+#### Bad Address SOLR
+
+With `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` or `./hyrax/.dassie` and run `docker-compose build` again, then `docker-compose up` again.
+
 <!-- NOTE: This title is referenced in the top-level documentation/developing-your-hyrax-based-app.md. Keep that in mind if you change it. -->
 ## Docker Image for Hyrax-based Applications
 
@@ -157,4 +180,4 @@ helm dependency update chart/hyrax
 helm install -n hyrax --set image.tag=(git rev-parse HEAD) dassie chart/hyrax
 ```
 
-[dockerhub-samveralabs]: https://hub.docker.com/r/samveralabs
+[dockerhub-samveralabs]: https://hub.docker.com/r/samveralabs