This is the main portion of the ExploreUK web application. Document data is pulled from Solr. Deploying to production is managed in the ukl-ansible-playbooks repository.
Developer installations have been tested on Linux (through Windows with WSL) and macOS.
git clone git@github.com:uklibraries/exploreuk-web-app.git
cd exploreuk-web-app
git submodule update --init
make env
make dev
The application should then be available at http://localhost:8080. Developers
should run make help to see helper commands through
make. There is a
git submodule that is
loaded on initialization in the assets directory, so new developers do not
need to source assets for installation. Its shared/ directory holds images
also used by findingaid; it is
copied into the Docker image at build time and served from /assets/shared/.
We use Docker for reproducible environments. Developers will want to consult the docker documentation for installation. We make use of make to manage commands, which is a standard Linux utility and an old (but functional) version is included with macOS. Developers can also use watchexec to run tests on every file change, which will require separate installation. Homebrew 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 to access a Linux kernel. Windows users should strongly consider working in WSL.
# macOS
brew install docker
# macOS optional
brew install make watchexec
nginx/default.conf is provided as an example configuration for development.
Developers are expected to create their own .env files for new environments,
including a .env.dev for development purposes. An .env.example file is
provided as a template for environment files, and the repo includes .env.ci
for continuous integration. Developers can choose to copy and edit
.env.example or run make env to generate a .env.dev file from the
template.
docker-compose.yml is the shared base and deliberately declares no env_file,
so it does not depend on any untracked file. Each environment supplies its own
through a compose file that is
merged
onto the base: docker-compose.dev.override.yml points at .env.dev and
docker-compose.ci.override.yml points at .env.ci. Note that Compose appends
rather than replaces list fields such as env_file when merging, which is why
the base leaves it empty. A production file can be found in the
ukl-ansible-playbooks
repository.
The make targets export COMPOSE_FILE so the base and dev override are always
loaded together. Developers invoking Compose directly need to do the same:
docker compose -f docker-compose.yml -f docker-compose.dev.override.yml up -d
# or
export COMPOSE_FILE=docker-compose.yml:docker-compose.dev.override.yml
docker compose up -d
There is a service, findingaid, which is an integration with ExploreUK's
associated application, findingaid.
Its inclusion in the development environment is optional. Developers wishing to
include this application in dev should follow the docker installation
instructions in the findingaid repo, set the environment variable FA_IMAGE to
the name of a locally built findingaid image or a URL to the desired image, and
then use the make dev-fa command. The xml directory will be gitignored.
# Run ExploreUK with a findingaid image
FA_IMAGE="findingaid:local" make dev-fa
This program attempts to adhere to the
PSR-12 coding standard for all PHP code.
For convenience, the dev environment provides
PHP_CodeSniffer, which
detects and can repair many PSR-12 violations. For convenience, 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.
This is based in part on euk: https://github.com/uklibraries/euk/
The following file is derived from Google's documentation of lazy loading images:
- app/assets/js/lazyload.js
Neal Powers, Nicole Sand, MLE Slone, and Eric Weig. For details, consult CONTRIBUTORS.
Copyright (C) 2018-2026 University of Kentucky. For details, consult LICENSE.
We make use of code which has their own licensing:
- Google's documentation of lazy loading images - Apache License, Version 2.0
- Internet Archive BookReader - GNU Affero GPL v3
- jQuery - MIT License (Dual-licensed GPLv2/MIT; MIT selected)
- jQuery UI - MIT License (Dual-licensed GPLv2/MIT; MIT selected)
- MediaElement.js - MIT License
- OpenSeadragon - BSD 3-Clause License
An important note for users, Docker Desktop is not always free software. The recommended installation instructions mention ways of installing the Docker Engine which is free software underneath the Apache License, Version 2.0.