Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The administration entry point has been streamlined and is now accessible via a single link at the bottom of the page. This update focuses on reducing distractions, consolidating similar configuration options, and prioritizing key information for administrators. Application and health information remains available, but it is less prominent unless there is a critical notice, making the dashboard cleaner and more focused on the tasks administrators typically log in to manage. All configuration options from the previous version have been condensed into a more efficient, centralized menu.
On the right side of the dashboard, a notifications and details section provides real-time information about site health, data, and indexing processes. If any issues arise, such as indexing errors or offline dependencies like Solr, notifications will appear prominently, eliminating the need for administrators to search for critical updates. These changes ensure that administrators can quickly access the most relevant information and address any potential issues without unnecessary complications.
In eMuseum, there are several types of translatable content, including the user interface (UI), field labels, and field values. The UI encompasses elements like the menu (collections, objects, people, exhibitions) and labels such as "of" in result counts or placeholder text in search fields. Field labels refer to terms like dimensions, medium, and credit. Both the UI and field labels can be translated directly within the eMuseum configuration section. However, field value translations are created and managed in TMS alongside the collection metadata. With the language switcher now integrated into the General Settings page of the eMuseum admin UI, administrators can easily enable or disable supported languages. This replaces the old process, which required XML file modifications on the server. Now, adding a new language, such as French, is as simple as selecting it from a dropdown, making the entire system much more accessible.
The translation of UI labels is managed through the eMuseum admin interface, allowing administrators to change labels, such as renaming "objects" to "artworks" and translating them to other languages like German. For field labels such as Dimensions or Medium, the translations are managed on the field configuration page, where administrators can define how labels appear in different languages. For field values, TMS offers several translation methods. Titles can be translated using language-specific entries, while other fields like descriptions and mediums can be handled through text entries, which allow for specific language assignments. Administrators can choose between standard or single-value text entries for more organized translation management. Once translations are completed in TMS, eMuseum can be configured to display them globally, with a multilingual column controlling which fields show translated values. If a translation isn’t available, eMuseum will default to the original language, ensuring a seamless user experience across multiple languages.
This new option automatically triggers when a user's search returns no results. This feature analyzes the search input and suggests alternative searches based on closely matching terms or available values within the collection. It's particularly useful for handling common typos or misspellings, offering suggestions that align with actual data in the system. By providing relevant alternatives, the "Did You Mean" feature enhances the search experience, ensuring that users are guided toward successful results even if their initial query is inaccurate.
Before version 6.5, eMuseum had numerous separate configuration pages for settings that have now been consolidated into a more streamlined interface. While some pages contained more settings than others, each served as an entry point to different sections of your online collection, all with their own menu items. Consolidating these pages and modules allowed us to introduce additional features without sacrificing functionality. Administrators can still view which modules and pages are enabled for the site and directly edit those pages, such as modifying the collections page banner or adjusting display options.
One significant enhancement is the ability to designate the homepage directly within the UI. Previously, setting the homepage required server access and manual file modification, which not all users had. Now, administrators can assign the homepage within this consolidated configuration table. Additionally, an "Order" column has been added, allowing for easy reordering of menu items using drag and drop. This feature enables changes to the order of key sections like Collections, Objects, People, and Exhibitions, which will automatically adjust their corresponding menu items, eliminating the need for customizations required in earlier versions.
Create complex searches straight from the Keyword Search bar without needing the Advanced Search or Filters. Search on specific fields using the field:value format (e.g. classification:"furniture").
eMuseum 6 puts you in control, allowing administrators to change the look and feel of your site with a set of easily useable controls—no coding required. Quickly manage fonts, colors, and spacing on your eMuseum site, from large elements such as the header, footer, and menu to complex elements such as the filter panel, result grid items, and detail page layout. Customizing your eMuseum site has never been easier.
eMuseum 6 expands on the Categories page with the addition of Search Groups. Now, admins can create groups of pre-defined queries in eMuseum, which can be nested and given their representative name, notes, and image, adding a new dimension to your online collection.
In the new version of eMuseum, administrators can easily control the availability of media types and derivatives for specific user roles. Additionally, admins can grant download permissions and create custom image derivatives for downloading or other purposes from the configuration interface.
eMuseum 6 includes new Loans and Events modules, so you can easily search, filter, and relate Loans and Events to your other eMuseum content.
The Getty Research Institute’s Union List of Artist Names (ULAN) database is a powerful resource for digital collections. This free database tool houses the information and historical context of over 300,000 artists with more than 720,000 entries. With eMuseum 6, you can easily link your constituent records to this resource using TMS and eMuseum.
Configure and style reports in eMuseum’s all-new Reports Manager. Administrators can create unlimited reports for any module and view, with configurable fields and security applied to all.
Manage data and media exchange between TMS and eMuseum seamlessly through eMuseum’s new companion application—Prism. Prism replaces SQL import scripts and the eMuseum Thumbnailer, handling all media management. Prism allows admins to easily configure the publication criteria and field data published to eMuseum and how often data is pushed to eMuseum. Managing the publication of data and media and keeping it nearly in sync with TMS is not only possible with Prism—it’s effortless.
Collection highlights and custom ordering: Collections can be manually ordered, and package Objects will display in the same order set in TMS Package Explorer. Collection detail pages also display a preview of highlighted objects.
Infinite scrolling: Optionally disable standard paging in favor of Infinitely scrolling through search results.
Search autocomplete: Configure emuseum to suggest searches based on Select field criteria.
Similar works: Display similar works on all module detail pages Derived from configurable common field data.
Page and module restrictions: Set top-level restrictions on entire modules (objects, exhibitions, loans, etc.) and pages (favorites, thesaurus, groups) to select user roles.
Privacy settings: Set a custom privacy policy and display a privacy Banner. Mass export and/or delete user data, And more.
Instant image zooming: Images can be set to zoom automatically with a single configuration option.
Dozens of new configuration options, including:
Numerous new field options
Extensive usability improvements
Seo enhancements
Support for accessibility
Faster indexing
Starting with eMuseum 6, data and media transfers to eMuseum are done on the application level. No direct database connection from eMuseum to TMS is required anymore. For this, the utility application Prism is required on the TMS side to collect the data and media and push both to eMuseum via HTTPS.
The following diagram shows the architecture of eMuseum with network connections between eMuseum, Prism, and TMS:
Arrows indicate the direction of access, not the direction of data-flow. There is no access against the direction of an arrow. For example, the eMuseum server does not initiate a connection to the Prism server.
This document describes the process of upgrading an installed instance of the eMuseum application. It is recommended to stop the application server before any of the steps mentioned below. Start it a
Before upgrading any part, make sure to backup the following files and folders in the EMUSEUM_HOME directory:
customcss/
logos/
profiles/
watermarks/
skins/
messages/
config.xml
If an external database is used, backup the database using the tools provided by the database management system.
The update of the required software, including Java, Tomcat, and Solr, is independent of the update of eMuseum itself and should be done regularly. Update the runtime environment and the application server and re-apply all custom configuration options.
Download the new installation package and extract its content into the EMUSEUM_HOME directory. Ensure all files and sub-directories are still readable and writable by the user under which the application server runs.
Run the SQL statements from the against the eMuseum database via any method suitable for the database system.
Deploy the new war file to the application server as described in the . If the “auto-deployment” feature is enabled, this can be done by copying the file EMUSEUM_HOME/bin/emuseum.war (the filename will include the new version, e. g. emuseum-6.2.war ) to the directory TOMCAT_HOME/webapps/. Make sure to adjust the file name to match the existing one in the webapps folder before copying the file.
Check the release notes for the version you're updating for any additional steps.
The Email Parameters and Event Logging configuration settings allow you to configure eMuseum to work with your SMTP email server. When Email is configured, eMuseum will use the information to send password reminder emails to registered users upon request (and may also send administrator-level messages to the configured administrator address on certain application events).
Enter your default "From" email address here. This address will be displayed to the user receiving emails from eMuseum, and is typically be an address that users should not reply to (e.g., [email protected]).
Enter the correct Port number here. The default SMTP port number is usually 587, but your SMTP server may require a different port. The port number also depends on the security setting (see below). Please confirm the correct port number with your network administrator.
Enter the user name and password that will be used to authenticate to the SMTP server if your server does not allow anonymous delivery.
By default, eMuseum uses "localhost" as the name for the SMTP server. If this is not a valid name for your SMTP server, enter the appropriate name, along with a valid user account login and password. The SMTP server IP address may also be used.
Select the security option that is supported by the SMTP server. There are three options available:
None No security. This option is generally not recommended, passwords are send in plain text without encryption.
StartTLS Good security that uses the same port as unencrypted SMTP (usually 587).
TLS (formerly SSL) Good security that uses a dedicated port (usually 465).
By checking the "Enabled Event Logging" box, the subscribed email address will be able to receive log output from application events, such as data imports and indexing, via email.
This option allows administrators to email the input email address to test whether the SMTP server is configured correctly and working based on values entered in the "Email Parameters" section.
The "Groups" feature in eMuseum6 introduces a range of functionalities aimed at enhancing the organization and browsing experience of records. This comprehensive feature enables administrators to create, manage, and nest groups based on field categories or specific search criteria. Users can easily browse through related items by grouping records, streamlining their access to relevant information.
One aspect of the "Groups" feature is the ability to create category groups. Administrators can define groups of browsable records from any module, utilizing a specific field as the basis for grouping. This categorization enables users to explore records associated with each distinct value in the selected field. By leveraging category groups, administrators can create logical associations between records and enhance user navigation within the system.
Additionally, the "Groups" feature offers search groups, empowering administrators to generate groups based on keyword searches, advanced search queries, or filtered search results. These search-generated groups provide users with direct access to result sets that match the specified search criteria.
Administrators can leverage the concept of parent groups within the "Groups" feature. Parent groups serve as containers for nesting other groups, such as search or category groups. By creating empty groups without specific module, field, or query associations, administrators can establish a hierarchical structure for organizing related groups. This nesting capability facilitates a multi-level grouping approach, allowing users to navigate through parent groups to access the associated nested groups conveniently.
This article is going to demonstrate how to create the three types of groups mentioned above:
eMuseum superuser login
Enable "Groups" page under Configuration > Page Management > Groups > Configuration tab
Go to Configuration > Page Management > Groups > Groups List tab.
Click on "Create New Group".
Enter the desired name for the group, which will be displayed on your site.
The URL path for the group will be automatically generated, but you can customize it if needed.
Automatic URL generation was introduced in v6.4
In the Parent Group drop-down list, choose whether the group should appear at the root level or as a branch of a parent group on the page.
Optionally, provide a description that will be shown on the page for this group.
Select "Parent Group"
Click "Submit"
Go to Configuration > Page Management > Groups > Groups List tab.
Click on "Create New Group".
Enter the desired name for the group, which will be displayed on your site.
The URL path for the group will be automatically generated, but you can customize it if needed.
Automatic URL generation was introduced in v6.4
In the Parent Group drop-down list, choose whether the group should appear at the root level or as a branch of a parent group on the page.
Optionally, provide a description that will be shown on the page for this group.
Select "Category Group" from the available options.
Choose the field to group on from the drop-down list.
Click "Submit"
Note that the list of grouping fields in Step (8) is generated based on the fields configured under Configuration > Data and Search Settings > Field Configuration > Search tab > Filters section.
Do an advanced search
On the Result page, click "Add New Group"
Note that the position of the button may vary depending on your eMuseum skin, but it is typically found above the result list.
Enter a Group Name for the new group.
Use the Parent Group drop-down list to determine whether the group will appear at the root level (top level) on the page or as a branch of a Parent Group.
Optionally, provide a description that will be displayed on the page for this Group.
Click "Create Group"
Documentation of the eMuseum API.
All requests follow the HTT protocol with the following values and are stateless:
Headers HTTP header fields
Path parameters URL path segments
Query parameters URL query parameters
All parameters use percent-encoding.
To access content that requires authentication, username and password of an eMuseum user have to be specified in the Authentication Header using the Basic authentication scheme.
If authorization is required, there are two options to include the corresponding API key in the request:
Query parameter: key
Header: X-API-Key
All responses follow the HTT protocol and include a status code which determines the content of the response.
The eMuseum API supports the following output formats (specified by the <format> request parameter):
xml
json
rdf
Records are referenced by their identifier (specified by the <identifier> request parameter). Please note that identifiers are strings, not numbers. Even though most of them look like numbers (e. g. “1” or “123”), they can contain alphanumeric characters (e. g. “1-1” or “5-123”).
The eMuseum API does not use a shared base URL but follows the URLs that are used by the UI.
The <module> is one of the following module names though some of them might not be enabled:
objects
people
exhibitions
media
bibliography
sites
events
loans
The following endpoints are provided by all modules:
/<module>/<format>
List all records of a module.
/<module>/<identifier>/<format>
Get the details of a record.
The following endpoints are provided by all modules except the Objects module:
/<module>/<identifier>/objects/<format>
List all related Object records for a record.
Collections can be accessed by the following endpoints:
/collections/<format>
List all Collections
/collections/<identifier>/<format>
Get the details of a Collection
/collections/<identifier>/objects/<format>
List the Object records within a Collection.
/groups/<url>/results/<format>
List all records of a search group.
/groups/<url>/category/<value>/<format>
List all records of a category group for a category value.
/favorites/<id>/objects/<format>
List all Object records within a Favorite.
/search/<query>/<module>/<format>
List all search results of a Module-specific search.
/advancedsearch/<module>/<query>/<format>
List all search results of a Module-specific search.
All result pages (i. e. pages that list multiple records) support the following common query parameters.
Result pages are limited to 100 records by default. Via the query parameter page a page can be requested. The values start at 1.
The order of records on result pages can be controlled with the query parameter sort. The value contains the field name and an option suffix to control ascending (-asc) or descending (-desc).
For (quick and advanced) search results the additional sort field “relevance” is supported.
For Collection Objects the additional sort field “collection” is supported.
Examples:
sort=relevance
sort=title-asc
sort=invno-desc
Result pages can be filtered by applying the query parameter filter.
Multiple filters are concatenated by a semicolon. Each filter requires a field and at least one value, separated by colon. Multiple values for a field are separated by comma.
Examples:
filter=field:value
filter=field:value1,value2
filter=field1:value1;field2:value1,value2
How to add Google Analytics to <Head> section of the HTML with eMuseum 6
Please note the following:
We have planned to include Google Analytics in different sections of the HTML in eMuseum version 6.5
If your eMuseum site is hosted by Gallery Systems, please reach out to Gallery Systems support and request the change instead
In eMuseum6.4.* and prior versions, there is not a configuration setting to add Google Analytics to <Head> section of the HTML, this article is going to step you through how to achieve it by modifying the Layout.tml skin file.
The file location of Layout.tml may differ for each client, especially when custom eMuseum skin is applied.
First of all, go to eMuseum Configuration page > Display Settings > Skins, or this url path http(s)://eMuseumUrl/configuration/skins, and check which skin is selected currently.
Internal implies that your eMuseum application is reading the skin files directly from <Tomcat_home>\webapps directory and that you are NOT using a custom skin.
If Internal is selected, proceed further down this guide to (2) When a custom skin is NOT applied.
If your skin is NOT "Internal", mark the skin name and locate the skin folder under <eMuseum_home>\skins folder. Proceed to (1) When a custom skin is applied.
(1) When a custom skin is applied
Navigate to <eMuseum_home>\skins\[skinName]\com\gallerysystems\emuseum\core\components
If this directory does not exist,
create this directory
Check whether Layout.tml exists under the component folder
If not, copy Layout.tml from <Tomcat_home>\webapps\[root]\WEB-INF\classes\com\gallerysystems\emuseum\core\components
paste Layout.tml to <eMuseum_home>\skins\[skinName]\com\gallerysystems\emuseum\core\components
note that if eMuseum is not the root directory, you need to replace the root folder (<Tomcat_home>\webapps\[root]) with the actual eMuseum folder name (e.g.,<Tomcat_home>\webapps\emuseum)
Open Layout.tml file
Find <t:statisticstrackingcode />
Copy and paste it to other sections of the file as needed
Save
If your eMuseum is in Production mode, restart Apache Tomcat for the change to take effect
(2) When a custom skin is NOT applied
We do not recommend modifying the source file under this directory <Tomcat_home>\webapps
Instead, please create a new folder under <eMuseum_home>\skins. The folder name will become the skin name
Download the attached .zip file below
unzip the content to <eMuseum_home>\skins folder,
rename custom_skin to a preferred skin name
skip to step 9
4. Under <eMuseum_home>\skins\[skinName], create folder META-INF and subfolders assets\css
The result should look like this <eMuseum_home>\skins\[skinName]\META-INF\assets\css
5. Under META-INF\assets\css, create a new file called custom.scssLeave the .scss file empty, eMuseum just needs it to exist
Under <eMuseum_home>\skins\[skinName]\META-INF \assets (folders you just created), create another subfolders js
The result should look like this <eMuseum_home>\skins\[skinName]\META-INF\assets\js
Under META-INF\assets\css, create a new file called custom.js
Copy and paste the empty function below to custom.js
define([
"jquery"
], function($) {
});Navigate to <eMuseum_home>\skins\[skinName], create this folder path com\gallerysystems\emuseum\core\components
The result should look like this <eMuseum_home>\skins\[skinName]\com\gallerysystems\emuseum\core\components
copy Layout.tml from <Tomcat_home>\webapps\[root]\WEB-INF\classes\com\gallerysystems\emuseum\core\components
note that if eMuseum is not the root directory, you must replace the root folder above with the actual eMuseum folder.
paste Layout.tml to <eMuseum_home>\skins\[skinName]\com\gallerysystems\emuseum\core\components
Open Layout.tml file
Find <t:statisticstrackingcode />
Copy and paste it to other sections of the file as needed
Save
If your eMuseum is in Production mode, restart Apache Tomcat for the change to take effect.
There are three license tiers: Standard, Pro and Developer. This page shows which features are included in each tier.
Modules
Objects
Modules
People
Modules
Exhibitions
Modules
Sites
Modules
Bibliography
Modules
Media
Modules
Events
Modules
Loans
Pages
Start
Pages
Collections
Pages
Favorites
Pages
Help
Pages
About
Pages
Rights & Reproduction
Pages
Groups
Pages
Vocabularies
Search
Keyword
Search
Advanced
Search
Sorting
Search
Filtering
Search
Autocomplete
Views
Details View
Views
Images Grid
View
List View
Views
Table View
Data Services
External Vocabularies
Data Services
eMuseum API
Data Services
OAI-PMH
Date Services
IIIF
Media Settings
Image Size Management
Media Settings
Watermarking
Media Settings
Image Zooming
Media Settings
Custom Image Sizes
Media Settings
Downloading
Misc
Unlimited Users
Misc
Quick Appearance Manager
Misc
Field Configuration Manager
Misc
Themeable
Misc
Privacy Settings
Misc
Infinite Results Scrolling
Misc
Prism Data and Media Transfer
Misc
Discover More
Misc
Reports
Misc
Multiple Data Sources
Summary of the eMuseum system requirements and prerequisite applications.
4 GB RAM is required per application; 6 GB is recommended. Tomcat and the database system (RDBMS) are considered applications in this case. If Tomcat and the database run on the same server, the minimum RAM requirement is 8 GB.
The following hard drive space must be available next to the applications.
eMuseum application: 250 MB
Solr: 500 MB
Media: If media is hosted on the eMuseum webserver (the default configuration), additional storage space depends on the amount of media published.
eMuseum is a Java-based application that requires a Java Runtime Environment (JRE). The following table shows which Java versions are supported by each version of eMuseum:
eMuseum 6.5
eMuseum 6.4
eMuseum 6.3
eMuseum 6.2
eMuseum 6.1
eMuseum 6.0
eMuseum 5.2
eMuseum 5.1
eMuseum 5.0
eMuseum runs on the Tomcat web application server. The following table shows which Tomcat versions are supported by each version of eMuseum
eMuseum 6.5
eMuseum 6.4
eMuseum 6.3
eMuseum 6.2
eMuseum 6.1
eMuseum 6.0
eMuseum 5.2
eMuseum 5.1
eMuseum 5.0
eMuseum uses Solr, an external search engine. The following table shows which Solr versions are required and supported by each version of eMuseum:
eMuseum 6.5
eMuseum 6.4
eMuseum 6.3
eMuseum 6.2
eMuseum 6.1
eMuseum 6.0
eMuseum 5.2
eMuseum 5.1
eMuseum 5.0
One of the following database management systems (RDBMS) is required.
eMuseum 6.5
eMuseum 6.4
eMuseum 6.3
eMuseum 6.2
eMuseum 6.1
eMuseum 6.0
eMuseum 5.2
eMuseum 5.1
eMuseum 5.0
eMuseum 6
eMuseum 5
eMuseum 6.5
eMuseum 6.4
eMuseum 6.3
eMuseum 6.2
eMuseum 6.1
eMuseum 6.0
eMuseum 5
eMuseum 5 supports TMS versions back to 2010. For eMuseum 6, please see Prism compatibility.
eMuseum 5.2
eMuseum 5.1
eMuseum 5.0
Since eMuseum 6, an instance of Prism is required to import data, vocabulary, and media from TMS. Prism is not required to be installed on the same server as eMuseum; one Prism instance can transfer data to multiple eMuseum instances.
eMuseum 6.5
eMuseum 6.4
eMuseum 6.3
eMuseum 6.2
eMuseum 6.1
eMuseum 6.0
An overview of eMuseum versions.
6.5.7 July 11,
6.5.6 May 29,
6.5.5 May 8 2025,
6.5.4 February 26 2025,
6.5.3 January 29 2025,
6.5.2 December 2 2024,
6.5.1 October 14 2024,
6.5 September 27 2024,
6.4.21 May 29,
6.4.20 May 8 2025,
6.4.19 February 26 2025,
6.4.18 January 29 2025,
6.4.17 October 14 2024,
6.4.16 August 1 2024, Changelog
6.4.15 April 22 2024, Changelog
6.4.14 April 19 2024, Changelog, Release Notes
6.4.13 Februar 23 2024, Changelog, Release Notes
6.4.12 Oktober 13 2023, Changelog
6.4.11 Oktober 03 2023, Changelog, Release Notes
6.4.10 Juni 30 2023, Changelog, Release Notes
6.4.9 April 13 2023, Changelog, Release Notes
6.4.8 März 06 2023, Changelog
6.4.7 Januar 04 2023, Changelog, Release Notes
6.4.6 November 08 2022, Changelog, Release Notes
6.4.5 Oktober 14 2022, Changelog, Release Notes
6.4.4 August 15 2022, Changelog
6.4.3 August 11 2022, Changelog, Release Notes
6.4.2 Juni 28 2022, Changelog, Release Notes
6.4.1 Juni 16 2022, Changelog
6.4 Mai 31 2022, Changelog, Release Notes
6.322 May 8 2025
6.3.21 January 29 2025
6.3.20 October 14 2024
6.3.19 August 1 2024
6.3.18 Apr 19 2024
6.3.17 Feb 23 2024
6.3.16 Oct 13 2023
6.3.15 Oct 3 2023
6.3.14 Jun 30 2023
6.3.13 Apr 13 2023
6.3.12 Mar 6 2023
6.3.11 Jan 4 2023
6.3.10 Nov 8 2022
6.3.9 Oct 14 2022
6.3.8 Aug 11 2022
6.3.7 Jun 28 2022
6.3.6 May 17 2022
6.3.5 Mar 21 2022
6.3.4 Feb 11 2022
6.3.3 Nov 30 2021
6.3.2 May 21 2021
6.3.1 May 14 2021
6.3 Apr 16 2021
6.2.19 Sep 9 2024
6.2.18 Apr 19 2024
6.2.17 Feb 23 2024
6.2.16 Oct 3 2023
6.2.15 Jun 30 2023
6.2.14 Apr 13 2023
6.2.13 Mar 6 2023
6.2.12 Jan 4 2023
6.2.11 Nov 8 2022
6.2.10 Oct 14 2022
6.2.9 Aug 11 2022
6.2.8 Jun 28 2022
6.2.7 May 17 2022
6.2.6 Mar 21 2022
6.2.5 Feb 11 2022
6.2.4 Nov 30 2021
6.2.3 May 21 2021
6.2.2 Apr 15 2021
6.2.1 Nov 4 2020
6.2 Aug 28 2020
6.1.21 Sep 9 2024
6.1.20 Apr 19 2024
6.1.19 Feb 23 2024
6.1.18 Oct 3 2023
6.1.17 Jun 30 2023
6.1.16 Apr 13 2023
6.1.15 Mar 6 2023
6.1.14 Jan 4 2023
6.1.13 Nov 8 2022
6.1.12 Oct 14 2022
6.1.11 Aug 11 2022
6.1.10 Jun 28 2022
6.1.9 May 17 2022
6.1.8 Mar 21 2022
6.1.7 Feb 11 2022
6.1.6 Nov 30 2021
6.1.5 May 21 2021
6.1.4 Apr 15 2021
6.1.3 Nov 4 2020
6.1.2 Aug 20 2020
6.1.1 Jun 16 2020
6.1 Apr 9 2020
6.0.29 Sep 9 2024
6.0.28 Apr 19 2024
6.0.27 Feb 23 2024
6.0.26 Oct 3 2023
6.0.25 Jun 30 2023
6.0.24 Apr 13 2023
6.0.23 Mar 6 2023
6.0.22 Jan 4 2023
6.0.21 Nov 8 2022
6.0.20 Oct 14 2022
6.0.19 Aug 11 2022
6.0.18 Jun 28 2022
6.0.17 May 17 2022
6.0.16 Mar 21 2022
6.0.15 Feb 11 2022
6.0.14 Nov 30 2021
6.0.13 May 21 2021
6.0.12 Apr 15 2021
6.0.11 Nov 4 2020
6.0.10 Aug 20 2020
6.0.9 Jun 16 2020
6.0.8 Mar 5 2020
6.0.7 Jan 29 2020
6.0.6 Dec 11 2019
6.0.5 Nov 8 2019
6.0.4 Oct 28 2019
6.0.3 Oct 17 2019
6.0.2 Oct 7 2019
6.0.1 Sep 27 2019
6.0 Sep 13 2019
This guide explains how to run eMuesum over HTTPS. For in-depth details and Tomcat settings, see the Tomcat 9.0 How-To.
The process consists of these steps:
Choose the protocol to be used by Tomcat
Create a keypair which consists of a private key and a certificate, and create a Certificate Signing Request (CSR) that includes the certificate
Send the CSR to a Certificate Authority (CA) to obtain a signed certificate
Create a keystore that includes both the private key and the signed certificate
Configure Tomcat to enable HTTPS and use the Keystore
Tomcat supports two protocols for handling HTTPS, the APR/native and the NIO, which are described below. Each protocol uses a different keystore format. Though it is possible to convert from one format to the other, we recommend creating the keystore, certificate, and key files in the format specific to the protocol from the beginning.
The APR/native protocol requires the installation of OpenSSL and the Tomcat Native library. If you choose this option, use OpenSSL to create the certificate in the PKCS #12 format.
The NIO protocol is implemented in pure Java and uses the JKS keystore type. If you choose this option, you can use the Keystore Explorer to create the certificate and the keystore.
The first step is to create a keypair that consists of a private key and certificate, which will be wrapped in a Certificate Signing Request (CSR).
Install OpenSSL (or download the OpenSSL binaries)
For Windows, unpack the downloaded file to C:\eMuseum\ and define environment variables by opening a command prompt and running these two commands:
SET PATH=%PATH%;C:\eMuseum\openssl-0.9.8h-1-bin\bin
SET OPENSSL_CONF=C:\eMuseum\openssl-0.9.8h-1-bin\share\openssl.cnfCreate a private key by running the following command in a command prompt:
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out collections-mymuseum-org.key(replace collections-mymuseum-org with the domain of your eMuseum instance)
Create a Certificate Signing Request (which includes the certificate) by running the following command in a command prompt:
openssl req -new -key collections-mymuseum-org-key.pem -out collections-mymuseum-org.csr(replace collections-mymuseum-org with the same value as in the previous step)
When prompted, provide the following information:
Enter Country Name (e. g. US)
Enter State or Province Name (e. g., New York)
Enter Locality Name (e. g., New York)
Enter the Organization Name (e. g., Gallery Systems)
Enter Organizational Unit Name (e. g. Gallery Systems)
Enter Common Name (e. g. collections.mymuseum.org) The Common Name (CN) must be the fully qualified domain name of the site—e. g. collection.mymuseum.org
Enter "Email Address" (e. g. [email protected])
Press enter when prompted for "challenge password". Not required.
Press enter when prompted for "company name". Not required.
Download and install the KeyStore Explorer application
Create a keypair that:
Go to the Tools menu and select Generate Key Pair
In the Generate Key Pair prompt, select RSA and make sure the Key Size is set to 2,048
Click OK
On the Generate Key Pair Certificate screen:
Choose Version 3 as the version
Select SHA-256 with RSA as the signature algorithm
Select 1 to 5 years for the validity period The validity period determines how long the certificate will be valid for
Click the @ icon
Enter the requested information The Common Name (CN) must be the fully qualified domain name of the site—e. g. collection.mymuseum.org
Click OK
Click OK
Enter a password for the key store
Click OK
Click OK
Click the save icon or go to the File menu and select Save
Browse to the root of the Tomcat installation directory
Enter a file name value such as collection.mymuseum.org.jks Change this value to match your eMuseum domain plus .jks
Click Save
Create a Certificate Signing Request (CSR):
Right-click on the private key and select Generate CSR
Choose PKCS #10
Select SHA-256 with RSA
Browse to select a location to save the .csr file to
Enter a file name value such as collection.mymuseum.org.csr
Click OK
Use the CSR file generated in the steps above to obtain a signed certificate from your preferred Certificate Authority (CA). You will get back a signed certificate and, optionally, an intermediate and a root certificate that are specific to the CA.
The PKCS #12 format is appropriate for using the APR/native protocol. If the private key and the certificate have been created using OpenSSL, they are already in the PKCS #12 format. Make sure that the intermediate certificate is included in the .crt file together with the signed certificate.
The JKS format is the right format for using the NIO protocol. If the private key and the certificate have been created with the Keystore Explorer, import the signed certificate back into the keystore:
Right-click on the private key and select Import CA Reply → From File
Browse to the signed certificate from the CA
Select the certificate and click OK
Go to the Tools menu and select Import Trusted Certificate
Browse to the intermediate certificate file and select it If the intermediate file contains more than one certificate, back up the file and delete all but the first.
Click OK to import the certificate
Click the save icon to save the changes to the key store. If prompted, re-enter the key store password.
Depending on the protocol, the configuration is slightly different. In both cases, copy the (Keystore) file(s) to the <TOMCAT_HOME>/conf/ folder.
Open <TOMCAT_HOME>/conf/server.xml in a text editor with administrator permissions
For Tomcat 8.5 and above add the following block under the <Service> element:
<Connector port="443" protocol="org.apache.coyote.http11.Http11AprProtocol" maxThreads="150" SSLEnabled="true">
<UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol" />
<SSLHostConfig>
<Certificate
certificateKeyFile="conf/collections-mymuseum-org.key"
certificateFile="conf/collections-mymuseum-org.crt"
certificateChainFile="conf/cachain.crt"
type="RSA"
/>
</SSLHostConfig>
</Connector>CopyXML
For Tomcat 8 and below add the following block under the <Server> element:i
<Connector
protocol="org.apache.coyote.http11.Http11AprProtocol"
port="443"
maxThreads="200"
scheme="https"
secure="true"
SSLEnabled="true"
SSLCertificateFile="conf/collections-mymuseum-org.crt"
SSLCertificateKeyFile="conf/collections-mymuseum-org.key"
SSLVerifyClient="optional"
SSLProtocol="TLSv1.1+TLSv1.2"
/>CopyXML
Save the changes to server.xml
Restart Tomcat
Open <TOMCAT_HOME>/conf/server.xml in a text editor with administrator permissions
Add the following block under the<Service>element:
<Connector
port="443"
protocol="org.apache.coyote.http11.Http11NioProtocol"
maxThreads="150"
SSLEnabled="true"
scheme="https"
secure="true"
clientAuth="false"
sslProtocol="TLS"
keystoreFile="C:\Tomcat\collection.mymuseum.org.jks"
keystoreType="JKS"
keystorePass="yourkeystorepassword"
/>CopyXML
Make sure to change the keystoreFile and the keystorePass attributes according to your settings.
Save the changes to server.xml
Restart Tomcat
This step is only necessary if using the API under HTTPS. In this case you have to make sure that Java can knows about your certificate and can resolve requests to your domain. Add your certificate to Java’s keystore:
keytool -keystore cacerts -import -alias collection.mymuseum.org -file collection-mymuseum-org.crtChange the alias “collection.mymuseum.org” and the filename “collection-mymuseum-org.crt” according to your files.
JKS: Java KeyStore