An implementation of the Blacklight Search platform.
We'll run the Rails app locally, but the databases (MySQL, Redis, and Solr) are containerized.
Install Docker and Docker Compose Install Docker Compose
Copy the .env-example file
cp .env-example .env
Once this file has been copied, you will need to legitimize the values of the various environment variables it contains. Check with Paul Swanson to get real values for variables that have placeholders.
Install Ruby 3.1.2 via rbenv
brew install rbenv ruby-build
rbenv init
rbenv install 3.1.2
Install MySQL and Redis clients, as well as geckodriver for system tests run via Selenium.
brew install mysql@5.7 redis geckodriver tesseract
Install Nginx and mkcert (for local SSL)
brew install nginx
brew install mkcert
brew install nss # If you use Firefox
Install a local SSL cert
mkcert -install # Will ask for sudo password
mkcert mdl.devlocal
mkdir -p certs
mv mdl.devlocal* ./certs/
Install the Nginx config
./bin/install_nginx_conf
Start Nginx
sudo brew services start nginx
Install Node via NVM (or preferred alternative)
nvm install 20
Install Yarn
npm i -g yarn
Run the setup script (builds Docker images for dependencies)
./local-dev-init.sh
Start Sidekiq
./start_sidekiq.sh 'default -q iiif_search -q critical,2'
Ingest some content
INGEST_ALL=1 bundle exec rake 'mdl_ingester:collection[p15160coll13]'
INGEST_ALL=1 bundle exec rake 'mdl_ingester:collection[p16022coll10]'
Start the rails server
bundle exec rails s
You can login by visiting https://mdl.devlocal/users/sign_in
username: local@example.com password: password
Enter an interactive session with the application (must be running in another tab):
$ bundle exec rails console
- [MySQL] If you run into issues with the database, try removing and recreating the db volumes:
$ docker-compose down -v; docker-compose up
When you update certain frontend elements of the app, you'll need to rebuild the webpacker image. Things like adding a new "pack" (entrypoint), adding or removing dependencies, and updating the version of NodeJS all require rebuilding the image. Here's how you do it:
-
Find the container ID of the webpacker container
docker ps -qa -f name=webpacker
-
If it's running, stop it
docker stop $CONTAINER_ID
-
remove the container:
docker rm $CONTAINER_ID
-
Find the image(s)
docker images mdl_search_webpacker -q
-
Remove the images
docker rmi $IMAGE_ID
-
Build the new image (assuming you're done making changes for now)
docker-compose build webpacker
-
Run the container
docker-compose up -d webpacker
###
# Full suite
bundle exec rspec
###
# Single directory
bundle exec rspec spec/features/
###
# Single file
bundle exec rspec spec/lib/borealis_image_spec.rb
We have separate Docker containers for development and test environments so that you can run tests without worrying about affecting your local development data.
- "How to I add/remove/change X feature in the UI?"
- MDL Search makes use of a Rails Engine called "Blacklight". Rails engines are like little Rails apps that you override within your own app. If there is a UI feature you want to alter or remove, you may need to hunt around a bit in Blacklight to find it. Tip: browse the HTML source of the feature you are looking for and search the Blacklight view codebase (for your specific version) for small unique html snippets from the interface; sometimes you'll get lucky. Other times, you may have to browse through template render calls until you find what you are looking for.
# Note: you might consider adding aliases (shortcuts) in your shell env to make it easier to run these commands. e.g.:
# alias dps='docker ps -a'
# Show all docker images
$ docker ps -a
# Force Remove all MDL images
$ docker-compose stop; docker rmi -f $(docker images -q --filter="reference=mdl*")
# Remove all inactive Docker images (ones that have "Exited")
$ docker rm $(docker ps -a | grep Exited | awk '\''BEGIN { FS=" " } ; {print $1;}'\'')
# CAREFUL! Scorched earth! remove all Docker images
$ docker rmi $(docker images | grep "^<none>" | awk "{print $3}")
This is especially useful for analyzing containers to see why they are the size that they are and finding ways to slim them down.