# Installation

## Overview

By default, the following ports will be used:

* Tomcat
  * HTTP: 80
  * HTTPS: 443
  * Shutdown: 8005
* Solr: 8983

{% tabs %}
{% tab title="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.*
{% endtab %}

{% tab title="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
  {% endtab %}
  {% endtabs %}

## eMuseum Installation Package

Acquire an eMuseum installation package as the first step of the installation. Default packages can be downloaded from the [Community Portal](https://community.gallerysystems.com/).

{% tabs %}
{% tab title="Windows" %}
Create a base folder, e. g. `C:\eMuseum`, and extract the installation package into it. Rename the resulting installation folder to `home`.
{% endtab %}

{% tab title="Linux" %}
Extract the installation package and move it to `/var/opt/emuseum`:

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

{% endtab %}
{% endtabs %}

## 3rd-party Requirements

Next, install all required 3rd-party requirements.

### Install Java

Install Java in the required version.

{% tabs %}
{% tab title="Windows" %}
Download Java from [adoptium.net](https://adoptium.net/de/temurin/releases/?os=windows\&arch=x64\&package=jdk\&version=17). 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).
{% endtab %}

{% tab title="Linux" %}
Install the OpenJDK package in the required version via the package management.

On Ubuntu, this can be done with *apt*:

```bash
apt install openjdk-17-jdk
```

{% endtab %}
{% endtabs %}

### Install Tomcat

Install the required version of Tomcat.

{% tabs %}
{% tab title="Windows" %}
Download Tomcat from [tomcat.apache.org](https://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":

```xml
    <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.
{% endtab %}

{% tab title="Linux" %}
Download and import Tomcat PGP keys:

```bash
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):

```bash
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:

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

Create a Tomcat group and user:

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

Adjust the file permissions:

```bash
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:

```bash
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":

```xml
    <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`:

```systemd
[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:

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

{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="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):

```batch
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`:

```batch
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:

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

Start the service.
{% endtab %}

{% tab title="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>.
{% endtab %}
{% endtabs %}

## eMuseum Application

### Create Database

Create a new eMuseum database including user as follows.

{% tabs %}
{% tab title="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!**):

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

{% endtab %}

{% tab title="MariaDB" %}
Either use a management client of your choice or run the following SQL script (**adjust the login password!**):

```sql
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.
{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="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`.
{% endtab %}

{% tab title="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/`.
{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="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).
{% endtab %}

{% tab title="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)
{% endtab %}
{% endtabs %}

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.

{% tabs %}
{% tab title="Windows" %}
Copy the XML file from above to Tomcat’s configuration folder: `C:\eMuseum\Tomcat9\conf\Catalina\localhost\ROOT.xml`
{% endtab %}

{% tab title="Linux" %}
Copy the XML file from above to Tomcat’s configuration folder: `/var/opt/tomcat/conf/Catalina/localhost/ROOT.xml`
{% endtab %}
{% endtabs %}

Deploy the war file.

{% tabs %}
{% tab title="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`.
{% endtab %}

{% tab title="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`.
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
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).
{% endhint %}

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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.gallerysystems.com/emuseum/6.4/installation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.