CPW Configuration and Deployment
Every time a change is merged into the beta or master (production) branches of the github repository, a new Docker image is built and pushed to the Docker Hub Repository. In addition, every PR contains a few preview links to Vercel deployments, which are useful for testing new functionality and sharing it with the community before merging it into the codebase.
You can see the current beta version deployed at ebooksbeta.lyrasistechnology.org, which is automatically updated anytime code is pushed to the beta branch. Because the application can host multiple libraries, the root url will show a list of the available libraries to choose from. This is not meant to be a patron-facing page, but simply used by the maintaining community to see and navigate between the different libraries on a deployment. Each library home page is available at its own url path, for example ebooksbeta.lyrasistechnology.org/howard for the Howard County Library System beta version.
There are two main places that configuration is set for CPW. The first is settings for each library configured in their respective Circulation Manager interfaces. These settings are sent to CPW from the circulation manager to configure how the app will run. The second place is the config file for an entire CPW instance. Recall that CPW can host catalogs for multiple libraries, so the settings in a CPW config file would apply to every library on that instance.
1. Setting up a library for CPW in the Circulation Manager
There are a few configurations in the Circulation Manager that are important for setting up a CPW deployment.
- CORS Settings: Web applications can only access servers that are specifically configured to allow requests from that domain. For example, if CPW is running on ebooksbeta.lyrasistechnology.org, and you would like it to host a library in a Circulation Manager running on circ-manager.library.org, then the Circulation Manager needs to be configured to allow access from ebooksbeta.lyrasistechnology.org.
- Primary and Secondary Colors: Both the primary and secondary colors for the library can be configured in the Circulation Manager interface. Both of these colors need to have sufficient contrast with the color white, so that white text is legible on top of this color background and vice-versa. The Circulation Manager interface will check the contrast of your selected colors and will show an error if there is not sufficient contrast.
- Logo - The logo to display in the web catalog interface for this library. It will be shown in the upper left corner.
- Header links - These links will be displayed in the header of the web catalog. It may be useful, for example, to provide a link back to the main library home page.
- Other - The other standard Circulation Manager settings also apply to the web catalog, such as authentication setups, lanes, library name, help links, etc.
2. Setting up a CPW Config File
Some configuration settings apply to the entire CPW instance, whether there are 1 or 1000 libraries being hosted on it. These settings are set in a YAML config file, which is then hosted somewhere on the internet. The URL to that file is then provided to CPW when running the application. The configurable settings are:
- bugsnag_api_key - The optional API key to your Bugsnag account for error tracking (more below).
- gtm_id - The optional id for your Google Tag Manager account for web analytics (more below).
- show_medium - Whether or not to show medium indicators on books. If you expect your library to only have ebooks, for example, you may want to set this to "false". The default is "true".
- media_support - The media types supported by the library, and how they are supported. You can choose to hide some formats, or redirect users to read certain formats in the mobile app.
- libraries - This is where you set either a dictionary of libraries the app will host, or a url to a single library registry.
More info on setting up a CPW config file can be found in the Github Repo README.
Deploying via Docker
To deploy via Docker, simply pull the public docker image from Docker Hub, and run the docker image with a provided config file. More info can be found in the README.