A Hyrax app for GW Libraries with:
The public application is accessible at https://scholarspace.library.gwu.edu/
Some convenient links to have handy:
The Dockerized version of the ScholarSpace app uses the following images:
Component | Image Name | Version | Source |
---|---|---|---|
Fedora server | ghcr.io/samvera/fcrepo4 | 4.7.5 | https://github.com/samvera-labs/docker-fcrepo |
Postgres (for Fedora) | postgres | 15.4 | https://hub.docker.com/_/postgres |
Postgres (for Hyrax) | postgres | 9.5.25-alpine | https://hub.docker.com/_/postgres |
Solr | library/solr | 6.4.2-alpine | Dockerfile-solr |
Rails app | scholarspace-app | -- | Dockerfile |
Redis server | redis | 5-alpine | https://hub.docker.com/_/redis |
Sidekiq | scholarspace-app | -- | Dockerfile |
docker-fcrepo
repository. config/initializers/hyrax.rb
have been refactored to use environment variables where possible in order to minimize manual configuration. When loading code from outside the container, such files will be overwritten by their external counterparts.docker/scripts/scholarspace-setup.sh
): creating the scholarspace user and group, setting permissions, and creating a cron job for the sitemap generation.docker exec --user scholarspace [container-name] bash -l
. (Setting the scholarspace
user and running bash -l
are necessary to ensure that the RVM paths load correctly.)/etc/group
and add your user (e.g., ubuntu
) to the docker
group.id $USER
and note the values for uid
and gid
. Below you will add those to the .env
file. Note: You can create
a separate user for the app, but it is not necessary. That user will need to own /opt/scholarspace and subdirectories.opt/scholarspace
directory and clone the scholarspace-hyrax
repository inside it. mkdir -p /opt/scholarspace/scholarspace-derivatives
.
/opt/scholarspace/certs
/opt/scholarspace/scholarspace-tmp
/opt/scholarspace/scholarspace-minter
/opt/scholarspace/scholarspace-ingest
/opt/scholarspace/scholarspace-hyrax
run cp example.env .env
to create the local environment file..env
to add the following values:
#Recaptch config
commenttrue
if using)SSL_
variables (if using).env
file, set the ReCAPTCHA API keys:
RECAPTCHA_SITE_KEY=
RECAPTCHA_SECRET_KEY=
.env
as needed.docker-compose.yml
as necessary.
app-server
service definition./opt/scholarspace/fedora-data
and /opt/scholarspace/solr-data
directories to store the Fedora files on the host (e.g, sudo mkdir -p /opt/scholarspace/fedora-data
). Grant permissions on the Solr directory to the Solr user: sudo chown -R 8983:8983 /opt/scholarspace/solr-data
docker compose up -d
. This will build the Hyrax app/Sidekiq and Solr images locally and start all containers. Note that the app is not yet ready to view and there may be some errors in the log at this point. If you get an authentication error, see the section on authenticating to the GitHub Container Registry below. SECRET_KEY_BASE
being set in the .env
file. To generate a secret key using Rails, run docker exec -it --user scholarspace [app-server-container-name] bash -lc "docker/scripts/app-init.sh --create-secret"
. The app-server-container-name
is probably scholarspace-hyrax-app-server-1
but can be ascertained by running docker ps
..env
file and restart the containers: docker compose down && docker compose up -d
.docker exec -it --user scholarspace [app-server-container-name] bash -lc "docker/scripts/app-init.sh --run-migrations"
.
docker exec -it --user scholarspace [app-server-container-name] bash -lc "rails db:{drop,create,migrate,seed}"
docker exec -it --user scholarspace [app-server-container-name] bash -lc "docker/scripts/app-init.sh --apply-content-blocks --precompile-assets"
.docker exec [app-container-name] bash -lc "passenger-config restart-app /"
. app-init.sh
script:
--create-roles
: create default app roles (if they don't already exist)--create-admin-set
: create the default Admin Set, if it doesn't already exist--add-admin-user
: grant a ScholarSpace user the admin
role. To use: first, create the user in the ScholarSpace UI. Then run this command, inserting an environment variable (admin_user=USER_EMAIL_ADDRESS
) before the path to the script. This environment variable will be used by the Rake task to look up the user in the app database. docker exec -it --user scholarspace [app-container-name] bash -lc "docker/scripts/app-init.sh --create-sitemap"
. With default configurations, this job will run every morning at 12:30 AM, or can be configured in config/schedule.rb
to run on a different schedule.For convenience with prod deployments, use the redeploy script:
sudo chmod u+x script/redeploy-app.sh
./script/redeploy-app.sh
This script will perform the following actions:
It will still be necessary to restart the app container after visiting the site (in order to the compiled assets to be visible).
The ScholarSpace app and Solr Docker images are hosted on GitHub's Container Registry. Since the images are not public (by GW policy), pulling images from the registry requires user authentication with a personal access token.
write:packages
or (minimally) read:packages
permission.export CR_PAT=[YOUR_TOKEN]
echo $CR_PAT | docker login ghcr.io -u [USERNAME] --password-stdin
docker compose up -d
./opt/scholarspace/solr-data
on the Docker host. chown -R 8983:8983 /opt/scholarspace/solr-data
docker-compose.yml
file, e.g., /data/fedora
. pg-fcrepo
(Fedora) and pg-hyrax
. Repeat these steps for each container. Each container uses a separate Docker volume: db
and db-hyrax
, respectively.docker cp [db-backup-file.sql] [db-container-name]:/tmp
. This puts it in the /tmp directory inside the container.docker exec -it [db-container-name] /bin/bash
.template0
. (Restoring with the default template may cause errors.)dropdb -U fedoraproduser fcrepo && createdb -U fedoraproduser -T template0 fcrepo
dropdb -U scholarspace gwss_prod && createdb -U scholarspace -T template0 gwss_prod
psql -U [scholarspace|fedoraproduser] -d [gwss_prod|fcrepo]
< [db-backup-file.sql]In the app-server container (i.e. through docker exec -it scholarspace-hyrax_app-server_1 /bin/sh
, followed by su scholarspace
), run:
bundle exec rails db:migrate RAILS_ENV=production
In the app-server container (i.e. through docker exec -it scholarspace-hyrax_app-server_1 /bin/sh
, followed by su scholarspace
), run this rake task - replacing email and password with your new admin user email and password:
bundle exec rails gwss:prep_new_prod RAILS_ENV=production admin_user="AN-EMAIL-ADDRESS@EXAMPLE.COM" admin_password="A-PASSWORD"
This will create the admin and content-admin roles, create an admin user with the specified email and password, create the default admin sets, and create an ETDs
admin set with the admin user as the owner.
In addition, this task will precompile assets for production.
docker-compose.yml
uses Docker volumes to persist storage for the Postgres databases.script/redeploy-app.sh
from the /opt/scholarspace/scholarspace-hyrax
directory (after making that script executable). This script will bring down all containers, delete the scholarspace-app
image, delete the app-hyrax
volume, and then restart all containers, rebuilding the image in the process. This script will also precompile the assets for the app as a last step.~/.bashrc
file, using the docker ps
command to identify the app container, like so:
alias hyrax-container='docker exec -it --user scholarspace $(docker ps --filter "name=app" -q) bash -l'
alias restart-hyrax='docker exec $(docker ps --filter 'name=app' -q) bash -lc "passenger-config restart-app /"'
#!/bin/bash
echo "Recreating Fedora and Solr directories" rm -r /data/fedora && mkdir /data/fedora rm -r /var/solr/data && mkdir /var/solr/data && chown -R 8983:8983 /var/solr/data echo "Cleaning up ScholarSpace files" rm -r /opt/scholarspace/scholarspace-derivatives/derivatives echo "Removing Docker volumes" docker volume rm $(docker volume ls -q)
After bringing down the containers, run this script (with `sudo`) to clear out all persistent storage, including the Rails database, before bringing back up the containers.
# Development Mode
### Preparing Development Databases
NOTE: The following steps assume that Docker containers have launched successfully and are currently running.
To prepare a development server:
- Run `docker exec -it scholarspace-hyrax_app-server_1 /bin/sh`
- This will give you access to an interactive terminal (`-it`) in the container with the Rails application.
- Switch to the in-container "scholarspace" user with `su scholarspace`
- Run:
- `bundle exec rails db:create` to create the `development` and `test` databases.
- `bundle exec rails db:migrate` to run the database migrations for the `development` and `test` databases.
- `bundle exec rails db:seed` to create (in the `devleopment` environment):
- An admin role and user (email and password set in `.env`)
- A content admin role and user (email and password set in `.env`)
- The default admin set
- The admin set collection type
- The user collection type
- An `ETDs` admin set
### Running a Development Application
From a terminal attached to the Rails application container (i.e. through `docker exec -it scholarspace-hyrax_app-server_1 /bin/sh`), run:
- `bundle exec rails s -b 0.0.0.0`
This command starts a Passenger/NGINX server running Rails in `development` mode on port 3000, accessible at:
- http://YOUR-EC2-INSTANCE-URL.compute.amazonaws.com:3000 (assuming AWS security groups have been configured to allow traffic on port 3000)
As you interact with the `development` application in a browser, the logs will output to the terminal where you ran the `bundle exec rails s -b 0.0.0.0` command, with a `debug` level of detail.
To stop the `development` server, press `ctrl + c` in the terminal where you ran the command to start the server. You can restart the development application, and previous changes (i.e. deposited works, created collections, etc) should persist.