a mechanism for grouping nodes under a "Parent" node through the generic "Member Of" relationship field (field_member_of). This mechanism is also used by Paged Content and Compound Objects. Islandora on its own does not prescribe any particular Content Type, so this field can be configured for any node bundle intended to represent Islandora resources.
+
a mechanism for grouping nodes under a "Parent" node through the generic "Member Of" relationship field (field_member_of). This mechanism is also used by Paged Content and Compound Objects. Islandora on its own does not prescribe any particular Content Type, so this field can be configured for any node bundle intended to represent Islandora resources.
a "Children" tab on resources, which provides a management interface to access, re-order, add, or delete the members of a resource based on the Member Of field.
a "Model" field (field_model) which can take various values including "Collection".
@@ -2490,8 +2490,8 @@
Islandora Starter Site featuresIslandora Starter Site is an optional set of presets for Islandora, intended to provide a more user-friendly out-of-the-box experience and starting point for more specific customization.
Islandora Starter Site provides:
-
a Content Type "Repository Item" that uses the field_member_of field, so that users may add nodes of this type to a collection (or paged content, or compound resource),
a Content Type "Repository Item" that uses the field_member_of field, so that users may add nodes of this type to a collection (or paged content, or compound resource),
logic (a Context) such that if a resource is tagged as a "Collection" (in the "Model" field, then a view of its members will show on the collection's page.
Within a single content type (i.e. metadata profile), Islandora provides the ability to designate
some objects as different "types" than others. Key behaviours, such as what derivatives are created
-or what viewer is used, can be configured
+or what viewer is used, can be configured
(see Contexts) based on this value. The available values
are taxonomy terms in the Islandora Models vocabulary, and they are attached to nodes via the special
mandatory field, "Model" (field_model), which must be present on all Islandora content types.
@@ -2553,7 +2553,7 @@
The Islandora community uses GitHub issues to track bug reports, requests for improvements, requests for new features, and use cases. Issues are welcome from anyone who works with Islandora.
+
The Islandora issue queue is maintained in the Islandora Documentation repository on GitHub. Issues posted to the queue are reviewed weekly on the Islandora Tech Call. Members of the Islandora community can then respond to posted issues by replying with comments, taking on the assignment to do the work described in the issue, or making pull requests relating to the issue.
Select the type of issue you are creating, as this will provide you with a template to describe your issue.
+
+
+
Fill in the information for your issue:
+
+
Give your issue a descriptive title following the text that is already provided in the template title, ex. [BUG].
+
Fill in the body of your issue under the Write tab. A template of questions will be provided based on the type of issue selected. Depending on your issue, you may need to: describe a bug you are seeing and how to reproduce it, describe how an existing feature could be improved, describe a new feature and how it should work, or describe documentation that needs to be written or expanded.
+
Use the built-in text editor to help format your issue in Markdown.
+
Use the Preview button to see how your issue will be published and ensure the formatting looks the way you want.
+
Click Submit new issue to add your issue to the queue.
+
Optionally, Add labels to your issue to assign it to available categories, such as "documentation" or "question." Click on as may labels as you like. When you click outside of the drop-down list, the selected labels will be applied to your issue.
The Islandora community uses GitHub issues to track bug reports, requests for improvements, requests for new features, and use cases. Issues are welcome from anyone who works with Islandora.
-
The Islandora issue queue is maintained in the Islandora Documentation repository on GitHub. Issues posted to the queue are reviewed weekly on the Islandora Tech Call. Members of the Islandora community can then respond to posted issues by replying with comments, taking on the assignment to do the work described in the issue, or making pull requests relating to the issue.
Select the type of issue you are creating, as this will provide you with a template to describe your issue.
-
-
-
Fill in the information for your issue:
-
-
Give your issue a descriptive title following the text that is already provided in the template title, ex. [BUG].
-
Fill in the body of your issue under the Write tab. A template of questions will be provided based on the type of issue selected. Depending on your issue, you may need to: describe a bug you are seeing and how to reproduce it, describe how an existing feature could be improved, describe a new feature and how it should work, or describe documentation that needs to be written or expanded.
-
Use the built-in text editor to help format your issue in Markdown.
-
Use the Preview button to see how your issue will be published and ensure the formatting looks the way you want.
-
Click Submit new issue to add your issue to the queue.
-
Optionally, Add labels to your issue to assign it to available categories, such as "documentation" or "question." Click on as may labels as you like. When you click outside of the drop-down list, the selected labels will be applied to your issue.
Use a GitHub Pull Request to submit documentation.
+
See the Editing Documentation documentation page for information on creating a Pull Request.
+
+
+
Make it clear if the documentation is based on a particular configuration (such as the Install Profile Demo) or if it applies to any deployment of Islandora.
+
+
Submit documentation formatted in Markdown format.
+
+
Include a top-level heading for the whole page (using #)
+
Please add Markdown headings (# and ##) to the content sections.
+
+
+
+
Use the "bold/emphasis" style in Markdown by enclosing text in double asterisks or underscores, **bold text** or __bold text__, for UI elements that users will interact with. For example, a button label for a button that must be pressed should be made bold in Markdown.
+
+
Use the "italics" style in Markdown by enclosing text in single asterisks or underscores, *italic text* or _italic text_, for UI elements that have a label or title if you need to reference them in the documentation. For example, a title of a screen or page that will visit should be made italic in Markdown.
+
Use >> and **bold text** to indicate clicking through nested menu items, and also include the direct path. Example:
+
Use - instead of * for bulleted lists. Indent four (4) spaces for nested lists (Github renders nesting in markdown with 2 spaces, but mkdocs needs 4).
+Example:
+
- I am a list item
+ - And I am a sub-item.
+
+
Upload images to the 'assets' folder and reference them from there.
+
For file naming, use underscores between words and prefix all file names with the page name, e.g. context_display_hints.jpg for the image showing how to set display hints in the context menu.
+
+
+
Use the Admonition syntax to create notes like this (four-space indent required):
+
+
Example:
+
!!! note "Helpful Tip"
+ I am a helpful tip!
+
+
Result:
+
+
Helpful Tip
+
I am a helpful tip!
+
+
+
Use our custom islandora type within the Admonition syntax to call attention to areas where Islandora configuration differs from standard Drupal configuration:
+
+
Example:
+
!!! islandora "Lobster trap"
+ This setting is specific to Islandora and is not standard to Drupal.
+
+
Result:
+
+
Lobster trap
+
This setting is specific to Islandora and is not standard to Drupal.
Use a GitHub Pull Request to submit documentation.
-
See the Editing Documentation documentation page for information on creating a Pull Request.
-
-
-
Make it clear if the documentation is based on a particular configuration (such as the Install Profile Demo) or if it applies to any deployment of Islandora.
-
-
Submit documentation formatted in Markdown format.
-
-
Include a top-level heading for the whole page (using #)
-
Please add Markdown headings (# and ##) to the content sections.
-
-
-
-
Use the "bold/emphasis" style in Markdown by enclosing text in double asterisks or underscores, **bold text** or __bold text__, for UI elements that users will interact with. For example, a button label for a button that must be pressed should be made bold in Markdown.
-
-
Use the "italics" style in Markdown by enclosing text in single asterisks or underscores, *italic text* or _italic text_, for UI elements that have a label or title if you need to reference them in the documentation. For example, a title of a screen or page that will visit should be made italic in Markdown.
-
Use >> and **bold text** to indicate clicking through nested menu items, and also include the direct path. Example:
-
Use - instead of * for bulleted lists. Indent four (4) spaces for nested lists (Github renders nesting in markdown with 2 spaces, but mkdocs needs 4).
-Example:
-
- I am a list item
- - And I am a sub-item.
-
-
Upload images to the 'assets' folder and reference them from there.
-
For file naming, use underscores between words and prefix all file names with the page name, e.g. context_display_hints.jpg for the image showing how to set display hints in the context menu.
-
-
-
Use the Admonition syntax to create notes like this (four-space indent required):
-
-
Example:
-
!!! note "Helpful Tip"
- I am a helpful tip!
-
-
Result:
-
-
Helpful Tip
-
I am a helpful tip!
-
-
-
Use our custom islandora type within the Admonition syntax to call attention to areas where Islandora configuration differs from standard Drupal configuration:
-
-
Example:
-
!!! islandora "Lobster trap"
- This setting is specific to Islandora and is not standard to Drupal.
-
-
Result:
-
-
Lobster trap
-
This setting is specific to Islandora and is not standard to Drupal.
have either an individual Contributor License Agreement (CLA) on file with the Islandora Foundation, or work for an organization that has a corporate Contributor License Agreement on file with the Islandora Foundation.
for information on how to fill out and submit a Contributor License Agreement (CLA) for yourself and/or your organization visit the License Agreements section of the "How to contribute" documentation page.
#  Repository Name
+
+[](link)
+[](link)
+[](./CONTRIBUTING.md)
+[](./LICENSE)
+[](link)
+
+## Introduction
+
+A brief introduction and summary of the module.
+
+## Requirements
+
+This module requires the following modules/libraries:
+
+* [Name](Link)
+* [Name](Link)
+* Any
+* Requirements
+
+## Installation
+
+Installations instructions.
+
+## Configuration
+
+Describe path to configuration.
+
+Include a screenshot of configuration page. When using your choice of screenshot software, resize your browser
+first to avoid wide screenshots. Here are a few browser extension examples to take screenshots.
+
+ - [Fireshots](https://chrome.google.com/webstore/detail/take-webpage-screenshots/mcbpblocgmgfnpjjppndjkmgjaogfceg)
+ - [Nimbus](https://chrome.google.com/webstore/detail/nimbus-screenshot-screen/bpconcjcammlapcogcnnelfmaeghhagj)
+
+To upload the image drag the image into the comment section of an existing Pull Request.
+
+This will generate the image URL link for you
+ 
+
+Video example on [How to attach an Image in README.md file with Github](https://youtu.be/wVHJtL-y7P0)
+
+
+## Other Sections As Needed
+
+Sections specific to this repo, but not found in all repos, should go here.
+
+## Documentation
+
+Further documentation for this module is available on the [Islandora documentation site](https://islandora.github.io/documentation/).
+
+## Troubleshooting/Issues
+
+Having problems or solved a problem? Check out the Islandora google groups for a solution.
+
+- [Islandora Group](https://groups.google.com/forum/?hl=en&fromgroups#!forum/islandora)
+- [Islandora Dev Group](https://groups.google.com/forum/?hl=en&fromgroups#!forum/islandora-dev)
+
+## FAQ
+
+Q. Is this normal?
+
+A. Yes. This is normal. Why ...
+
+## Maintainers/Sponsors
+
+Current maintainers:
+
+- [Maintainer Name](https://github.com/maintainer_github)
+- [Another Maintainer](https://github.com/maintainer_github)
+
+This project has been sponsored by:
+
+- Some really awesome sponsor
+
+## Development
+
+If you would like to contribute, please get involved by attending our weekly [Tech Call](https://github.com/Islandora/documentation/wiki). We love to hear from you!
+
+If you would like to contribute code to the project, you need to be covered by an Islandora Foundation [Contributor License Agreement](https://drive.google.com/file/d/1k6eCM5EV-w4I4ErkiGj4NJwvLnXkejyk/view?usp=sharing) or [Corporate Contributor License Agreement](https://drive.google.com/file/d/1-SQYuHWRxvltQYgkFWpYv7nGbvJp1u8h/view?usp=sharing). Please see the [Contributors](https://github.com/Islandora/islandora-community/wiki/Onboarding-Checklist) pages on Islandora.ca for more information.
+
+We recommend using the [islandora-playbook](https://github.com/Islandora-Devops/islandora-playbook) to get started. If you want to pull down the submodules for development, don't forget to run git submodule update --init --recursive after cloning.
+
+Also include any Travis gotcha's here.
+
+## License
+
+[Name](link). GPLv2 for Drupal modules. MIT for other modules.
+
#  Repository Name
-
-[](link)
-[](link)
-[](./CONTRIBUTING.md)
-[](./LICENSE)
-[](link)
-
-## Introduction
-
-A brief introduction and summary of the module.
-
-## Requirements
-
-This module requires the following modules/libraries:
-
-* [Name](Link)
-* [Name](Link)
-* Any
-* Requirements
-
-## Installation
-
-Installations instructions.
-
-## Configuration
-
-Describe path to configuration.
-
-Include a screenshot of configuration page. When using your choice of screenshot software, resize your browser
-first to avoid wide screenshots. Here are a few browser extension examples to take screenshots.
-
- - [Fireshots](https://chrome.google.com/webstore/detail/take-webpage-screenshots/mcbpblocgmgfnpjjppndjkmgjaogfceg)
- - [Nimbus](https://chrome.google.com/webstore/detail/nimbus-screenshot-screen/bpconcjcammlapcogcnnelfmaeghhagj)
-
-To upload the image drag the image into the comment section of an existing Pull Request.
-
-This will generate the image URL link for you
- 
-
-Video example on [How to attach an Image in README.md file with Github](https://youtu.be/wVHJtL-y7P0)
-
-
-## Other Sections As Needed
-
-Sections specific to this repo, but not found in all repos, should go here.
-
-## Documentation
-
-Further documentation for this module is available on the [Islandora documentation site](https://islandora.github.io/documentation/).
-
-## Troubleshooting/Issues
-
-Having problems or solved a problem? Check out the Islandora google groups for a solution.
-
-- [Islandora Group](https://groups.google.com/forum/?hl=en&fromgroups#!forum/islandora)
-- [Islandora Dev Group](https://groups.google.com/forum/?hl=en&fromgroups#!forum/islandora-dev)
-
-## FAQ
-
-Q. Is this normal?
-
-A. Yes. This is normal. Why ...
-
-## Maintainers/Sponsors
-
-Current maintainers:
-
-- [Maintainer Name](https://github.com/maintainer_github)
-- [Another Maintainer](https://github.com/maintainer_github)
-
-This project has been sponsored by:
-
-- Some really awesome sponsor
-
-## Development
-
-If you would like to contribute, please get involved by attending our weekly [Tech Call](https://github.com/Islandora/documentation/wiki). We love to hear from you!
-
-If you would like to contribute code to the project, you need to be covered by an Islandora Foundation [Contributor License Agreement](https://drive.google.com/file/d/1k6eCM5EV-w4I4ErkiGj4NJwvLnXkejyk/view?usp=sharing) or [Corporate Contributor License Agreement](https://drive.google.com/file/d/1-SQYuHWRxvltQYgkFWpYv7nGbvJp1u8h/view?usp=sharing). Please see the [Contributors](https://github.com/Islandora/islandora-community/wiki/Onboarding-Checklist) pages on Islandora.ca for more information.
-
-We recommend using the [islandora-playbook](https://github.com/Islandora-Devops/islandora-playbook) to get started. If you want to pull down the submodules for development, don't forget to run git submodule update --init --recursive after cloning.
-
-Also include any Travis gotcha's here.
-
-## License
-
-[Name](link). GPLv2 for Drupal modules. MIT for other modules.
-
-
-
-
-
-
- Last update:
- November 1, 2023
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
+
+
+
+ Redirecting...
+
+
+
+
+
+
+Redirecting...
+
+
diff --git a/contributing/releasing-islandora/index.html b/contributing/releasing-islandora/index.html
index 832d0a3d9..b00941bf1 100644
--- a/contributing/releasing-islandora/index.html
+++ b/contributing/releasing-islandora/index.html
@@ -479,7 +479,7 @@
A functioning Islandora Stack is made up of dozens of components working in synchronization with each other to store information in your repository, manage that information, and disseminate it intelligently to users. Whether running an installation using the provided Ansible playbook or installing the stack manually, it may be helpful to have a brief overview of all the components we're going to need, in the order we're going to install them, as well as a brief introduction to each component's installation and configuration process.
+
This list includes four different kinds of components:
+
+
Components which are hard-required (such as Drupal and the Islandora module)
+
Components for which defaults are provided but which can be swapped out (such as the software managing databases, or the repository's storage system)
+
Components that can't easily be swapped out but are not necessarily required (such as using Solr as the site's internal search engine)
+
Components which do not have official alternatives and are not necessarily required, but will likely exist on the vast majority of Islandora installations (such as Alpaca and Crayfish)
+
+
The Webserver Stack - Apache, PHP, and MySQL/PostgreSQL¶
+
Combined together, Apache, PHP, and MySQL/PostgreSQL comprise a LAMP or LAPP server used to provide end-user-facing components - namely, the website.
+
Apache is the webserver that will serve up webpages to the public. It will also manage some internal functionality provided by Crayfish, and will expose Cantaloupe to the public. We’ll be making changes to the VirtualHost entry, enabling some modules, and modifying the ports configuration. The VirtualHost entry will eventually be modified when we need to expose other services like Cantaloupe to the public.
+
PHP is the runtime interpreter for all the code Drupal and Crayfish need to be processed. By default, installing PHP 7.2 will give us a command-line interpreter, as well as an interpreter for Apache. We’re going to install several PHP modules required and/or useful for the components that make use of PHP.
+
MySQL and PostgreSQL are database management systems that we will use to store information for many different components like Drupal and Fedora. By default, the Ansible playbook installs MySQL, though this can be switched to PostgreSQL. The manual installation guide recommends and walks through installing and using PostgreSQL.
+
The Front-Facing CDM - Composer, Drush, and Drupal¶
+
Composer will be used to install both Drupal and Drush simultaneously using Islandora's fork of the drupal-project repository.
+
Composer is an installer and dependency manager for PHP projects. We're going to need it to install components for any PHP code we need to make use of, including Drupal and Crayfish.
+
Drush and Drupal are installed simultaneously using drupal-project. Drupal will serve up webpages and manage Islandora content, and Drush will help us get some things done from the command-line.
+
The Web Application Server - Tomcat and Cantaloupe¶
+
Several applets will be deployed via their .war files into Tomcat, including Fedora and Cantaloupe.
+
Tomcat serves up webpages and other kinds of content much like Apache, but is specifically designed to deploy Java applications as opposed to running PHP code.
+
Cantaloupe is an image tileserver that Islandora will connect to and use to serve up extremely large images in a way that doesn't have an adverse effect on the overall system.
+
The Back-End File Management Repository - Fedora, Syn, and Blazegraph¶
+
Fedora will be installed in its own section, rather than as part of the Tomcat installation, as the installation process is rather involved and requires some authorization pieces to be set up in order to connect them back to Drupal and other components.
+
Fedora is the default backend repository that Islandora content will be synchronized with and stored in. A great deal of configuration will be required to get it up and running, including ensuring a database is created and accessible.
+
Syn is the authorization piece that allows Fedora to connect to other components.
+
Blazegraph will store representative graph data about the repository that can be queried using SPARQL. Some configuration will also be required to link it back to Fedora, as well as to ensure it is being properly indexed.
The installation of Solr itself is rather straightforward, but a configuration will have to be generated and applied from the Drupal side.
+
Solr will be installed as a standalone application. Nothing of particular importance needs to happen here; the configuration will be applied when search_api_solr is installed.
+
search_api_solr is the Drupal module that implements the Solr API for Drupal-side searches. After installing and configuring the module, the drush solr-gsc command will be used to generate Solr configs, and these configs will be moved to the Solr configuration location.
Crayfish is a series of microservices that perform different asynchronous tasks kicked off by Islandora. It contains a series of submodules that will be installed via Composer. Later, these configured components will be connected to Alpaca.
+
The Broker Connecting Everything - Karaf and Alpaca¶
+
Karaf’s job is similar to Tomcat, except where Tomcat is a web-accessible endpoint for Java applets, Karaf is simply meant to be a container for system-level applets to communicate via its OSGI. Alpaca is one such applet; it will broker messages between Fedora and Drupal, and between Drupal and various derivative generation applications.
+
Alpaca contains Karaf services to manage moving information between Islandora, Fedora, and Blazegraph as well as kicking off derivative services in Crayfish. These will be configured to broker between Drupal and Fedora using an ActiveMQ queue.
Drupal configuration exists as a series of .yaml files that can either be created in a feature, or exported from Drupal using the content_sync module. It can also be manually entered in via the UI. We're going to place configuration in a few different ways; Some content will be synchronized onto the site, and some core configurations from the main Islandora module will need to be run in order to facilitate ingest.
A functioning Islandora Stack is made up of dozens of components working in synchronization with each other to store information in your repository, manage that information, and disseminate it intelligently to users. Whether running an installation using the provided Ansible playbook or installing the stack manually, it may be helpful to have a brief overview of all the components we're going to need, in the order we're going to install them, as well as a brief introduction to each component's installation and configuration process.
-
This list includes four different kinds of components:
-
-
Components which are hard-required (such as Drupal and the Islandora module)
-
Components for which defaults are provided but which can be swapped out (such as the software managing databases, or the repository's storage system)
-
Components that can't easily be swapped out but are not necessarily required (such as using Solr as the site's internal search engine)
-
Components which do not have official alternatives and are not necessarily required, but will likely exist on the vast majority of Islandora installations (such as Alpaca and Crayfish)
-
-
The Webserver Stack - Apache, PHP, and MySQL/PostgreSQL¶
-
Combined together, Apache, PHP, and MySQL/PostgreSQL comprise a LAMP or LAPP server used to provide end-user-facing components - namely, the website.
-
Apache is the webserver that will serve up webpages to the public. It will also manage some internal functionality provided by Crayfish, and will expose Cantaloupe to the public. We’ll be making changes to the VirtualHost entry, enabling some modules, and modifying the ports configuration. The VirtualHost entry will eventually be modified when we need to expose other services like Cantaloupe to the public.
-
PHP is the runtime interpreter for all the code Drupal and Crayfish need to be processed. By default, installing PHP 7.2 will give us a command-line interpreter, as well as an interpreter for Apache. We’re going to install several PHP modules required and/or useful for the components that make use of PHP.
-
MySQL and PostgreSQL are database management systems that we will use to store information for many different components like Drupal and Fedora. By default, the Ansible playbook installs MySQL, though this can be switched to PostgreSQL. The manual installation guide recommends and walks through installing and using PostgreSQL.
-
The Front-Facing CDM - Composer, Drush, and Drupal¶
-
Composer will be used to install both Drupal and Drush simultaneously using Islandora's fork of the drupal-project repository.
-
Composer is an installer and dependency manager for PHP projects. We're going to need it to install components for any PHP code we need to make use of, including Drupal and Crayfish.
-
Drush and Drupal are installed simultaneously using drupal-project. Drupal will serve up webpages and manage Islandora content, and Drush will help us get some things done from the command-line.
-
The Web Application Server - Tomcat and Cantaloupe¶
-
Several applets will be deployed via their .war files into Tomcat, including Fedora and Cantaloupe.
-
Tomcat serves up webpages and other kinds of content much like Apache, but is specifically designed to deploy Java applications as opposed to running PHP code.
-
Cantaloupe is an image tileserver that Islandora will connect to and use to serve up extremely large images in a way that doesn't have an adverse effect on the overall system.
-
The Back-End File Management Repository - Fedora, Syn, and Blazegraph¶
-
Fedora will be installed in its own section, rather than as part of the Tomcat installation, as the installation process is rather involved and requires some authorization pieces to be set up in order to connect them back to Drupal and other components.
-
Fedora is the default backend repository that Islandora content will be synchronized with and stored in. A great deal of configuration will be required to get it up and running, including ensuring a database is created and accessible.
-
Syn is the authorization piece that allows Fedora to connect to other components.
-
Blazegraph will store representative graph data about the repository that can be queried using SPARQL. Some configuration will also be required to link it back to Fedora, as well as to ensure it is being properly indexed.
The installation of Solr itself is rather straightforward, but a configuration will have to be generated and applied from the Drupal side.
-
Solr will be installed as a standalone application. Nothing of particular importance needs to happen here; the configuration will be applied when search_api_solr is installed.
-
search_api_solr is the Drupal module that implements the Solr API for Drupal-side searches. After installing and configuring the module, the drush solr-gsc command will be used to generate Solr configs, and these configs will be moved to the Solr configuration location.
Crayfish is a series of microservices that perform different asynchronous tasks kicked off by Islandora. It contains a series of submodules that will be installed via Composer. Later, these configured components will be connected to Alpaca.
-
The Broker Connecting Everything - Karaf and Alpaca¶
-
Karaf’s job is similar to Tomcat, except where Tomcat is a web-accessible endpoint for Java applets, Karaf is simply meant to be a container for system-level applets to communicate via its OSGI. Alpaca is one such applet; it will broker messages between Fedora and Drupal, and between Drupal and various derivative generation applications.
-
Alpaca contains Karaf services to manage moving information between Islandora, Fedora, and Blazegraph as well as kicking off derivative services in Crayfish. These will be configured to broker between Drupal and Fedora using an ActiveMQ queue.
Drupal configuration exists as a series of .yaml files that can either be created in a feature, or exported from Drupal using the content_sync module. It can also be manually entered in via the UI. We're going to place configuration in a few different ways; Some content will be synchronized onto the site, and some core configurations from the main Islandora module will need to be run in order to facilitate ingest.
-
-
-
-
-
- Last update:
- November 1, 2023
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
+
+
+
+ Redirecting...
+
+
+
+
+
+
+Redirecting...
+
+
diff --git a/installation/docker-available-commands/index.html b/installation/docker-available-commands/index.html
index 9113ac90d..92faa2c55 100644
--- a/installation/docker-available-commands/index.html
+++ b/installation/docker-available-commands/index.html
@@ -481,7 +481,7 @@
The manual installation documentation is in need of attention. We are aware that some components no longer work as documented here. If you are interested in helping us improve the documentation, please see Contributing.
+
+
After all of the above pieces are in place, installed, configured, started, and otherwise prepared, the last thing we need to do is to finally configure the front-end Drupal instance to wire all the installed components together.
By default, settings.php is read-only for all users. It should be made writable while this pre-configuration is being done, then set back to 444 afterwards.
+
+
Some additional settings will need to be established in your default settings.php before Drupal-side configuration can occur.
+
The below configuration will establish localhost as a trusted host pattern, but on production sites this will need to be expanded to include the actual host patterns used by the site.
The Islandora Starter Site, which was presented as an option in the "Installing Composer, Drush, and Drupal" step,
+installs Islandora and other modules and configures them, allowing you to skip this section. You may want to use this manual method in the case where you want
+to pick and choose which Islandora modules you use.
The Islandora Drupal module contains the core code to create a repository ecosystem in a Drupal environment. It also includes several submodules; of importance to us is islandora_core_feature, which contains the key configurations that allow you to use Islandora features.
+
Take note of some of the other comments in the below bash script for an idea of what the other components are expected, and which may be considered optional.
+
cd/opt/drupal
+# Since islandora_defaults is near the bottom of the dependency chain, requiring
+# it will get most of the modules and libraries we need to deploy a standard
+# Islandora site.
+sudo-uwww-datacomposerrequire"drupal/flysystem:^2.0@alpha"
+sudo-uwww-datacomposerrequire"islandora/islandora:^2.4"
+sudo-uwww-datacomposerrequire"islandora/controlled_access_terms:^2"
+sudo-uwww-datacomposerrequire"islandora/openseadragon:^2"
+
+# These can be considered important or required depending on your site's
+# requirements; some of them represent dependencies of Islandora submodules.
+sudo-uwww-datacomposerrequire"drupal/pdf:1.1"
+sudo-uwww-datacomposerrequire"drupal/rest_oai_pmh:^2.0@beta"
+sudo-uwww-datacomposerrequire"drupal/search_api_solr:^4.2"
+sudo-uwww-datacomposerrequire"drupal/facets:^2"
+sudo-uwww-datacomposerrequire"drupal/content_browser:^1.0@alpha"## TODO do we need this?
+sudo-uwww-datacomposerrequire"drupal/field_permissions:^1"
+sudo-uwww-datacomposerrequire"drupal/transliterate_filenames:^2.0"
+
+# These tend to be good to enable for a development environment, or just for a
+# higher quality of life when managing Islandora. That being said, devel should
+# NEVER be enabled on a production environment, as it intentionally gives the
+# user tools that compromise the security of a site.
+sudo-uwww-datacomposerrequiredrupal/restui:^1.21
+sudo-uwww-datacomposerrequiredrupal/console:~1.0
+sudo-uwww-datacomposerrequiredrupal/devel:^2.0
+sudo-uwww-datacomposerrequiredrupal/admin_toolbar:^2.0
+
Components we've now downloaded using composer require can be enabled simultaneously via drush, which will ensure they are installed in the correct dependent order. Enabling islandora_defaults will also ensure all content types and configurations are set up in Islandora. The installation process for all of these modules will likely take some time.
+
+
Notice
+
This list of modules assumes that all of the above components were downloaded using composer require; if this is not the case, you may need to pare down this list manually. It also includes devel, which again, should not be enabled on production sites.
+
+
cd/opt/drupal
+drush-yenrdfresponsive_imagedevelsyslogserializationbasic_authrestrestuisearch_api_solrfacetscontent_browserpdfadmin_toolbarcontrolled_access_terms_defaultsislandora_breadcrumbsislandora_iiifislandora_oaipmh
+# After all of this, rebuild the cache.
+drush-ycr
+
To allow our installation to talk to other services via Syn, we need to establish a Drupal-side JWT configuration using the keys we generated at that time.
+
Log onto your site as an administrator at /user, then navigate to /admin/config/system/keys/add. Some of the settings here are unimportant, but pay close attention to the Key type, which should match the key we created earlier (an RSA key), and the File location, which should be the ultimate location of the key we created for Syn on the filesystem, /opt/keys/syn_private.key.
+
+
Click Save to create the key.
+
Once this key is created, navigate to /admin/config/system/jwt to select the key you just created from the list. Note that before the key will show up in the Private Key list, you need to select that key's type in the Algorithm section, namely RSASSA-PKCS1-v1_5 using SHA-256 (RS256).
+
+
Click Save configuration to establish this as the JWT key configuration.
Navigate to the Islandora core configuration page at /admin/config/islandora/core to set up the core configuration to connect to Gemini. Of note here, the Gemini URL will need to be established to facilitate the connection to Fedora, and the appropriate Bundles with Gemini URI pseudo field types will need to be checked off.
+
+
Notice
+
Any other Drupal content types you wish to synchronize with Fedora should also be checked off here.
The manual installation documentation is in need of attention. We are aware that some components no longer work as documented here. If you are interested in helping us improve the documentation, please see Contributing.
-
-
After all of the above pieces are in place, installed, configured, started, and otherwise prepared, the last thing we need to do is to finally configure the front-end Drupal instance to wire all the installed components together.
By default, settings.php is read-only for all users. It should be made writable while this pre-configuration is being done, then set back to 444 afterwards.
-
-
Some additional settings will need to be established in your default settings.php before Drupal-side configuration can occur.
-
The below configuration will establish localhost as a trusted host pattern, but on production sites this will need to be expanded to include the actual host patterns used by the site.
The Islandora Starter Site, which was presented as an option in the "Installing Composer, Drush, and Drupal" step,
-installs Islandora and other modules and configures them, allowing you to skip this section. You may want to use this manual method in the case where you want
-to pick and choose which Islandora modules you use.
The Islandora Drupal module contains the core code to create a repository ecosystem in a Drupal environment. It also includes several submodules; of importance to us is islandora_core_feature, which contains the key configurations that allow you to use Islandora features.
-
Take note of some of the other comments in the below bash script for an idea of what the other components are expected, and which may be considered optional.
-
cd/opt/drupal
-# Since islandora_defaults is near the bottom of the dependency chain, requiring
-# it will get most of the modules and libraries we need to deploy a standard
-# Islandora site.
-sudo-uwww-datacomposerrequire"drupal/flysystem:^2.0@alpha"
-sudo-uwww-datacomposerrequire"islandora/islandora:^2.4"
-sudo-uwww-datacomposerrequire"islandora/controlled_access_terms:^2"
-sudo-uwww-datacomposerrequire"islandora/openseadragon:^2"
-
-# These can be considered important or required depending on your site's
-# requirements; some of them represent dependencies of Islandora submodules.
-sudo-uwww-datacomposerrequire"drupal/pdf:1.1"
-sudo-uwww-datacomposerrequire"drupal/rest_oai_pmh:^2.0@beta"
-sudo-uwww-datacomposerrequire"drupal/search_api_solr:^4.2"
-sudo-uwww-datacomposerrequire"drupal/facets:^2"
-sudo-uwww-datacomposerrequire"drupal/content_browser:^1.0@alpha"## TODO do we need this?
-sudo-uwww-datacomposerrequire"drupal/field_permissions:^1"
-sudo-uwww-datacomposerrequire"drupal/transliterate_filenames:^2.0"
-
-# These tend to be good to enable for a development environment, or just for a
-# higher quality of life when managing Islandora. That being said, devel should
-# NEVER be enabled on a production environment, as it intentionally gives the
-# user tools that compromise the security of a site.
-sudo-uwww-datacomposerrequiredrupal/restui:^1.21
-sudo-uwww-datacomposerrequiredrupal/console:~1.0
-sudo-uwww-datacomposerrequiredrupal/devel:^2.0
-sudo-uwww-datacomposerrequiredrupal/admin_toolbar:^2.0
-
Components we've now downloaded using composer require can be enabled simultaneously via drush, which will ensure they are installed in the correct dependent order. Enabling islandora_defaults will also ensure all content types and configurations are set up in Islandora. The installation process for all of these modules will likely take some time.
-
-
Notice
-
This list of modules assumes that all of the above components were downloaded using composer require; if this is not the case, you may need to pare down this list manually. It also includes devel, which again, should not be enabled on production sites.
-
-
cd/opt/drupal
-drush-yenrdfresponsive_imagedevelsyslogserializationbasic_authrestrestuisearch_api_solrfacetscontent_browserpdfadmin_toolbarcontrolled_access_terms_defaultsislandora_breadcrumbsislandora_iiifislandora_oaipmh
-# After all of this, rebuild the cache.
-drush-ycr
-
To allow our installation to talk to other services via Syn, we need to establish a Drupal-side JWT configuration using the keys we generated at that time.
-
Log onto your site as an administrator at /user, then navigate to /admin/config/system/keys/add. Some of the settings here are unimportant, but pay close attention to the Key type, which should match the key we created earlier (an RSA key), and the File location, which should be the ultimate location of the key we created for Syn on the filesystem, /opt/keys/syn_private.key.
-
-
Click Save to create the key.
-
Once this key is created, navigate to /admin/config/system/jwt to select the key you just created from the list. Note that before the key will show up in the Private Key list, you need to select that key's type in the Algorithm section, namely RSASSA-PKCS1-v1_5 using SHA-256 (RS256).
-
-
Click Save configuration to establish this as the JWT key configuration.
Navigate to the Islandora core configuration page at /admin/config/islandora/core to set up the core configuration to connect to Gemini. Of note here, the Gemini URL will need to be established to facilitate the connection to Fedora, and the appropriate Bundles with Gemini URI pseudo field types will need to be checked off.
-
-
Notice
-
Any other Drupal content types you wish to synchronize with Fedora should also be checked off here.
The manual installation documentation is in need of attention. We are aware that some components no longer work as documented here. If you are interested in helping us improve the documentation, please see Contributing.
Composer provides PHP code that we can use to install it. After downloading and running the installer, we’re going to move the generated executable to a place in $PATH, removing its extension:
At this point, you have the option of using the Islandora Starter Site, with its pre-selected modules
+and configurations which function "out of the box," or build a clean stock Drupal via the Drupal Recommended Project and install
+Islandora modules as you desire.
+
Option 1: Create a project using the Islandora Starter Site¶
+
Navigate to the folder where you want to put your Islandora project (in our case /var/www), and
+create the Islandora Starter Site:
Before we can proceed with the actual site installation, we’re going to need to make our new Drupal installation the default web-accessible location Apache serves up. This will include an appropriate ports.conf file, and replacing the default enabled site.
+
+
Notice
+
Out of the box, these files will contain support for SSL, which we will not be setting up in this guide (and therefore removing with these overwritten configurations), but which are absolutely indispensable to a production site. This guide does not recommend any particular SSL certificate authority or installation method, but you may find DigitalOcean's tutorial helpful.
+
+
/etc/apache2/ports.conf | root:root/644
+
Listen 80
+
+
Remove everything but the "Listen 80" line. You can leave the comments in if you want.
+- SERVER_NAME: localhost
+ - For a development environment hosted on your own machine or a VM, localhost should suffice. Realistically, this should be the domain or IP address the server will be accessed at.
+
Restart the Apache 2 service to apply these changes:
PostgreSQL roles are directly tied to users. We’re going to ensure a user is in place, create a role for them in PostgreSQL, and create a database for them that we can use to install Drupal.
+
# Run psql as the postgres user, the only user currently with any PostgreSQL
+# access.
+sudo-upostgrespsql
+# Then, run these commands within psql itself:
+createdatabaseDRUPAL_DBencoding'UTF8'LC_COLLATE='en_US.UTF-8'LC_CTYPE='en_US.UTF-8'TEMPLATEtemplate0;
+createuserDRUPAL_DB_USERwithencryptedpassword'DRUPAL_DB_PASSWORD';
+grantallprivilegesondatabaseDRUPAL_DBtoDRUPAL_DB_USER;
+# Then, quit psql.
+\q
+
+- DRUPAL_DB: drupal9
+ - This will be used as the core database that Drupal is installed into
+- DRUPAL_DB_USER: drupal
+ - Specifically, this is the user that will connect to the PostgreSQL database being created, not the user that will be logging into Drupal
+- DRUPAL_DB_PASSWORD: drupal
+ - This should be a secure password; it’s recommended to use a password generator to create this such as the one provided by random.org
+
The Drupal installation process can be done through the GUI in a series of form steps, or can be done quickly using Drush's site-install command. It can be invoked with the full list of parameters (such as --db-url and --site-name), but if parameters are missing, they will be asked of you interactively.
+
Option 1: Site install the Starter Site with existing configs¶
+
Follow the instructions in the README of the Islandora Starter Site.
+The steps are not reproduced here to remove redundancy. When this installation is done, you'll have a starter site ready-to-go. Once you set up the external services in the next sections, you'll need to configure Drupal to know where they are.
+
Option 2: Site install the basic Drupal Recommended Project¶
+This uses the same parameters from the above step, as well as:
+
+
SITE_NAME: Islandora 2.0
+
This is arbitrary, and is simply used to title the site on the home page
+
+
+
DRUPAL_LOGIN: islandora
+
The Drupal administrative username to use
+
+
+
DRUPAL_PASS: islandora
+
The password to use for the Drupal administrative user
+
+
+
+
Congratulations, you have a Drupal site! It currently isn’t really configured to do anything, but we’ll get those portions set up in the coming sections.
The manual installation documentation is in need of attention. We are aware that some components no longer work as documented here. If you are interested in helping us improve the documentation, please see Contributing.
Some packages need to be installed before we can proceed with installing Crayfish; these packages are used by the microservices within Crayfish. These include:
+
+
Imagemagick, which will be used for image processing. We'll be using the LYRASIS build of imagemagick here, which supports JP2 files.
+
Tesseract, which will be used for optical character recognition; note that by default Tesseract can only understand English; several other individual Tesseract language packs can be installed using apt-get, and a list of available packs can be procured with sudo apt-cache search tesseract-ocr
NOTICE: If you get the sudo: apt-add-repository: command not found, run sudo apt-get install software-properties-common in order to make the command available.
Not much needs to happen here; Crayfish opts for a simple logging approach, with one .log file for each component. We’ll create a folder where each logfile can live.
Each Crayfish component requires one or more .yaml file(s) to ensure everything is wired up correctly.
+
NOTICE
+
The following configuration files represent somewhat sensible defaults; you should take consideration of the logging levels in use, as this can vary in desirability from installation to installation. Also note that in all cases, http URLs are being used, as this guide does not deal with setting up https support. In a production installation, this should not be the case. These files also assume a connection to a PostgreSQL database; use a pdo_mysql driver and the appropriate 3306 port if using MySQL.
# This file is the entry point to configure your own services.
+# Files in the packages/ subdirectory configure your dependencies.
+# Put parameters here that don't need to change on each machine where the app is deployed
+# https://symfony.com/doc/current/best_practices/configuration.html#application-related-configuration
+parameters:
+app.executable:/usr/local/bin/convert
+app.formats.valid:
+-image/jpeg
+-image/png
+-image/tiff
+-image/jp2
+app.formats.default:image/jpeg
+
+services:
+# default configuration for services in *this* file
+_defaults:
+autowire:true# Automatically injects dependencies in your services.
+autoconfigure:true# Automatically registers your services as commands, event subscribers, etc.
+
+# makes classes in src/ available to be used as services
+# this creates a service per class whose id is the fully-qualified class name
+App\Islandora\Houdini\:
+resource:'../src/*'
+exclude:'../src/{DependencyInjection,Entity,Migrations,Tests,Kernel.php}'
+
+# controllers are imported separately to make sure services can be injected
+# as action arguments even if you don't extend any base controller class
+App\Islandora\Houdini\Controller\HoudiniController:
+public:false
+bind:
+$formats:'%app.formats.valid%'
+$default_format:'%app.formats.default%'
+$executable:'%app.executable%'
+tags:['controller.service_arguments']
+
+# add more service definitions when explicit configuration is needed
+# please note that last definitions always *replace* previous ones
+
security:
+
+# https://symfony.com/doc/current/security.html#where-do-users-come-from-user-providers
+providers:
+jwt_user_provider:
+id:Islandora\Crayfish\Commons\Syn\JwtUserProvider
+
+firewalls:
+dev:
+pattern:^/(_(profiler|wdt)|css|images|js)/
+security:false
+main:
+anonymous:false
+# Need stateless or it reloads the User based on a token.
+stateless:true
+
+provider:jwt_user_provider
+guard:
+authenticators:
+-Islandora\Crayfish\Commons\Syn\JwtAuthenticator
+
+# activate different ways to authenticate
+# https://symfony.com/doc/current/security.html#firewalls-authentication
+
+# https://symfony.com/doc/current/security/impersonating_user.html
+# switch_user: true
+
+
+# Easy way to control access for large sections of your site
+# Note: Only the *first* access control that matches will be used
+access_control:
+# - { path: ^/admin, roles: ROLE_ADMIN }
+# - { path: ^/profile, roles: ROLE_USER }
+
+
Disabled JWT token authentication:
+
security:
+
+# https://symfony.com/doc/current/security.html#where-do-users-come-from-user-providers
+providers:
+jwt_user_provider:
+id:Islandora\Crayfish\Commons\Syn\JwtUserProvider
+
+firewalls:
+dev:
+pattern:^/(_(profiler|wdt)|css|images|js)/
+security:false
+main:
+anonymous:true
+# Need stateless or it reloads the User based on a token.
+stateless:true
+
Creating Apache Configurations for Crayfish Components¶
+
Finally, we need appropriate Apache configurations for Crayfish; these will allow other services to connect to Crayfish components via their HTTP endpoints.
+
Each endpoint we need to be able to connect to will get its own .conf file, which we will then enable.
+
NOTICE
+
These configurations would potentially have collisions with Drupal routes, if any are created in Drupal with the same name. If this is a concern, it would likely be better to reserve a subdomain or another port specifically for Crayfish. For the purposes of this installation guide, these endpoints will suffice.
Enabling Each Crayfish Component Apache Configuration¶
+
Enabling each of these configurations involves creating a symlink to them in the conf-enabled directory; the standardized method of doing this in Apache is with a2enconf.
The Fedora configuration is going to come in a few different chunks that need to be in place before Fedora will be functional. We’re going to place several files outright, with mildly modified parameters according to our configuration.
+
The basics of these configuration files have been pulled largely from the templates in Islandora-Devops/islandora-playbook internal Fedora role; you may consider referencing the playbook’s templates directory for more details.
i8_namespaces.yml is a list of namespaces used by Islandora that may not necessarily be present in Fedora; we add them here to ensure we can use them in queries.
# Islandora 8/Fedora namespaces
+#
+# This file contains ALL the prefix mappings, if a URI
+# does not appear in this file it will be displayed as
+# the full URI in Fedora.
+acl:http://www.w3.org/ns/auth/acl#
+bf:http://id.loc.gov/ontologies/bibframe/
+cc:http://creativecommons.org/ns#
+dc:http://purl.org/dc/elements/1.1/
+dcterms:http://purl.org/dc/terms/
+dwc:http://rs.tdwg.org/dwc/terms/
+ebucore:http://www.ebu.ch/metadata/ontologies/ebucore/ebucore#
+exif:http://www.w3.org/2003/12/exif/ns#
+fedoraconfig:http://fedora.info/definitions/v4/config#
+fedoramodel:info:fedora/fedora-system:def/model#
+foaf:http://xmlns.com/foaf/0.1/
+geo:http://www.w3.org/2003/01/geo/wgs84_pos#
+gn:http://www.geonames.org/ontology#
+iana:http://www.iana.org/assignments/relation/
+islandorarelsext:http://islandora.ca/ontology/relsext#
+islandorarelsint:http://islandora.ca/ontology/relsint#
+ldp:http://www.w3.org/ns/ldp#
+memento:http://mementoweb.org/ns#
+nfo:http://www.semanticdesktop.org/ontologies/2007/03/22/nfo#
+ore:http://www.openarchives.org/ore/terms/
+owl:http://www.w3.org/2002/07/owl#
+premis:http://www.loc.gov/premis/rdf/v1#
+prov:http://www.w3.org/ns/prov#
+rdf:http://www.w3.org/1999/02/22-rdf-syntax-ns#
+rdfs:http://www.w3.org/2000/01/rdf-schema#
+rel:http://id.loc.gov/vocabulary/relators/
+schema:http://schema.org/
+skos:http://www.w3.org/2004/02/skos/core#
+test:info:fedora/test/
+vcard:http://www.w3.org/2006/vcard/ns#
+webac:http://fedora.info/definitions/v4/webac#
+xml:http://www.w3.org/XML/1998/namespace
+xmlns:http://www.w3.org/2000/xmlns/
+xs:http://www.w3.org/2001/XMLSchema
+xsi:http://www.w3.org/2001/XMLSchema-instance
+
Fedora 6 now allows you to put all your configuration properties into a single file. We use 0640 permissions as you will want to put your database credentials in here.
fcrepo.home=FCREPO_HOME
+# External content using path defined above.
+fcrepo.external.content.allowed=/opt/fcrepo/config/allowed_external_hosts.txt
+# Namespace registry using path defined above.
+fcrepo.namespace.registry=/opt/fcrepo/config/i8_namespaces.yml
+fcrepo.auth.principal.header.enabled=true
+# The principal header is the syn-setting.xml "config" element's "header" attribute
+fcrepo.auth.principal.header.name=X-Islandora
+# false to use manual versioning, true to create a version on each change
+fcrepo.autoversioning.enabled=true
+fcrepo.db.url=FCREPO_DB_URL
+fcrepo.db.user=FCREPO_DB_USERNAME
+fcrepo.db.password=FCREPO_DB_PASSWORD
+fcrepo.ocfl.root=FCREPO_OCFL_ROOT
+fcrepo.ocfl.temp=FCREPO_TEMP_ROOT
+fcrepo.ocfl.staging=FCREPO_STAGING_ROOT
+# Can be sha512 or sha256
+fcrepo.persistence.defaultDigestAlgorithm=sha512
+# Jms moved from 61616 to allow external ActiveMQ to use that port
+fcrepo.dynamic.jms.port=61626
+# Same as above
+fcrepo.dynamic.stomp.port=61623
+fcrepo.velocity.runtime.log=FCREPO_VELOCITY_LOG
+fcrepo.jms.baseUrl=FCREPO_JMS_BASE
+
+
+
FCREPO_HOME - The home directory for all Fedora generated output and state. Unless otherwise specified, all logs, metadata, binaries, and internally generated indexes, etc. It would default to the Tomcat starting directory. A good default would be /opt/fcrepo
+
+
FCREPO_DB_URL - This parameter allows you to set the database connection url. In general the format is as follows:
FCREPO_OCFL_ROOT - Sets the root directory of the OCFL. Defaults to FCREPO_HOME/data/ocfl-root if not set.
+
FCREPO_TEMP_ROOT - Sets the temp directory used by OCFL. Defaults to FCREPO_HOME/data/temp if not set.
+
FCREPO_STAGING_ROOT - Sets the staging directory used by OCFL. Defaults to FCREPO_HOME/data/staging if not set.
+
FCREPO_VELOCITY_LOG - The Fedora HTML template code uses Apache Velocity, which generates a runtime log called velocity.log. Defaults to FCREPO_HOME/logs/velocity. A good choice might be /opt/tomcat/logs/velocity.log
+
FCREPO_JMS_BASE - This specifies the baseUrl to use when generating JMS messages. You can specify the hostname with or without port and with or without path. If your system is behind a NAT firewall you may need this to avoid your message consumers trying to access the system on an invalid port. If this system property is not set, the host, port and context from the user's request will be used in the emitted JMS messages. If your Alpaca is on the same machine as your Fedora and you use the islandora-indexing-fcrepo, you could use http://localhost:8080/fcrepo/rest.
While not strictly necessary, we can use the tomcat-users.xml file to give us direct access to the Fedora endpoint. Fedora defines, out of the box, a fedoraAdmin and fedoraUser role that can be reflected in the users list for access. The following file will also include the base tomcat user. As always, these default passwords should likely not stay as the defaults.
As before, start the Tomcat service to get Fedora up and running.
+
sudosystemctlstarttomcat
+
+
Note: sometimes it takes a while for Fedora and Tomcat to start up, usually it shouldn't take longer than 5 minutes.
+
Once it starts up, Fedora REST API should be available at http://localhost:8080/fcrepo/rest. The username is fedoraAdmin and we defined the password before as FEDORA_ADMIN_PASSWORD (default: "islandora").
For Islandora and Fedora to talk to each other, an SSL key needs to be generated for use with Syn. We’re going to make a spot where such keys can live, and generate one.
Your Fedora web application needs to be deployed in Tomcat with the name fcrepo.war. Otherwise, change the name of the above XML file to match the deployed web application's name.
Finally, restart tomcat to apply the new configurations.
+
sudosystemctlrestarttomcat
+
+
Note: sometimes it takes a while for Fedora and Tomcat to start up, usually it shouldn't take longer than 5 minutes.
+
Note: after installing the Syn valve, you'll no longer be able to manually create/edit or delete objects via Fedora Web UI. All communication with Fedora will now be handled from the Islandora module in Drupal.
Redhat systems have stopped generating an all inclusive catalina.out, the catalina.<date>.log does not include web application's log statements. To get Fedora log statements flowing, you can create your own LogBack configuration file and point to it.
This will generate a log file at ${catalina.base}/logs/fcrepo.log and will rotate each day or if the logs reaches 10MB. It will maintain 30 days of old logs, or 2GB whichever comes first.
The Blazegraph .war file can be found in a few different places, but to ensure we’re able to easily wget it, we’re going to use the maven.org repository link to grab it.
BLAZEGRAPH_WAR_URL: You can find a link to this at the Maven repository for Blazegraph; you’ll want to click the link for the latest version of Blazegraph 2.1.x, then get the link to the .war file within that version folder.
+
+
Once this is downloaded, give it a moment to expand before moving on to the next step.
We would like to have an appropriate logging configuration for Blazegraph, which can be useful for looking at incoming traffic and determining if anything has gone wrong with Blazegraph. Our logger isn’t going to be much different than the default logger; it can be made more or less verbose by changing the default WARN levels. There are several other loggers that can be enabled, like a SPARQL query trace or summary query evaluation log; if these are desired they should be added in. Consult the Blazegraph documentation for more details.
Our configuration will be built from a few different files that we will eventually reference in JAVA_OPTS and directly apply to Blazegraph; these include most of the functional pieces Blazegraph requires, as well as a generalized configuration for the islandora namespace it will use. As with most large configurations like this, these should likely be tuned to your preferences, and the following files only represent sensible defaults.
In order to enable our configuration when Tomcat starts, we need to reference the location of RWStore.properties in the JAVA_OPTS environment variable that Tomcat uses.
The two other files we created, blazegraph.properties and inference.nt, contain information that Blazegraph requires in order to establish and correctly use the datasets Islandora will send to it. First, we need to create a dataset - contained in blazegraph.properties - and then we need to inform that dataset of the inference set we have contained in inference.nt.
The manual installation documentation is in need of attention. We are aware that some components no longer work as documented here. If you are interested in helping us improve the documentation, please see Contributing.
Karaf, as well as its processes and service, will be owned by a user in charge of ensuring this portion of the stack is segregated and that the service is running.
+- KARAF_TARBALL_LINK: It’s recommended to get the most recent version of Karaf 4.2.x. This will depend on the current version of Karaf, which can be found on the Karaf downloads page under “Karaf Runtime”. Like Solr, you can’t directly wget these links, but clicking on the .tar.gz link for the binary distribution will bring you to a list of mirrors, as well as provide you with a recommended mirror you can use here.
+- KARAF_DIRECTORY: This will depend on the exact version being used, but will likely be /opt/apache-karaf-VERSION, where VERSION is the current Karaf version number.
+
We’re going to apply some basic logging to our Karaf installation that should suffice for an example. In a production installation, you may want to play around with some of these values for more personally useful logging.
Similar to Tomcat, our Karaf service is going to rely on a setenv shell script to determine environment variables Karaf needs in place when running. For now, this will simply be the path to JAVA_HOME, but this also accepts many other parameters you can find in the default setenv script.
+
/opt/karaf/bin/setenv | karaf:karaf/755
+
#!/bin/sh
+export JAVA_HOME="PATH_TO_JAVA_HOME"
+
+- PATH_TO_JAVA_HOME: This will be the same JAVA_HOME we used when installing Tomcat , and can be found using the same method (i.e., still /usr/lib/jvm/java-11-openjdk-amd64 if that's what it was before).
+
We’re going to start Karaf, then run the installer to put our configurations in place and generate a Karaf service. Once these are installed, we’re going to stop Karaf, as from there on out its start/stop management should be handled via that service.
+
First we need to enable the default Karaf user in /opt/karaf/etc/users.properties:
sudo-ukaraf/opt/karaf/bin/start
+# You may want to wait a bit for Karaf to start.
+# If you're not sure whether or not it's running, you can always run:
+# ps aux | grep karaf
+# to see if the server is up and running.
+/opt/karaf/bin/clientfeature:installwrapper
+/opt/karaf/bin/clientwrapper:install
+/opt/karaf/bin/stop
+
Installing the Karaf wrapper generates several service files that can be used on different types of systems. For Debian and Ubuntu installation we want to enable the karaf.service service so that Karaf is properly started on boot.
Karaf features can be installed from several different types of sources, but the fastest and easiest way to do so is from existing repository URLs that we can just plug into Karaf to provide us feature lists prepared and ready for installation. Like most interactions with Karaf, we can add these repositories using its built-in client.
+
+
Notice
+
These repositories are updated consistently, and their updates include revised dependency lists. Commonly, when repositories are out of date or otherwise mismatched, feature installation can result in an Unable to resolve root: missing requirement error; for this reason, this guide recommends using recently-updated versions of these repositories. That being said, if such errors occur despite installing the latest versions of these features, the maintainer of the features repository should be informed.
+
+
For the Karaf features we’re going to install, we need a few different repositories to be added to the list:
+
/opt/karaf/bin/clientrepo-addmvn:org.apache.activemq/activemq-karaf/ACTIVEMQ_KARAF_VERSION/xml/features
+/opt/karaf/bin/clientrepo-addmvn:org.apache.camel.karaf/apache-camel/APACHE_CAMEL_VERSION/xml/features
+/opt/karaf/bin/clientrepo-addmvn:ca.islandora.alpaca/islandora-karaf/ISLANDORA_KARAF_VERSION/xml/features
+# XXX: This shouldn't be strictly necessary, but appears to be a missing
+# upstream dependency for some fcrepo features.
+/opt/karaf/bin/clientrepo-addmvn:org.apache.jena/jena-osgi-features/JENA_OSGI_VERSION/xml/features
+
+- ACTIVEMQ_KARAF_VERSION: The version of ActiveMQ we wrote down at the beginning of this chapter when installing ActiveMQ via apt-get
+- APACHE_CAMEL_VERSION: The latest version of Apache Camel 2.x.x; you can find this listed at the apache-camel repository page (e.g., 2.25.4 at the time of writing)
+- ISLANDORA_KARAF_VERSION: The latest version of Islandora Karaf 1.x; you can find this listed at the islandora-karaf repository page (e.g., 1.0.5 at the time of writing)
+- JENA_OSGI_VERSION: The latest version of the Apache Jena 3.x OSGi features; you can find this listed at the jena-osgi-features repository page (e.g., 3.17.0 at the time of writing)
+
For those services in Crayfish we have set up to provide derivatives to Islandora resources, we need connector blueprints to tell the derivative connector how to route incoming requests, run conversions, and return outgoing derivatives.
+
Our blueprints are going to look largely similar between services, with only a few properties changing between them. Largely, these mainly just need to match the ActiveMQ queues we established in the previous configuration, and route to the correct Crayfish service.
Before we can configure the features we’re going to use, they need to be installed. Some of these installations may take some time.
+
/opt/karaf/bin/clientfeature:installcamel-blueprint
+/opt/karaf/bin/clientfeature:installactivemq-blueprint
+/opt/karaf/bin/clientfeature:installfcrepo-service-activemq
+# This again should not be strictly necessary, since this isn't the triplestore
+# we're using, but is being included here to resolve the aforementioned
+# missing link in the dependency chain.
+/opt/karaf/bin/clientfeature:installjena
+/opt/karaf/bin/clientfeature:installfcrepo-camel
+/opt/karaf/bin/clientfeature:installfcrepo-indexing-triplestore
+/opt/karaf/bin/clientfeature:installislandora-http-client
+/opt/karaf/bin/clientfeature:installislandora-indexing-triplestore
+/opt/karaf/bin/clientfeature:installislandora-indexing-fcrepo
+/opt/karaf/bin/clientfeature:installislandora-connector-derivative
+
+
Verifying Karaf Components are Running (Optional But Recommended)¶
+
At this point, Karaf components should be up and running, but it's a good idea to double-check that this is the case. We can do this from within the Karaf client by taking a look at its component list.
+
# Until this point, we've been running Karaf commands from outside; we can hop
+# into the client, however, and run commands from directly within.
+/opt/karaf/bin/client
+# This takes us into the Karaf client so we can run commands.
+la|grepislandora
+la|grepfcrepo
+# It may be a good idea to use this to look up to the other components we
+# installed.
+logout
+
+
For the above la | grep commands, components that are running should be listed as Active.
The manual installation documentation is in need of attention. We are aware that some components no longer work as documented here. If you are interested in helping us improve the documentation, please see Contributing.
The Solr binaries can be found at the Solr downloads page; the most recent stable release of Solr 8 should be used.
+
# While generally we download tarballs as .tar.gz files without version
+# information, the Solr installer is a bit particular in that it expects a .tgz
+# file with the same name as the extracted folder it contains. It's odd, and we
+# can't really get around it.
+cd
+wgetSOLR_DOWNLOAD_LINK
+tar-xzvfSOLR_TARBALL
+
+- SOLR_DOWNLOAD_LINK: NOTICE: This will depend on a few different things, not least of all the current version of Solr. The link to the .tgz for the binary on the downloads page will take you to a list of mirrors that Solr can be downloaded from, and provide you with a preferred mirror at the top. This preferred mirror should be used as the SOLR_DOWNLOAD_LINK.
+- SOLR_TARBALL: The filename that was downloaded, e.g., solr-8.9.0.tgz
+
Solr includes an installer that does most of the heavy lifting of ensuring we have a Solr user, a location where Solr lives, and configurations in place to ensure it’s running on boot.
Solr's installation guide recommends that you increase the open file limit so that operations aren't disrupted while Solr is trying to access things in its index. This limit can be increased while the system is running, but doing so won't persist after a reboot. You can hard-increase this limit using your system's sysctl file:
Initially, our new Solr core will contain a configuration copied from the example included with the installation, so that we have something to work with when we configure this on the Drupal side. We’ll later update this with generated configurations we create in Drupal.
WARNING: Using _default configset with data driven schema functionality. NOT RECOMMENDED for production use.
+ To turn off: bin/solr config -c islandora8 -p 8983 -action set-user-property -property update.autoCreateFields -value false
+
+Created new core 'islandora8'
+
Rather than use an out-of-the-box configuration that won’t be suitable for our purposes, we’re going to use the Drupal search_api_solr module to generate one for us. This will also require us to install the module so we can create these configurations using Drush.
The following module(s) will be enabled: search_api_solr, language, search_api
+
+ // Do you want to continue?: yes.
+
+ [success] Successfully enabled: search_api_solr, language, search_api
+
Before we can create configurations to use with Solr, the core we created earlier needs to be referenced in Drupal.
+
Log in to the Drupal site at /user using the sitewide administrator username and password (if using defaults from previous chapters this should be islandora and islandora), then navigate to /admin/config/search/search-api/add-server.
+
Fill out the server addition form using the following options:
+
+
+
+
+
SERVER_NAME: islandora8
+
This is completely arbitrary, and is simply used to differentiate this search server configuration from all others. Write down or otherwise pay attention to the machine_name generated next to the server name you type in; this will be used in the next step.
+
+
+
+
As a recap for this configuration:
+
+
Server name should be an arbitrary identifier for this server
+
Enabled should be checked
+
Backend should be set to Solr
+
Under CONFIGURE SOLR BACKEND, Solr Connector should be set to Standard
+
Under CONFIGURE STANDARD SOLR CONNECTOR:
+
HTTP protocol is simply set to http since we've set this up on the same machine Drupal lives on. On a production installation, Solr should likely be installed behind an HTTPS connection.
+
Solr host can be set to localhost since, again, this is set up on the same machine Drupal lives on. On a production installation, this may vary, especially if parts of the installation live on different severs
+
Solr port should be set to the port Solr was installed on, which is 8983 by default
+
Solr path should be set to the configured path to the instance of Solr; in a default installation, there is only one Solr instance, and it lives at /
+
Solr core should be the name of the Solr core you created earlier, which is why it's listed as SOLR_CORE here
+
+
+
Under ADVANCED SERVER CONFIGURATION, solr.install.dir should be set to the path where we installed Solr, which this guide has established at /opt/solr
+
+
Click Save to create the server configuration.
+
NOTICE
+ You can ignore the error about an incompatible Solr schema; we're going to set this up in the next step. In fact, if you refresh the page after restarting Solr in the next step, you should see the error disappear.
Now that our core is in place and our Drupal-side configurations exist, we’re ready to generate Solr configuration files to connect this site to our search engine.
In order for content to be indexed back into Solr, a search index needs to be added to our server. Navigate to /admin/config/search/search-api/add-index and check off the things you'd like to be indexed.
+
NOTICE
+ You should come back here later and reconfigure this after completing the last step in this guide. The default indexing configuration is pretty permissive, and you may want to restrict, for example, indexed content to just Islandora-centric bundles. This guide doesn't set up the index's fields either, which are going to be almost wholly dependent on the needs of your installation. Once you complete that configuration later on, re-index Solr from the configuration page of the index we're creating here.
+
+
+
Click Save to add your index and kick off indexing of existing items.
The manual installation documentation is in need of attention. We are aware that some components no longer work as documented here. If you are interested in helping us improve the documentation, please see Contributing.
Tomcat runs in a Java runtime environment, so we'll need one to continue. In our case, OpenJDK 11 is open-source, free to use, and can fairly simply be installed using apt-get:
The installation of OpenJDK via apt-get establishes it as the de-facto Java runtime environment to be used on the system, so no further configuration is required.
+
The resultant location of the java JRE binary (and therefore, the correct value of JAVA_HOME when it’s referenced) will vary based on the specifics of the machine it’s being installed on; that being said, you can find its exact location using update-alternatives:
+
update-alternatives--listjava
+
+Take a note of this path as we will need it later.
+
Apache Tomcat, and all its processes, will be owned and managed by a specific user for the purposes of keeping parts of the stack segregated and accountable.
Tomcat 9 itself can be installed in several different ways; while it’s possible to install via apt-get, this doesn’t give us a great deal of control over exactly how we’re going to run and manage it; as a critical part of the stack, it is beneficial for our purposes to have a good frame of reference for the inner workings of Tomcat.
+
We’re going to download the latest version of Tomcat to /opt and set it up so that it runs automatically. Bear in mind that with the following commands, this is going to be entirely relative to the current version of Tomcat 9, which we’ll try to mitigate as we go.
+- TOMCAT_TARBALL_LINK: No default can be provided here; you should navigate to the Tomcat 9 downloads page and grab the link to the latest .tar.gz file under the “Core” section of “Binary Distributions”. It is highly recommended to grab the latest version of Tomcat 9, as it will come with associated security patches and fixes.
+- TOMCAT_DIRECTORY: This will also depend entirely on the exact version of tomcat downloaded - for example, apache-tomcat-9.0.50. Again, ls /opt can be used to find this.
+
+- PATH_TO_JAVA_HOME: This will vary a bit depending on the environment, but will likely live in /usr/lib/jvm somewhere (e.g., /usr/lib/jvm/java-11-openjdk-amd64); again, in an Ubunutu environment you can check a part of this using update-alternatives --list java, which will give you the path to the JRE binary within the Java home. Note that update-alternatives --list java will give you the path to the binary, so for PATH_TO_JAVA_HOME delete the /bin/java at the end to get the Java home directory, so it should look something like this:
+
Tomcat includes two shell scripts we’re going to make use of - startup.sh and shutdown.sh - which are light wrappers on top of a third script, catalina.sh, which manages spinning up and shutting down the Tomcat server.
+
Debian and Ubuntu use systemctl to manage services; we’re going to create a .service file that can run these shell scripts.
We’re going to both enable and start Tomcat. Enabling Tomcat will ensure that it starts on boot, the timing of which is defined by the [Install] section’s WantedBy statement, which specifies what it should start after. This is separate from starting it, which we need to do now in order to get Tomcat up and running without requiring a reboot.
We can check that Tomcat has started by running sudo systemctl status tomcat | grep Active; we should see that Tomcat is active (running), which is the correct result of startup.sh finishing its run successfully.
Since version 5, Cantaloupe is released as a standalone Java application and is no longer deployed in Tomcat via a .war file. Even so, we can still fine-tune how it runs and even install it as a service.
+- CANTALOUPE_RELEASE_URL: It’s recommended we grab the latest version of Cantaloupe 5. This can be found on the above-linked release page, as the .zip version; for example, https://github.com/cantaloupe-project/cantaloupe/releases/download/v5.0.3/cantaloupe-5.0.3.zip - make sure not to download the source code zip file as that isn't compiled for running out-of-the-box.
+
Cantaloupe pulls its configuration from a file called cantaloupe.properties; there are also some other files that can contain instructions for Cantaloupe while it’s running; specifically, we’re going to copy over the delegates.rb file, which can also contain custom configuration. We won’t make use of this file; we’re just copying it over for demonstration purposes.
+
Creating these files from scratch is not recommended; rather, we’re going to take the default cantaloupe configurations and plop them into their own folder so we can work with them.
+- CANTALOUPE_VER: This will depend on the exact version of Cantaloupe downloaded; in the above example release, this would be cantaloupe-5.0.3
+
The out-of-the-box configuration will work fine for our purposes, but it’s highly recommended that you take a look through the cantaloupe.properties and see what changes can be made; specifically, logging to actual logfiles isn’t set up by default, so you may want to take a peek at the log.application.SyslogAppender or log.application.RollingFileAppender, as well as changing the logging level.
+
Installing and configuring Cantaloupe as a service¶
+
Since it is a standalone application, we can configure Cantaloupe as a systemd service like we did with Tomcat, so it can start on boot:
We can check the service status with sudo systemctl status cantaloupe | grep Active and the splash screen of Cantaloupe should be available at http://localhost:8182
The manual installation documentation is in need of attention. We are aware that some components no longer work as documented here. If you are interested in helping us improve the documentation, please see Contributing.
Composer provides PHP code that we can use to install it. After downloading and running the installer, we’re going to move the generated executable to a place in $PATH, removing its extension:
At this point, you have the option of using the Islandora Starter Site, with its pre-selected modules
-and configurations which function "out of the box," or build a clean stock Drupal via the Drupal Recommended Project and install
-Islandora modules as you desire.
-
Option 1: Create a project using the Islandora Starter Site¶
-
Navigate to the folder where you want to put your Islandora project (in our case /var/www), and
-create the Islandora Starter Site:
Before we can proceed with the actual site installation, we’re going to need to make our new Drupal installation the default web-accessible location Apache serves up. This will include an appropriate ports.conf file, and replacing the default enabled site.
-
-
Notice
-
Out of the box, these files will contain support for SSL, which we will not be setting up in this guide (and therefore removing with these overwritten configurations), but which are absolutely indispensable to a production site. This guide does not recommend any particular SSL certificate authority or installation method, but you may find DigitalOcean's tutorial helpful.
-
-
/etc/apache2/ports.conf | root:root/644
-
Listen 80
-
-
Remove everything but the "Listen 80" line. You can leave the comments in if you want.
-- SERVER_NAME: localhost
- - For a development environment hosted on your own machine or a VM, localhost should suffice. Realistically, this should be the domain or IP address the server will be accessed at.
-
Restart the Apache 2 service to apply these changes:
PostgreSQL roles are directly tied to users. We’re going to ensure a user is in place, create a role for them in PostgreSQL, and create a database for them that we can use to install Drupal.
-
# Run psql as the postgres user, the only user currently with any PostgreSQL
-# access.
-sudo-upostgrespsql
-# Then, run these commands within psql itself:
-createdatabaseDRUPAL_DBencoding'UTF8'LC_COLLATE='en_US.UTF-8'LC_CTYPE='en_US.UTF-8'TEMPLATEtemplate0;
-createuserDRUPAL_DB_USERwithencryptedpassword'DRUPAL_DB_PASSWORD';
-grantallprivilegesondatabaseDRUPAL_DBtoDRUPAL_DB_USER;
-# Then, quit psql.
-\q
-
-- DRUPAL_DB: drupal9
- - This will be used as the core database that Drupal is installed into
-- DRUPAL_DB_USER: drupal
- - Specifically, this is the user that will connect to the PostgreSQL database being created, not the user that will be logging into Drupal
-- DRUPAL_DB_PASSWORD: drupal
- - This should be a secure password; it’s recommended to use a password generator to create this such as the one provided by random.org
-
The Drupal installation process can be done through the GUI in a series of form steps, or can be done quickly using Drush's site-install command. It can be invoked with the full list of parameters (such as --db-url and --site-name), but if parameters are missing, they will be asked of you interactively.
-
Option 1: Site install the Starter Site with existing configs¶
-
Follow the instructions in the README of the Islandora Starter Site.
-The steps are not reproduced here to remove redundancy. When this installation is done, you'll have a starter site ready-to-go. Once you set up the external services in the next sections, you'll need to configure Drupal to know where they are.
-
Option 2: Site install the basic Drupal Recommended Project¶
-This uses the same parameters from the above step, as well as:
-
-
SITE_NAME: Islandora 2.0
-
This is arbitrary, and is simply used to title the site on the home page
-
-
-
DRUPAL_LOGIN: islandora
-
The Drupal administrative username to use
-
-
-
DRUPAL_PASS: islandora
-
The password to use for the Drupal administrative user
-
-
-
-
Congratulations, you have a Drupal site! It currently isn’t really configured to do anything, but we’ll get those portions set up in the coming sections.
The manual installation documentation is in need of attention. We are aware that some components no longer work as documented here. If you are interested in helping us improve the documentation, please see Contributing.
Some packages need to be installed before we can proceed with installing Crayfish; these packages are used by the microservices within Crayfish. These include:
-
-
Imagemagick, which will be used for image processing. We'll be using the LYRASIS build of imagemagick here, which supports JP2 files.
-
Tesseract, which will be used for optical character recognition; note that by default Tesseract can only understand English; several other individual Tesseract language packs can be installed using apt-get, and a list of available packs can be procured with sudo apt-cache search tesseract-ocr
NOTICE: If you get the sudo: apt-add-repository: command not found, run sudo apt-get install software-properties-common in order to make the command available.
Not much needs to happen here; Crayfish opts for a simple logging approach, with one .log file for each component. We’ll create a folder where each logfile can live.
Each Crayfish component requires one or more .yaml file(s) to ensure everything is wired up correctly.
-
NOTICE
-
The following configuration files represent somewhat sensible defaults; you should take consideration of the logging levels in use, as this can vary in desirability from installation to installation. Also note that in all cases, http URLs are being used, as this guide does not deal with setting up https support. In a production installation, this should not be the case. These files also assume a connection to a PostgreSQL database; use a pdo_mysql driver and the appropriate 3306 port if using MySQL.
# This file is the entry point to configure your own services.
-# Files in the packages/ subdirectory configure your dependencies.
-# Put parameters here that don't need to change on each machine where the app is deployed
-# https://symfony.com/doc/current/best_practices/configuration.html#application-related-configuration
-parameters:
-app.executable:/usr/local/bin/convert
-app.formats.valid:
--image/jpeg
--image/png
--image/tiff
--image/jp2
-app.formats.default:image/jpeg
-
-services:
-# default configuration for services in *this* file
-_defaults:
-autowire:true# Automatically injects dependencies in your services.
-autoconfigure:true# Automatically registers your services as commands, event subscribers, etc.
-
-# makes classes in src/ available to be used as services
-# this creates a service per class whose id is the fully-qualified class name
-App\Islandora\Houdini\:
-resource:'../src/*'
-exclude:'../src/{DependencyInjection,Entity,Migrations,Tests,Kernel.php}'
-
-# controllers are imported separately to make sure services can be injected
-# as action arguments even if you don't extend any base controller class
-App\Islandora\Houdini\Controller\HoudiniController:
-public:false
-bind:
-$formats:'%app.formats.valid%'
-$default_format:'%app.formats.default%'
-$executable:'%app.executable%'
-tags:['controller.service_arguments']
-
-# add more service definitions when explicit configuration is needed
-# please note that last definitions always *replace* previous ones
-
security:
-
-# https://symfony.com/doc/current/security.html#where-do-users-come-from-user-providers
-providers:
-jwt_user_provider:
-id:Islandora\Crayfish\Commons\Syn\JwtUserProvider
-
-firewalls:
-dev:
-pattern:^/(_(profiler|wdt)|css|images|js)/
-security:false
-main:
-anonymous:false
-# Need stateless or it reloads the User based on a token.
-stateless:true
-
-provider:jwt_user_provider
-guard:
-authenticators:
--Islandora\Crayfish\Commons\Syn\JwtAuthenticator
-
-# activate different ways to authenticate
-# https://symfony.com/doc/current/security.html#firewalls-authentication
-
-# https://symfony.com/doc/current/security/impersonating_user.html
-# switch_user: true
-
-
-# Easy way to control access for large sections of your site
-# Note: Only the *first* access control that matches will be used
-access_control:
-# - { path: ^/admin, roles: ROLE_ADMIN }
-# - { path: ^/profile, roles: ROLE_USER }
-
-
Disabled JWT token authentication:
-
security:
-
-# https://symfony.com/doc/current/security.html#where-do-users-come-from-user-providers
-providers:
-jwt_user_provider:
-id:Islandora\Crayfish\Commons\Syn\JwtUserProvider
-
-firewalls:
-dev:
-pattern:^/(_(profiler|wdt)|css|images|js)/
-security:false
-main:
-anonymous:true
-# Need stateless or it reloads the User based on a token.
-stateless:true
-
Creating Apache Configurations for Crayfish Components¶
-
Finally, we need appropriate Apache configurations for Crayfish; these will allow other services to connect to Crayfish components via their HTTP endpoints.
-
Each endpoint we need to be able to connect to will get its own .conf file, which we will then enable.
-
NOTICE
-
These configurations would potentially have collisions with Drupal routes, if any are created in Drupal with the same name. If this is a concern, it would likely be better to reserve a subdomain or another port specifically for Crayfish. For the purposes of this installation guide, these endpoints will suffice.
Enabling Each Crayfish Component Apache Configuration¶
-
Enabling each of these configurations involves creating a symlink to them in the conf-enabled directory; the standardized method of doing this in Apache is with a2enconf.
The Fedora configuration is going to come in a few different chunks that need to be in place before Fedora will be functional. We’re going to place several files outright, with mildly modified parameters according to our configuration.
-
The basics of these configuration files have been pulled largely from the templates in Islandora-Devops/islandora-playbook internal Fedora role; you may consider referencing the playbook’s templates directory for more details.
i8_namespaces.yml is a list of namespaces used by Islandora that may not necessarily be present in Fedora; we add them here to ensure we can use them in queries.
# Islandora 8/Fedora namespaces
-#
-# This file contains ALL the prefix mappings, if a URI
-# does not appear in this file it will be displayed as
-# the full URI in Fedora.
-acl:http://www.w3.org/ns/auth/acl#
-bf:http://id.loc.gov/ontologies/bibframe/
-cc:http://creativecommons.org/ns#
-dc:http://purl.org/dc/elements/1.1/
-dcterms:http://purl.org/dc/terms/
-dwc:http://rs.tdwg.org/dwc/terms/
-ebucore:http://www.ebu.ch/metadata/ontologies/ebucore/ebucore#
-exif:http://www.w3.org/2003/12/exif/ns#
-fedoraconfig:http://fedora.info/definitions/v4/config#
-fedoramodel:info:fedora/fedora-system:def/model#
-foaf:http://xmlns.com/foaf/0.1/
-geo:http://www.w3.org/2003/01/geo/wgs84_pos#
-gn:http://www.geonames.org/ontology#
-iana:http://www.iana.org/assignments/relation/
-islandorarelsext:http://islandora.ca/ontology/relsext#
-islandorarelsint:http://islandora.ca/ontology/relsint#
-ldp:http://www.w3.org/ns/ldp#
-memento:http://mementoweb.org/ns#
-nfo:http://www.semanticdesktop.org/ontologies/2007/03/22/nfo#
-ore:http://www.openarchives.org/ore/terms/
-owl:http://www.w3.org/2002/07/owl#
-premis:http://www.loc.gov/premis/rdf/v1#
-prov:http://www.w3.org/ns/prov#
-rdf:http://www.w3.org/1999/02/22-rdf-syntax-ns#
-rdfs:http://www.w3.org/2000/01/rdf-schema#
-rel:http://id.loc.gov/vocabulary/relators/
-schema:http://schema.org/
-skos:http://www.w3.org/2004/02/skos/core#
-test:info:fedora/test/
-vcard:http://www.w3.org/2006/vcard/ns#
-webac:http://fedora.info/definitions/v4/webac#
-xml:http://www.w3.org/XML/1998/namespace
-xmlns:http://www.w3.org/2000/xmlns/
-xs:http://www.w3.org/2001/XMLSchema
-xsi:http://www.w3.org/2001/XMLSchema-instance
-
Fedora 6 now allows you to put all your configuration properties into a single file. We use 0640 permissions as you will want to put your database credentials in here.
fcrepo.home=FCREPO_HOME
-# External content using path defined above.
-fcrepo.external.content.allowed=/opt/fcrepo/config/allowed_external_hosts.txt
-# Namespace registry using path defined above.
-fcrepo.namespace.registry=/opt/fcrepo/config/i8_namespaces.yml
-fcrepo.auth.principal.header.enabled=true
-# The principal header is the syn-setting.xml "config" element's "header" attribute
-fcrepo.auth.principal.header.name=X-Islandora
-# false to use manual versioning, true to create a version on each change
-fcrepo.autoversioning.enabled=true
-fcrepo.db.url=FCREPO_DB_URL
-fcrepo.db.user=FCREPO_DB_USERNAME
-fcrepo.db.password=FCREPO_DB_PASSWORD
-fcrepo.ocfl.root=FCREPO_OCFL_ROOT
-fcrepo.ocfl.temp=FCREPO_TEMP_ROOT
-fcrepo.ocfl.staging=FCREPO_STAGING_ROOT
-# Can be sha512 or sha256
-fcrepo.persistence.defaultDigestAlgorithm=sha512
-# Jms moved from 61616 to allow external ActiveMQ to use that port
-fcrepo.dynamic.jms.port=61626
-# Same as above
-fcrepo.dynamic.stomp.port=61623
-fcrepo.velocity.runtime.log=FCREPO_VELOCITY_LOG
-fcrepo.jms.baseUrl=FCREPO_JMS_BASE
-
-
-
FCREPO_HOME - The home directory for all Fedora generated output and state. Unless otherwise specified, all logs, metadata, binaries, and internally generated indexes, etc. It would default to the Tomcat starting directory. A good default would be /opt/fcrepo
-
-
FCREPO_DB_URL - This parameter allows you to set the database connection url. In general the format is as follows:
FCREPO_OCFL_ROOT - Sets the root directory of the OCFL. Defaults to FCREPO_HOME/data/ocfl-root if not set.
-
FCREPO_TEMP_ROOT - Sets the temp directory used by OCFL. Defaults to FCREPO_HOME/data/temp if not set.
-
FCREPO_STAGING_ROOT - Sets the staging directory used by OCFL. Defaults to FCREPO_HOME/data/staging if not set.
-
FCREPO_VELOCITY_LOG - The Fedora HTML template code uses Apache Velocity, which generates a runtime log called velocity.log. Defaults to FCREPO_HOME/logs/velocity. A good choice might be /opt/tomcat/logs/velocity.log
-
FCREPO_JMS_BASE - This specifies the baseUrl to use when generating JMS messages. You can specify the hostname with or without port and with or without path. If your system is behind a NAT firewall you may need this to avoid your message consumers trying to access the system on an invalid port. If this system property is not set, the host, port and context from the user's request will be used in the emitted JMS messages. If your Alpaca is on the same machine as your Fedora and you use the islandora-indexing-fcrepo, you could use http://localhost:8080/fcrepo/rest.
While not strictly necessary, we can use the tomcat-users.xml file to give us direct access to the Fedora endpoint. Fedora defines, out of the box, a fedoraAdmin and fedoraUser role that can be reflected in the users list for access. The following file will also include the base tomcat user. As always, these default passwords should likely not stay as the defaults.
As before, start the Tomcat service to get Fedora up and running.
-
sudosystemctlstarttomcat
-
-
Note: sometimes it takes a while for Fedora and Tomcat to start up, usually it shouldn't take longer than 5 minutes.
-
Once it starts up, Fedora REST API should be available at http://localhost:8080/fcrepo/rest. The username is fedoraAdmin and we defined the password before as FEDORA_ADMIN_PASSWORD (default: "islandora").
For Islandora and Fedora to talk to each other, an SSL key needs to be generated for use with Syn. We’re going to make a spot where such keys can live, and generate one.
Your Fedora web application needs to be deployed in Tomcat with the name fcrepo.war. Otherwise, change the name of the above XML file to match the deployed web application's name.
Finally, restart tomcat to apply the new configurations.
-
sudosystemctlrestarttomcat
-
-
Note: sometimes it takes a while for Fedora and Tomcat to start up, usually it shouldn't take longer than 5 minutes.
-
Note: after installing the Syn valve, you'll no longer be able to manually create/edit or delete objects via Fedora Web UI. All communication with Fedora will now be handled from the Islandora module in Drupal.
Redhat systems have stopped generating an all inclusive catalina.out, the catalina.<date>.log does not include web application's log statements. To get Fedora log statements flowing, you can create your own LogBack configuration file and point to it.
This will generate a log file at ${catalina.base}/logs/fcrepo.log and will rotate each day or if the logs reaches 10MB. It will maintain 30 days of old logs, or 2GB whichever comes first.
The Blazegraph .war file can be found in a few different places, but to ensure we’re able to easily wget it, we’re going to use the maven.org repository link to grab it.
BLAZEGRAPH_WAR_URL: You can find a link to this at the Maven repository for Blazegraph; you’ll want to click the link for the latest version of Blazegraph 2.1.x, then get the link to the .war file within that version folder.
-
-
Once this is downloaded, give it a moment to expand before moving on to the next step.
We would like to have an appropriate logging configuration for Blazegraph, which can be useful for looking at incoming traffic and determining if anything has gone wrong with Blazegraph. Our logger isn’t going to be much different than the default logger; it can be made more or less verbose by changing the default WARN levels. There are several other loggers that can be enabled, like a SPARQL query trace or summary query evaluation log; if these are desired they should be added in. Consult the Blazegraph documentation for more details.
Our configuration will be built from a few different files that we will eventually reference in JAVA_OPTS and directly apply to Blazegraph; these include most of the functional pieces Blazegraph requires, as well as a generalized configuration for the islandora namespace it will use. As with most large configurations like this, these should likely be tuned to your preferences, and the following files only represent sensible defaults.
In order to enable our configuration when Tomcat starts, we need to reference the location of RWStore.properties in the JAVA_OPTS environment variable that Tomcat uses.
The two other files we created, blazegraph.properties and inference.nt, contain information that Blazegraph requires in order to establish and correctly use the datasets Islandora will send to it. First, we need to create a dataset - contained in blazegraph.properties - and then we need to inform that dataset of the inference set we have contained in inference.nt.
The manual installation documentation is in need of attention. We are aware that some components no longer work as documented here. If you are interested in helping us improve the documentation, please see Contributing.
Karaf, as well as its processes and service, will be owned by a user in charge of ensuring this portion of the stack is segregated and that the service is running.
-- KARAF_TARBALL_LINK: It’s recommended to get the most recent version of Karaf 4.2.x. This will depend on the current version of Karaf, which can be found on the Karaf downloads page under “Karaf Runtime”. Like Solr, you can’t directly wget these links, but clicking on the .tar.gz link for the binary distribution will bring you to a list of mirrors, as well as provide you with a recommended mirror you can use here.
-- KARAF_DIRECTORY: This will depend on the exact version being used, but will likely be /opt/apache-karaf-VERSION, where VERSION is the current Karaf version number.
-
We’re going to apply some basic logging to our Karaf installation that should suffice for an example. In a production installation, you may want to play around with some of these values for more personally useful logging.
Similar to Tomcat, our Karaf service is going to rely on a setenv shell script to determine environment variables Karaf needs in place when running. For now, this will simply be the path to JAVA_HOME, but this also accepts many other parameters you can find in the default setenv script.
-
/opt/karaf/bin/setenv | karaf:karaf/755
-
#!/bin/sh
-export JAVA_HOME="PATH_TO_JAVA_HOME"
-
-- PATH_TO_JAVA_HOME: This will be the same JAVA_HOME we used when installing Tomcat , and can be found using the same method (i.e., still /usr/lib/jvm/java-11-openjdk-amd64 if that's what it was before).
-
We’re going to start Karaf, then run the installer to put our configurations in place and generate a Karaf service. Once these are installed, we’re going to stop Karaf, as from there on out its start/stop management should be handled via that service.
-
First we need to enable the default Karaf user in /opt/karaf/etc/users.properties:
sudo-ukaraf/opt/karaf/bin/start
-# You may want to wait a bit for Karaf to start.
-# If you're not sure whether or not it's running, you can always run:
-# ps aux | grep karaf
-# to see if the server is up and running.
-/opt/karaf/bin/clientfeature:installwrapper
-/opt/karaf/bin/clientwrapper:install
-/opt/karaf/bin/stop
-
Installing the Karaf wrapper generates several service files that can be used on different types of systems. For Debian and Ubuntu installation we want to enable the karaf.service service so that Karaf is properly started on boot.
Karaf features can be installed from several different types of sources, but the fastest and easiest way to do so is from existing repository URLs that we can just plug into Karaf to provide us feature lists prepared and ready for installation. Like most interactions with Karaf, we can add these repositories using its built-in client.
-
-
Notice
-
These repositories are updated consistently, and their updates include revised dependency lists. Commonly, when repositories are out of date or otherwise mismatched, feature installation can result in an Unable to resolve root: missing requirement error; for this reason, this guide recommends using recently-updated versions of these repositories. That being said, if such errors occur despite installing the latest versions of these features, the maintainer of the features repository should be informed.
-
-
For the Karaf features we’re going to install, we need a few different repositories to be added to the list:
-
/opt/karaf/bin/clientrepo-addmvn:org.apache.activemq/activemq-karaf/ACTIVEMQ_KARAF_VERSION/xml/features
-/opt/karaf/bin/clientrepo-addmvn:org.apache.camel.karaf/apache-camel/APACHE_CAMEL_VERSION/xml/features
-/opt/karaf/bin/clientrepo-addmvn:ca.islandora.alpaca/islandora-karaf/ISLANDORA_KARAF_VERSION/xml/features
-# XXX: This shouldn't be strictly necessary, but appears to be a missing
-# upstream dependency for some fcrepo features.
-/opt/karaf/bin/clientrepo-addmvn:org.apache.jena/jena-osgi-features/JENA_OSGI_VERSION/xml/features
-
-- ACTIVEMQ_KARAF_VERSION: The version of ActiveMQ we wrote down at the beginning of this chapter when installing ActiveMQ via apt-get
-- APACHE_CAMEL_VERSION: The latest version of Apache Camel 2.x.x; you can find this listed at the apache-camel repository page (e.g., 2.25.4 at the time of writing)
-- ISLANDORA_KARAF_VERSION: The latest version of Islandora Karaf 1.x; you can find this listed at the islandora-karaf repository page (e.g., 1.0.5 at the time of writing)
-- JENA_OSGI_VERSION: The latest version of the Apache Jena 3.x OSGi features; you can find this listed at the jena-osgi-features repository page (e.g., 3.17.0 at the time of writing)
-
For those services in Crayfish we have set up to provide derivatives to Islandora resources, we need connector blueprints to tell the derivative connector how to route incoming requests, run conversions, and return outgoing derivatives.
-
Our blueprints are going to look largely similar between services, with only a few properties changing between them. Largely, these mainly just need to match the ActiveMQ queues we established in the previous configuration, and route to the correct Crayfish service.
Before we can configure the features we’re going to use, they need to be installed. Some of these installations may take some time.
-
/opt/karaf/bin/clientfeature:installcamel-blueprint
-/opt/karaf/bin/clientfeature:installactivemq-blueprint
-/opt/karaf/bin/clientfeature:installfcrepo-service-activemq
-# This again should not be strictly necessary, since this isn't the triplestore
-# we're using, but is being included here to resolve the aforementioned
-# missing link in the dependency chain.
-/opt/karaf/bin/clientfeature:installjena
-/opt/karaf/bin/clientfeature:installfcrepo-camel
-/opt/karaf/bin/clientfeature:installfcrepo-indexing-triplestore
-/opt/karaf/bin/clientfeature:installislandora-http-client
-/opt/karaf/bin/clientfeature:installislandora-indexing-triplestore
-/opt/karaf/bin/clientfeature:installislandora-indexing-fcrepo
-/opt/karaf/bin/clientfeature:installislandora-connector-derivative
-
-
Verifying Karaf Components are Running (Optional But Recommended)¶
-
At this point, Karaf components should be up and running, but it's a good idea to double-check that this is the case. We can do this from within the Karaf client by taking a look at its component list.
-
# Until this point, we've been running Karaf commands from outside; we can hop
-# into the client, however, and run commands from directly within.
-/opt/karaf/bin/client
-# This takes us into the Karaf client so we can run commands.
-la|grepislandora
-la|grepfcrepo
-# It may be a good idea to use this to look up to the other components we
-# installed.
-logout
-
-
For the above la | grep commands, components that are running should be listed as Active.
The manual installation documentation is in need of attention. We are aware that some components no longer work as documented here. If you are interested in helping us improve the documentation, please see Contributing.
The Solr binaries can be found at the Solr downloads page; the most recent stable release of Solr 8 should be used.
-
# While generally we download tarballs as .tar.gz files without version
-# information, the Solr installer is a bit particular in that it expects a .tgz
-# file with the same name as the extracted folder it contains. It's odd, and we
-# can't really get around it.
-cd
-wgetSOLR_DOWNLOAD_LINK
-tar-xzvfSOLR_TARBALL
-
-- SOLR_DOWNLOAD_LINK: NOTICE: This will depend on a few different things, not least of all the current version of Solr. The link to the .tgz for the binary on the downloads page will take you to a list of mirrors that Solr can be downloaded from, and provide you with a preferred mirror at the top. This preferred mirror should be used as the SOLR_DOWNLOAD_LINK.
-- SOLR_TARBALL: The filename that was downloaded, e.g., solr-8.9.0.tgz
-
Solr includes an installer that does most of the heavy lifting of ensuring we have a Solr user, a location where Solr lives, and configurations in place to ensure it’s running on boot.
Solr's installation guide recommends that you increase the open file limit so that operations aren't disrupted while Solr is trying to access things in its index. This limit can be increased while the system is running, but doing so won't persist after a reboot. You can hard-increase this limit using your system's sysctl file:
Initially, our new Solr core will contain a configuration copied from the example included with the installation, so that we have something to work with when we configure this on the Drupal side. We’ll later update this with generated configurations we create in Drupal.
WARNING: Using _default configset with data driven schema functionality. NOT RECOMMENDED for production use.
- To turn off: bin/solr config -c islandora8 -p 8983 -action set-user-property -property update.autoCreateFields -value false
-
-Created new core 'islandora8'
-
Rather than use an out-of-the-box configuration that won’t be suitable for our purposes, we’re going to use the Drupal search_api_solr module to generate one for us. This will also require us to install the module so we can create these configurations using Drush.
The following module(s) will be enabled: search_api_solr, language, search_api
-
- // Do you want to continue?: yes.
-
- [success] Successfully enabled: search_api_solr, language, search_api
-
Before we can create configurations to use with Solr, the core we created earlier needs to be referenced in Drupal.
-
Log in to the Drupal site at /user using the sitewide administrator username and password (if using defaults from previous chapters this should be islandora and islandora), then navigate to /admin/config/search/search-api/add-server.
-
Fill out the server addition form using the following options:
-
-
-
-
-
SERVER_NAME: islandora8
-
This is completely arbitrary, and is simply used to differentiate this search server configuration from all others. Write down or otherwise pay attention to the machine_name generated next to the server name you type in; this will be used in the next step.
-
-
-
-
As a recap for this configuration:
-
-
Server name should be an arbitrary identifier for this server
-
Enabled should be checked
-
Backend should be set to Solr
-
Under CONFIGURE SOLR BACKEND, Solr Connector should be set to Standard
-
Under CONFIGURE STANDARD SOLR CONNECTOR:
-
HTTP protocol is simply set to http since we've set this up on the same machine Drupal lives on. On a production installation, Solr should likely be installed behind an HTTPS connection.
-
Solr host can be set to localhost since, again, this is set up on the same machine Drupal lives on. On a production installation, this may vary, especially if parts of the installation live on different severs
-
Solr port should be set to the port Solr was installed on, which is 8983 by default
-
Solr path should be set to the configured path to the instance of Solr; in a default installation, there is only one Solr instance, and it lives at /
-
Solr core should be the name of the Solr core you created earlier, which is why it's listed as SOLR_CORE here
-
-
-
Under ADVANCED SERVER CONFIGURATION, solr.install.dir should be set to the path where we installed Solr, which this guide has established at /opt/solr
-
-
Click Save to create the server configuration.
-
NOTICE
- You can ignore the error about an incompatible Solr schema; we're going to set this up in the next step. In fact, if you refresh the page after restarting Solr in the next step, you should see the error disappear.
Now that our core is in place and our Drupal-side configurations exist, we’re ready to generate Solr configuration files to connect this site to our search engine.
In order for content to be indexed back into Solr, a search index needs to be added to our server. Navigate to /admin/config/search/search-api/add-index and check off the things you'd like to be indexed.
-
NOTICE
- You should come back here later and reconfigure this after completing the last step in this guide. The default indexing configuration is pretty permissive, and you may want to restrict, for example, indexed content to just Islandora-centric bundles. This guide doesn't set up the index's fields either, which are going to be almost wholly dependent on the needs of your installation. Once you complete that configuration later on, re-index Solr from the configuration page of the index we're creating here.
-
-
-
Click Save to add your index and kick off indexing of existing items.
The manual installation documentation is in need of attention. We are aware that some components no longer work as documented here. If you are interested in helping us improve the documentation, please see Contributing.
Tomcat runs in a Java runtime environment, so we'll need one to continue. In our case, OpenJDK 11 is open-source, free to use, and can fairly simply be installed using apt-get:
The installation of OpenJDK via apt-get establishes it as the de-facto Java runtime environment to be used on the system, so no further configuration is required.
-
The resultant location of the java JRE binary (and therefore, the correct value of JAVA_HOME when it’s referenced) will vary based on the specifics of the machine it’s being installed on; that being said, you can find its exact location using update-alternatives:
-
update-alternatives--listjava
-
-Take a note of this path as we will need it later.
-
Apache Tomcat, and all its processes, will be owned and managed by a specific user for the purposes of keeping parts of the stack segregated and accountable.
Tomcat 9 itself can be installed in several different ways; while it’s possible to install via apt-get, this doesn’t give us a great deal of control over exactly how we’re going to run and manage it; as a critical part of the stack, it is beneficial for our purposes to have a good frame of reference for the inner workings of Tomcat.
-
We’re going to download the latest version of Tomcat to /opt and set it up so that it runs automatically. Bear in mind that with the following commands, this is going to be entirely relative to the current version of Tomcat 9, which we’ll try to mitigate as we go.
-- TOMCAT_TARBALL_LINK: No default can be provided here; you should navigate to the Tomcat 9 downloads page and grab the link to the latest .tar.gz file under the “Core” section of “Binary Distributions”. It is highly recommended to grab the latest version of Tomcat 9, as it will come with associated security patches and fixes.
-- TOMCAT_DIRECTORY: This will also depend entirely on the exact version of tomcat downloaded - for example, apache-tomcat-9.0.50. Again, ls /opt can be used to find this.
-
-- PATH_TO_JAVA_HOME: This will vary a bit depending on the environment, but will likely live in /usr/lib/jvm somewhere (e.g., /usr/lib/jvm/java-11-openjdk-amd64); again, in an Ubunutu environment you can check a part of this using update-alternatives --list java, which will give you the path to the JRE binary within the Java home. Note that update-alternatives --list java will give you the path to the binary, so for PATH_TO_JAVA_HOME delete the /bin/java at the end to get the Java home directory, so it should look something like this:
-
Tomcat includes two shell scripts we’re going to make use of - startup.sh and shutdown.sh - which are light wrappers on top of a third script, catalina.sh, which manages spinning up and shutting down the Tomcat server.
-
Debian and Ubuntu use systemctl to manage services; we’re going to create a .service file that can run these shell scripts.
We’re going to both enable and start Tomcat. Enabling Tomcat will ensure that it starts on boot, the timing of which is defined by the [Install] section’s WantedBy statement, which specifies what it should start after. This is separate from starting it, which we need to do now in order to get Tomcat up and running without requiring a reboot.
We can check that Tomcat has started by running sudo systemctl status tomcat | grep Active; we should see that Tomcat is active (running), which is the correct result of startup.sh finishing its run successfully.
Since version 5, Cantaloupe is released as a standalone Java application and is no longer deployed in Tomcat via a .war file. Even so, we can still fine-tune how it runs and even install it as a service.
-- CANTALOUPE_RELEASE_URL: It’s recommended we grab the latest version of Cantaloupe 5. This can be found on the above-linked release page, as the .zip version; for example, https://github.com/cantaloupe-project/cantaloupe/releases/download/v5.0.3/cantaloupe-5.0.3.zip - make sure not to download the source code zip file as that isn't compiled for running out-of-the-box.
-
Cantaloupe pulls its configuration from a file called cantaloupe.properties; there are also some other files that can contain instructions for Cantaloupe while it’s running; specifically, we’re going to copy over the delegates.rb file, which can also contain custom configuration. We won’t make use of this file; we’re just copying it over for demonstration purposes.
-
Creating these files from scratch is not recommended; rather, we’re going to take the default cantaloupe configurations and plop them into their own folder so we can work with them.
-- CANTALOUPE_VER: This will depend on the exact version of Cantaloupe downloaded; in the above example release, this would be cantaloupe-5.0.3
-
The out-of-the-box configuration will work fine for our purposes, but it’s highly recommended that you take a look through the cantaloupe.properties and see what changes can be made; specifically, logging to actual logfiles isn’t set up by default, so you may want to take a peek at the log.application.SyslogAppender or log.application.RollingFileAppender, as well as changing the logging level.
-
Installing and configuring Cantaloupe as a service¶
-
Since it is a standalone application, we can configure Cantaloupe as a systemd service like we did with Tomcat, so it can start on boot:
We can check the service status with sudo systemctl status cantaloupe | grep Active and the splash screen of Cantaloupe should be available at http://localhost:8182
The manual installation documentation is in need of attention. We are aware that some components no longer work as documented here. If you are interested in helping us improve the documentation, please see Contributing.
Apache 2, the webserver that will deliver webpages to end users
+
PHP 7, the runtime code interpreter that Drupal will use to generate webpages and other services via apache, as well as that Drush and Composer will use to run tasks from the command line
+
Several modules for PHP 7 which are required to run the PHP code that Drupal and other applications will be executing
+
PostgreSQL 10, the database that Drupal will use for storage (as well as other applications down the line)
Apache can typically be installed and configured outright by your operating system’s package manager:
+
sudoapt-get-yinstallapache2apache2-utils
+
+
This will install:
+
+
A systemd service that will ensure Apache can be stopped and started, and will run when the machine is powered on
+
A set of Apache configurations in /etc/apache2, including the basic configuration, ports configuration, enabled mods, and enabled sites
+
An Apache webroot in /var/www/html, configured to be the provided server on port :80 in /etc/apache2/sites-enabled/000-default.conf; we’ll make changes and additions to this file later
+
A user and group, www-data, which we will use to read/write web documents.
Since the user we are currently logged in as is going to work quite a bit inside the Drupal directory, we want to give it group permissions to anything the www-data group has access to. When we run composer, www-data will also be caching data in our own home directory, so we want this group modification to go in both directions.
+
N.B. This code block uses backticks, not single quotes; this is an important distinction as backticks have special meaning in bash.
+
Note If doing this in the terminal, replace "whoami" with your username and remove the backticks
+
sudousermod-a-Gwww-data`whoami`
+sudousermod-a-G`whoami`www-data
+# Immediately log back in to apply the new group.
+sudosu`whoami`
+
This will install a series of PHP configurations and mods in /etc/php/7.4, including:
+
+
A mods-available folder (from which everything is typically enabled by default)
+
A configuration for PHP when run from Apache in the apache2 folder
+
A configuration for PHP when run from the command line - including when run via Drush - in the cli folder
+
unzip, which is important for PHP’s zip module to function correctly despite it not being a direct dependency of the module. We will also need to unzip some things later, so this is convenient to have in place early in the installation process.
PostgreSQL can generally be easily installed using your operating system’s package manager. It is typically sensible to install the version the system recognizes as up-to-date. We’re simply going to install the database software:
+
sudoapt-get-yinstallpostgresql
+
+
This will install:
+
+
A user at the system level named postgres; this will be the only user, by default, that has permission to run the psql binary and have access to Postgres configurations
+
A binary executable at /usr/bin/psql, which anyone - even root - will get kicked out of the moment they run it, since only the postgres user has permission to run any Postgres commands
+
A series of configurations that live in /etc/postgresql/11/main which can be used to modify how PostgreSQL works.
A modification needs to be made to the PostgreSQL configuration in order for Drupal to properly install and function. This change can be made to the main configuration file at /etc/postgresql/11/main/postgresql.conf:
+
Before:
+
+
558 | #bytea_output = ‘hex’ # hex, escape
+
+
After:
+
+
558 | bytea_output = ‘escape’
+
+
(Remove the "# hex, escape" comment and change the value from "hex" to "escape")
+
The postgresql service should be restarted to accept the new configuration:
The manual installation documentation is in need of attention. We are aware that some components no longer work as documented here. If you are interested in helping us improve the documentation, please see Contributing.
Apache 2, the webserver that will deliver webpages to end users
-
PHP 7, the runtime code interpreter that Drupal will use to generate webpages and other services via apache, as well as that Drush and Composer will use to run tasks from the command line
-
Several modules for PHP 7 which are required to run the PHP code that Drupal and other applications will be executing
-
PostgreSQL 10, the database that Drupal will use for storage (as well as other applications down the line)
Apache can typically be installed and configured outright by your operating system’s package manager:
-
sudoapt-get-yinstallapache2apache2-utils
-
-
This will install:
-
-
A systemd service that will ensure Apache can be stopped and started, and will run when the machine is powered on
-
A set of Apache configurations in /etc/apache2, including the basic configuration, ports configuration, enabled mods, and enabled sites
-
An Apache webroot in /var/www/html, configured to be the provided server on port :80 in /etc/apache2/sites-enabled/000-default.conf; we’ll make changes and additions to this file later
-
A user and group, www-data, which we will use to read/write web documents.
Since the user we are currently logged in as is going to work quite a bit inside the Drupal directory, we want to give it group permissions to anything the www-data group has access to. When we run composer, www-data will also be caching data in our own home directory, so we want this group modification to go in both directions.
-
N.B. This code block uses backticks, not single quotes; this is an important distinction as backticks have special meaning in bash.
-
Note If doing this in the terminal, replace "whoami" with your username and remove the backticks
-
sudousermod-a-Gwww-data`whoami`
-sudousermod-a-G`whoami`www-data
-# Immediately log back in to apply the new group.
-sudosu`whoami`
-
This will install a series of PHP configurations and mods in /etc/php/7.4, including:
-
-
A mods-available folder (from which everything is typically enabled by default)
-
A configuration for PHP when run from Apache in the apache2 folder
-
A configuration for PHP when run from the command line - including when run via Drush - in the cli folder
-
unzip, which is important for PHP’s zip module to function correctly despite it not being a direct dependency of the module. We will also need to unzip some things later, so this is convenient to have in place early in the installation process.
PostgreSQL can generally be easily installed using your operating system’s package manager. It is typically sensible to install the version the system recognizes as up-to-date. We’re simply going to install the database software:
-
sudoapt-get-yinstallpostgresql
-
-
This will install:
-
-
A user at the system level named postgres; this will be the only user, by default, that has permission to run the psql binary and have access to Postgres configurations
-
A binary executable at /usr/bin/psql, which anyone - even root - will get kicked out of the moment they run it, since only the postgres user has permission to run any Postgres commands
-
A series of configurations that live in /etc/postgresql/11/main which can be used to modify how PostgreSQL works.
A modification needs to be made to the PostgreSQL configuration in order for Drupal to properly install and function. This change can be made to the main configuration file at /etc/postgresql/11/main/postgresql.conf:
-
Before:
-
-
558 | #bytea_output = ‘hex’ # hex, escape
-
-
After:
-
-
558 | bytea_output = ‘escape’
-
-
(Remove the "# hex, escape" comment and change the value from "hex" to "escape")
-
The postgresql service should be restarted to accept the new configuration:
-
sudosystemctlrestartpostgresql
-
-
-
-
-
-
- Last update:
- November 1, 2023
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
+
+
+
+ Redirecting...
+
+
+
+
+
+
+Redirecting...
+
+
diff --git a/installation/playbook/index.html b/installation/playbook/index.html
index dcc50414f..c78ce3c88 100644
--- a/installation/playbook/index.html
+++ b/installation/playbook/index.html
@@ -481,7 +481,7 @@
Drupal provides an "Audio" field formatter for file fields that displays a simple playable audio widget. It works but does not support captions/subtitles. Islandora provides an "Audio with captions" formatter that allows for captions.
To use the captions feature out of the box, add the captions track as a WEBVTT file (.vtt) in the Audio media's "Track" field (see below regarding which Audio media to use). If you don't have the "Track" field (provided by Islandora Starter Site), create a field of type "Media Track" (a type provided by Islandora) on the same Media (or more broadly, same entity) as your audio file. Then use the Manage Display page to set your audio file field to render using the "Audio with captions" field formatter.
+
+
+
