Installation

This page explains the installation procedure for eMuseum.

Overview

By default, the following ports will be used:

• Tomcat

  • HTTP: 80

  • HTTPS: 443

  • Shutdown: 8005

• Solr: 8983

Windows

On Windows, we will install everything into a base folder (e. g. C:\eMuseum):

• C:\eMuseum

  • \home

  • \jdk17

  • \solr9

  • \Tomcat9

It is recommended to use the major version in the folder name but leave out any other version part. That will ensure that references do not need to be adjusted on every update.

Linux

On Linux, Java will be installed via the package management, Tomcat will be installed manually at /opt/tomcat9 with a working directory at /var/opt/tomcat, Solr will be installed via the official installation script with a symlink at /opt/solr and the data located at /var/solr, and eMuseum will be installed to /var/opt/emuseum:

• /opt/tomcat9

• /opt/solr → /opt/solr-x.y.z

• /var/solr

• /var/opt/tomcat

• /var/opt/emuseum

eMuseum Installation Package

Acquire an eMuseum installation package as the first step of the installation. Default packages can be downloaded from the Community Portal.

Windows

Create a base folder, e. g. C:\eMuseum, and extract the installation package into it. Rename the resulting installation folder to home.

Linux

Extract the installation package and move it to /var/opt/emuseum:

unzip eMuseum-6.4.12.zip
mv eMuseum-6.4.12 /var/opt/emuseum

3rd-party Requirements

Next, install all required 3rd-party requirements.

Install Java

Install Java in the required version.

Windows

Download Java from adoptium.net. Make sure to pick the correct version and architecture. Then, install it to C:\eMuseum\jdk17 (adjust the folder name to match the Java version).

Linux

Install the OpenJDK package in the required version via the package management.

On Ubuntu, this can be done with apt:

apt install openjdk-17-jdk

Install Tomcat

Install the required version of Tomcat.

Windows

Download Tomcat from tomcat.apache.org. For an easy installation that includes a service, pick the 32-bit/64-bit Windows Service Installer.

Execute the installer. Un-check all additional options like the documentation and the manager, but select all options under the root item (Tomcat Native and service). The first path the installer asks for is the Java directory, not the Tomcat installation folder. Select C:\eMuseum\jdk17. The second path will be the Tomcat installation folder. Select C:\eMuseum\Tomcat9 (adjust the folder name to match the Tomcat version). Use only “eMuseum” as the name; the installer will add “Apache Tomcat” in front of it. Starting the service to let Tomcat create some default folders is recommended.

After the installation, stop the Tomcat service and increase the memory by executing the Tomcat configuration utility at C:\eMuseum\Tomcat9\bin\eMuseumw.exe. Under the tab “Java,” set the start memory to “512” and the maximum memory to a minimum of “4096”.

Next, adjust the port of the HTTP connector in C:\eMuseum\Tomcat9\conf\server.xml from “8080” to “80” and increase the maxParameterCount to "3000":

    <Connector port="80" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443"
               maxParameterCount="3000">

To set up HTTPS, uncomment one of the example connectors, change its port to “443” and adjust the TLS settings.

Linux

Download and import Tomcat PGP keys:

cd ~/
wget https://downloads.apache.org/tomcat/tomcat-9/KEYS
gpg --import KEYS
rm KEYS

Download, verify and extract Tomcat 9 tar ball to /opt/ (adjust the version to use the latest):

wget https://dlcdn.apache.org/tomcat/tomcat-9/v9.0.84/bin/apache-tomcat-9.0.84.tar.gz
wget https://downloads.apache.org/tomcat/tomcat-9/v9.0.84/bin/apache-tomcat-9.0.84.tar.gz.asc
gpg --verify apache-tomcat-9.0.84.tar.gz.asc
tar -xzf apache-tomcat-9.0.84.tar.gz
mv apache-tomcat-9.0.84 /opt/
rm apache-tomcat-9.0.84.tar.gz
rm apache-tomcat-9.0.84.tar.gz.asc

Create a symlink tomcat9 → apache-tomcat-9.0.84:

