diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..c4a6a30 --- /dev/null +++ b/Makefile @@ -0,0 +1,45 @@ +COMPOSE_DEV = docker compose -f docker-compose.yml -f docker-compose.dev.override.yml + +.PHONY: help dev build down test lint lint-fix check logs test-watch findingaid-sh web-sh sample + +help: ## Show this help + @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}' + +dev: ## Start development environment + $(COMPOSE_DEV) up -d + +build: ## Build containers + $(COMPOSE_DEV) build + +down: ## Stop all containers + $(COMPOSE_DEV) down + +test: ## Run PHPUnit tests + $(COMPOSE_DEV) exec findingaid /opt/findingaid/vendor/bin/phpunit -c /opt/findingaid/phpunit.xml /opt/findingaid/tests + +lint: ## Run PHP_CodeSniffer (PSR-12) + $(COMPOSE_DEV) exec findingaid /opt/findingaid/vendor/bin/phpcs -w --exclude=Generic.Files.LineLength --standard=PSR12 /opt/findingaid/tests /opt/findingaid/app + +lint-fix: ## Auto-fix PHP_CodeSniffer violations (PSR-12) + $(COMPOSE_DEV) exec findingaid /opt/findingaid/vendor/bin/phpcbf --exclude=Generic.Files.LineLength --standard=PSR12 /opt/findingaid/tests /opt/findingaid/app + +check: ## Run linter and tests reports + make lint + make test + +logs: ## Tail container logs + $(COMPOSE_DEV) logs -f + +test-watch: ## Run tests on each file change (requires: watchexec) + watchexec -w app -w public -w tests --no-process-group 'make test' + +sample: ## Download and extract sample finding aid data (~1GB) + wget -O xml.tar.gz https://solrindex.uky.edu/fa/findingaid/xml.tar.gz + tar zxf xml.tar.gz + rm xml.tar.gz + +findingaid-sh: ## Shell into the findingaid container + $(COMPOSE_DEV) exec findingaid sh + +web-sh: ## Shell into the web container + $(COMPOSE_DEV) exec web sh diff --git a/README.md b/README.md index e36a77f..e11ae7c 100644 --- a/README.md +++ b/README.md @@ -1,98 +1,92 @@ -findingaid -========== +## findingaid This is a finding aid viewer intended to be used as part of a digital library. It is written to run on Linux and has not been tested with other operating systems, but should run on most Unix-like operating systems. -Caveat ------- +## Caveat -This is written specifically for the University of Kentucky Libraries and includes -some highly local assumptions. You are welcome to use and reuse this code according -to the terms of the license, but you should be aware of its opinionated nature. +This is written specifically for the University of Kentucky Libraries and +includes some highly local assumptions. You are welcome to use and reuse this +code according to the terms of the license, but you should be aware of its +opinionated nature. -Dependencies ------------- +## Developer installation -* [Composer](https://getcomposer.org) +Developer installations have been tested on Linux (through Windows with +[WSL](https://learn.microsoft.com/en-us/windows/wsl/)) and macOS. -* [JSMin](https://github.com/douglascrockford/JSMin) +### Quickstart -Installation ------------- +```shell +git clone https://github.com/uklibraries/findingaid.git +cd findingaid +make sample +make dev +``` -1. Install the dependencies. +The application should then be available at `http://localhost:8080/`. +Developers should run `make help` to see a list of helper commands through +[make](https://www.gnu.org/software/make/). -2. Extract the repository. +### Dependencies - ```shell - git clone https://github.com/uklibraries/findingaid.git /path/to/findingaid - ``` +We use [Docker](https://www.docker.com/) for reproducible environments. +Developers will want to consult the +[docker documentation for installation](https://docs.docker.com/engine/install/). +We make use of [make](https://www.gnu.org/software/make/) to manage commands, +which is a standard Linux utility and an old (but functional) version is +included with macOS. Developers can also optionally use +[watchexec](https://github.com/watchexec/watchexec) to run tests on every file +change, which will require separate installation. [Homebrew](https://brew.sh/) +is a recommended package manager that works for both Linux and macOS. Using +Docker requires access to a Linux kernel. Mac users should consider using +[Colima](https://github.com/abiosoft/colima) to access a Linux kernel. Windows +users should strongly consider working in WSL. -3. Descend into the findingaid repository. +``` +# macOS +brew install docker - ```shell - cd /path/to/findingaid - ``` +# macOS optional +brew install make watchexec +``` -4. Use Composer to install needed packages. +### Sample data -5. Generate minified JavaScript. +Finding aids must be arranged in a +[PairTree](https://confluence.ucop.edu/display/Curation/PairTree) hierarchy in +the `xml` directory. The files are not pure EAD, but must be preprocessed using +a different program. For an example, install the +[sample data](https://exploreuk.uky.edu/fa/findingaid/xml.tar.gz) (which expands +to just shy of a gigabyte): - ```shell - bash exe/build.sh - ``` +```shell +make sample +``` -6. Install your finding aid data set in the xml directory. The finding aids -must be arranged in a -[PairTree](https://confluence.ucop.edu/display/Curation/PairTree) hierarchy. -The files are not pure EAD, but must be preprocessed using a different -program. For an example, install the -[sample data](https://exploreuk.uky.edu/fa/findingaid/xml.tar.gz) -(which expands to just shy of a gigabyte): +## Coding standard - ```shell - wget https://solrindex.uky.edu/fa/findingaid/xml.tar.gz - tar zxf xml.tar.gz - ``` +This program attempts to adhere to the +[PSR-12](https://www.php-fig.org/psr/psr-12/) coding standard for all PHP code. +For convenience, the dev environment provides +[PHP_CodeSniffer](https://github.com/PHPCSStandards/PHP_CodeSniffer/), which +detects and can repair many PSR-12 violations. Developers can use `make lint` to +get a report of linting violations, and `make lint-fix` to fix those that can be +automatically fixed. These deliberately exclude line length as a fix. -7. Create the cache directory. This must be writeable by your web server. +## Copyright - ```shell - mkdir public/cache - chown apache:apache public/cache # or appropriate similar command - ```` - -8. Connect the public directory to your website. For example, if your -website uses `/var/www/html` as its document root and permits symlinks, then -the following commands should make the finding aid viewer accessible. Some -commands might require you to become root. - - ```shell - cd /var/www/html - ln -s /path/to/findingaid/public ./findingaid - ``` - -Installation with Docker ------------------------- -If your usecase is development, the docker-compose.yml file will start an NGINX container with the appropriate volumes for development. - -Once your findingaids are installed, use `docker compose up` to start your development environment. - -Copyright ---------- - -This program is Copyright (C) 2016-2024 MLE Slone. For details, consult -LICENSE.txt. +This program is Copyright (C) 2016-2024 MLE Slone. For +details, consult LICENSE.txt. This program uses the following libraries: -* Luis Almeida's [unveil.js](https://github.com/luis-almeida/unveil) -* John Dyer's [MediaElement.js](http://mediaelementjs.com) -* Marcus Ekwall's [reveal.js](http://stackoverflow.com/a/7031800/237176) -* Justin Hileman's [Mustache.php](https://github.com/bobthecow/mustache.php) -* Jan Sorgalla's [Lity](http://sorgalla.com/lity/) -* [Bootstrap](https://getbootstrap.com) -* [jQuery](https://jquery.org) -* [jQuery UI](https://jqueryui.com) +- Luis Almeida's [unveil.js](https://github.com/luis-almeida/unveil) +- John Dyer's [MediaElement.js](http://mediaelementjs.com) +- Marcus Ekwall's [reveal.js](http://stackoverflow.com/a/7031800/237176) +- Justin Hileman's [Mustache.php](https://github.com/bobthecow/mustache.php) +- Jan Sorgalla's [Lity](http://sorgalla.com/lity/) +- [Bootstrap](https://getbootstrap.com) +- [jQuery](https://jquery.org) +- [jQuery UI](https://jqueryui.com)