Skip to content

README-docker-dev.md

Latest commit

 

History

History
127 lines (80 loc) · 4 KB

README-docker-dev.md

File metadata and controls

127 lines (80 loc) · 4 KB

SDBM — Local Docker Development

Prerequisites

  • Docker Desktop (macOS) or Docker Engine (Linux)
  • Ruby (to run bin/tools)
  • A .env file (see below)
  • sdbmss.localhost in /etc/hosts (see below)

bin/tools is used instead of rake because rake task execution is not practical on macOS Apple silicon with this project's legacy Ruby/Rails constraints.

Important: Do not edit docker-compose.yml manually.

It is generated by scripts/generate_dev_compose.py from scripts/generate_dev_compose.yml. Edit those files instead.

First-time setup

1. Create .env

From the rails_app/ directory:

cp docker-environment-sample .env

Edit .env for your environment.

2. Add /etc/hosts entry

Note: The following is required on macOS. It may not be needed on Linux.

Add the line below to /etc/hosts.

127.0.0.1 sdbmss.localhost

To edit the hosts file you'll need to be super user or use sudo (e.g., sudo vi /etc/hosts).

3. Get data files

The development environment relies on these static and database files:

  • sdbm_data.tgz (120 MB)
  • sdbm.sql.gz (6.3 MB)

Contact Penn Libraries' Digital Library Development team for copies.

Penn Libraries staff can access the files here (permission required): SDBM Data on SharePoint.

Place them in rails_app/dev/data/.

Optional: override the default archive paths via environment variables in .env:

  • SDBM_DATA_ARCHIVE=/path/to/sdbm_data.tgz
  • SDBM_SQL_ARCHIVE=/path/to/sdbm.sql.gz

4. Start the stack

From rails_app/:

bin/tools start

Builds any missing custom images, then starts all services. Waits for HTTP 200 on $SDBMSS_APP_HOST before returning, and runs host diagnostics for /etc/hosts mapping and connectivity issues.

5. Run setup

bin/tools setup

This loads the database, copies static assets, adds test users, reindexes Solr, and loads Jena. Takes about 5 minutes.

6. Confirm

Go to http://sdbmss.localhost. Log in as admin / testpassword.

Daily use

Command What it does
bin/tools start Start all services
bin/tools stop Stop all services (volumes preserved)
bin/tools clean Remove services and volumes
bin/tools clean --all Remove services, volumes, and custom images
bin/tools rebuild Rebuild all custom images (no start)
bin/tools start --force-rebuild Rebuild custom images before starting

All commands run from rails_app/.

Running tests

Tests run inside the app container:

docker exec -it sdbmss-app-1 bash
RAILS_ENV=test bundle exec rspec

Skip JS tests for a faster run: bundle exec rspec --tag ~js

The full suite takes about 14 minutes.

Docker compose services

The services defined in docker-compose.yml are:

  1. The SDBM Rails app
  2. Solr
  3. MySQL
  4. RabbitMQ -- queue for Jena updates
  5. Jena Fuseki -- RDF/SPARQL server; built from https://github.com/upenn-libraries/Jena-Fuseki
  6. Delayed Job -- background job processing (Rails image)
  7. Interface -- service for updating Jena (listens to RabbitMQ queue); built from https://github.com/upenn-libraries/sdbm-interface
  8. Traefik -- reverse proxy
  9. Chrome -- development-only headless browser for specs

Generating the docker compose file

Edit scripts/generate_dev_compose.yml (service configuration), then run scripts/generate_dev_compose.py to regenerate docker-compose.yml.

AI Usage Disclosure: Reviewed, revised, and extended by Claude Sonnet 4.6 (Anthropic).