ln -s /opt/apache-tomcat-9.0.84 /opt/tomcat9

Create a Tomcat group and user:

groupadd --system tomcat
useradd --system -s /usr/sbin/nologin -g tomcat tomcat

Adjust the file permissions:

chown -R tomcat:tomcat /opt/apache-tomcat-9.0.84/
find /opt/tomcat9/ -type d -exec chmod 755 {} \;
find /opt/tomcat9/ -type f -exec chmod 644 {} \;
chmod +x /opt/tomcat9/bin/*.sh

Create a working directory for Tomcat:

mkdir /var/opt/tomcat
mkdir /var/opt/tomcat/webapps
cp -r /opt/tomcat9/{conf,logs,temp,work} /var/opt/tomcat/
chown tomcat:tomcat /var/opt/tomcat
chmod 755 /var/opt/tomcat

Next, adjust the port of the HTTP connector in /var/opt/tomcat/conf/server.xml from “8080” to “80” and increase the maxParameterCount to "3000":

    <Connector port="80" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443"
               maxParameterCount="3000">

To set up HTTPS, uncomment one of the example connectors, change its port to “443” and adjust the TLS settings.

Finally, create a Systemd service unit at /etc/systemd/system/tomcat9.service:

[Unit]
Description=Tomcat 9 servlet container
After=network.target

[Service]
Type=forking
User=tomcat
Group=tomcat
Environment="JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64/"
Environment="JAVA_OPTS=-Djava.security.egd=file:///dev/urandom -Djava.awt.headless=true"
Environment="CATALINA_BASE=/var/opt/tomcat"
Environment="CATALINA_HOME=/opt/tomcat9"
Environment="CATALINA_OPTS=-Xms1024M -Xmx4096M -server -XX:+UseParallelGC"
EnvironmentFile=-/etc/tomcat/%i.conf
ExecStart=/opt/tomcat9/bin/startup.sh
ExecStop=/opt/tomcat9/bin/shutdown.sh

[Install]
WantedBy=multi-user.target

Enable and start the service:

systemctl daemon-reload
systemctl enable --now tomcat9.service

Install Database Management Engine

If you want to use a standalone database instance, install one of the supported Database Management Systems. Otherwise, use an existing database server.

Install Solr

If you want to use a standalone instance of Solr, please follow the following steps. If you plan to use a shared instance, skip the next steps.

Windows

Download the Solr binary release from https://solr.apache.org/downloads.html and extract the package to C:\eMuseum\solr9 (adjust the folder name to match the Solr version).

On the download page, you will only find tar.gz files. However, on a recent version of Windows, the following tar can be used via the command line to extract the package (adjust the filename to match the Solr version):

tar zxf solr-9.5.0.tgz

Configure the JVM that Solr uses by setting the following line in C:\eMuseum\solr9\bin\solr.in.cmd:

set SOLR_JAVA_HOME=C:\eMuseum\jdk17

To set up Solr as a service, download the latest version of the Windows Service Wrapper (WinSW) from https://github.com/winsw/winsw/releases (pick the Windows 64-bit executable). Move the file to C:\eMuseum\home\utils\WinSW and rename it to eMuseumSolr.exe. Next, rename the XML file eMuseumSolr.example.xml in that folder to eMuseumSolr.xml (both the XML and the exe files have to have the same name). Finally, open a command prompt with administrator permissions, navigate to the folder, and run the following command:

cd C:\eMuseum\home\utils\WinSW
eMuseumSolr.exe install

Start the service.

Linux

Download Solr binary release from https://solr.apache.org/downloads.html and follow the https://solr.apache.org/guide/solr/latest/deployment-guide/taking-solr-to-production.html.

eMuseum Application

Create Database

Create a new eMuseum database including user as follows.

SQL Server

If you want to use SQL Server Management Studio, open it, connect to the database server, and do the following steps:

• Create a new login with the name “emuseum” and a strong password. Disable all password policies.

• Create a new database named “emuseum” with the owner set to “emuseum” and the Recovery Model set to “simple”

Alternatively, run the following SQL script (adjust the login password!):

CREATE DATABASE emuseum;
ALTER DATABASE [emuseum] SET RECOVERY SIMPLE;

CREATE LOGIN emuseum WITH PASSWORD = N'emuseum', CHECK_POLICY = OFF, CHECK_EXPIRATION = OFF;

USE emuseum;
CREATE USER emuseum FROM LOGIN emuseum;
EXEC sp_addrolemember 'db_owner', 'emuseum';

MariaDB

Either use a management client of your choice or run the following SQL script (adjust the login password!):

CREATE DATABASE emuseum CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'emuseum'@'localhost' IDENTIFIED BY PASSWORD 'emuseum';
GRANT ALL PRIVILEGES ON emuseum.* TO 'emuseum'@'localhost' WITH GRANT OPTION;
FLUSH PRIVILEGES;

If the database server is running on a different host, adjust the host value. Use “%” to allow the user to connect from any host.

Create Database Schema

Since version 6.4, eMuseum creates the database schema automatically on start-up.

Create Solr cores

Copy eMuseum’s core configuration to Solr’s data folder.

Windows

Copy eMuseum’s core configuration from C:\eMuseum\home\solr\solr9 to Solr’s data folder.

If Solr has been installed for eMuseum only, the data folder will be C:\eMuseum\solr9\server\solr.

Linux

Copy eMuseum’s core configuration from /var/opt/emuseum/solr/solr9/ to Solr’s data folder.

If Solr has been installed for eMuseum only, the data folder will be /var/solr/data/.

If Solr is not used exclusively for eMuseum, the data folder depends on the Solr setup. Rename the core folders to emuseum_records and emuseum_vocabularies (if you use a shared Solr instance for several eMuseum applications, use a prefix like the client name). Additionally, change the core names inside core.properties files within the core folders to match the folder names.

Restart Solr for the changes to take effect. Optionally, you can log in to the Solr admin dashboard at http://localhost:8983/ and check if the two cores are listed.

Deploy Webapp

Windows

Create a context descriptor by copying an example context.xml file from C:\eMuseum\home\bin\context to C:\eMuseum\home\bin\ROOT.xml which matches the database management system (e. g. context.mssql.xml for SQL Server).

Linux

Create a context descriptor by copying an example context.xml file from /var/opt/emuseum/bin/context/ to /var/opt/emuseum/bin/ROOT.xml which matches the database management system (e. g. context.mssql.xml for SQL Server)

Adjust the following settings:

• emuseum.home The path to the eMuseum folder: C:\eMuseum\home (Windows) or /var/opt/emuseum (Linux)

• emuseum.jdbcurl The database connection URL

• emuseum.dbuser The database user name

• emuseum.dbpassword The database user password

• solr.serverUrl The base URL of the Solr server

• solr.corePrefix The prefix of the Solr cores (including any trailing character like _).

Copy the context descriptor to Tomcat.

Windows

Copy the XML file from above to Tomcat’s configuration folder: C:\eMuseum\Tomcat9\conf\Catalina\localhost\ROOT.xml

Linux

Copy the XML file from above to Tomcat’s configuration folder: /var/opt/tomcat/conf/Catalina/localhost/ROOT.xml

Deploy the war file.

Windows

To deploy the webapp on Window, copy the war file from C:\eMuseum\home\bin\emuseum-6.4.war (adjust the version number) to C:\eMuseum\Tomcat9\webapps\ROOT.war.

Linux

To deploy the webapp on Linux, copy the war file from /var/opt/emuseum/bin/emuseum-6.4.war (adjust the version number) to /var/opt/tomcat/webapps/ROOT.war.

For Tomcat to match the configuration with the application, it is crucial that the war file and the context description have the same name (except for the file extension).

Start the Tomcat service.

First Start

Open a web browser and navigate to http://localhost/admin. Login as superuser/superuser.

Change Superuser Password

Change the superuser password to a strong password.

Set License

Set a license under Configuration → Application → License.

Configure Application

Adjust the following application settings:

• Application name

• Hostname

• Use HTTPS (if enabled and a domain has been set up)