Installation

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.

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

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

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

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).

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

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.

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}
chown tomcat:tomcat /var/opt/tomcat
chmod 755 /var/opt/tomcat

Next, adjust the port of the HTTP connector in /var/opt/tomcat/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

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.

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.

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';

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.

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.

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/.

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).

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)

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

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

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.

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.