Add Apache TLS/SSL reverse proxy to CollectionSpace

Using the Apache HTTP Server in front of CollectionSpace's Tomcat Server instance has many advantages, including port hiding and supporting TLS/SSL connections.

Port Hiding

Port hiding is useful for creating a URL for CollectionSpace that does not have the :8180 port number. For example, a CollectionSpace tenant can be available to users at cspace.mymuseum.org, instead of the harder to remember cspace.mymuseum.org:8180/cspace/tenantname.

TLS/SSL

TLS/SSL are cryptographic protocols that provide communications security over the Internet. Configuring CollectionSpace to communicate this way with users is critical to protecting collection data and user information in a production instance. If you have trouble getting this to work, please reach out to the CollectionSpace community for help. A great place to start is by sending an email to the CollectionSpace "Talk" email list at talk@collectionspace.org.

Instructions for installing on Ubuntu 20.04 LTS

Installing Apache as a reverse proxy to Tomcat

Install the Apache HTTP Server:

sudo apt install apache2

Create a virtual host for your CollectionSpace instance.

Enable the proxy and proxy_http modules.

sudo a2enmod proxy
sudo a2enmod proxy_http

Add the following lines to your virtual host configuration file:

ProxyRequests Off
ProxyPass /cspace/ http://localhost:8180/cspace/
ProxyPassReverse /cspace/ http://localhost:8180/cspace/
ProxyPass /cspace-ui/ http://localhost:8180/cspace-ui/
ProxyPassReverse /cspace-ui/ http://localhost:8180/cspace-ui/
ProxyPass /cspace-services/ http://localhost:8180/cspace-services/
ProxyPassReverse /cspace-services/ http://localhost:8180/cspace-services/

Restart apache.

sudo systemctl restart apache2

CollectionSpace should now be accessible on your virtual host, without a port number. For example, if your virtual host's domain is cspace.mymuseum.org, the core tenant should be available at http://cspace.mymuseum.org/cspace/core.

Enabling SSL/TLS

To enable TLS, you must have a certificate for your domain. If you don't have a certificate, you can obtain one from Let's Encrypt.

Enable the ssl module.

sudo a2enmod ssl

Edit your virtual host configuration file. Change the port number of the configuration to 443 instead of 80, and add the SSL configuration settings shown below.

<VirtualHost *:443>
    # ... other configuration

    SSLEngine On

	# Replace /path/to/file with the location of your crt file
    SSLCertificateFile /path/to/file

    # Replace /path/to/file with the location of your key file 
    SSLCertificateKeyFile /path/to/file  
</VirtualHost>

Restart apache.

sudo systemctl restart apache2

CollectionSpace should now be accessible using an https URL, like https://cspace.mymuseum.org/cspace/core.

In your virtual host configuration file, add configuration to redirect http URLs to https.

<VirtualHost *:80>
	# Replace cspace.mymuseum.org with your hostname
    ServerName cspace.mymuseum.org 

    # Replace cspace.mymuseum.org with your hostname
    Redirect permanent / https://cspace.mymuseum.org/
</VirtualHost>

<VirtualHost *:443>
    # ... SSL/TLS site configuration
</VirtualHost>

Restart apache.

sudo systemctl restart apache2

Attempting to access CollectionSpace using an http URL, like http://cspace.mymuseum.org/cspace/core, should now force the browser to access CollectionSpace using https, e.g. at https://cspace.mymuseum.org/cspace/core.