Versions Compared

Old Version 1

changes.mady.by.user Anonymous

Saved on

compared with

New Version Current

changes.mady.by.user Ray Lee

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Using the Apache HTTP Server in font front of CollectionSpace's Tomcat Server instance has many advantages.  The two most important for us are , including port hiding and supporting TLS/SSL connections. Learn more about the Apache HTTP Server here: https://en.wikipedia.org/wiki/Apache_HTTP_Server

Port Hiding

This Port hiding is useful for creating a landing page URL for CollectionSpace so one can ignore that does not have the :8180 port number as well as have Apache redirect you to the full site location if the user only knows the domain (and subdomain.) This is useful as remembering demo.collectionspace.org is much nicer than remembering demo.collectionspace.org/collectionspace/ui/core/html/index.html.. 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 and a computer network in general.  Configuring . Configuring CollectionSpace to communicate this way with its users is critical to protecting collection data and user information in a production instance.  If If you have trouble get getting this to work, please reach out to the CollectionSpace community for help.  A 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 is installed:

Code Block
sudo apt-get install apache2

Create a virtual host for your CollectionSpace instance.

Enable the proxy and rewrite modules. These are necessary for what we wish to accomplish proxy_http modules.

Code Block
a2enmodsudo rewrite
a2enmod proxy
sudo a2enmod proxy_http

a2enmod mod_ssl

Then restart apache.

Code Block
/etc/init.d/apache2 restart (sudo service apache restart)

Next, make sure proxying is turned on, which is usually turned off by default in Ubuntu. Edit /etc/apache2/mods-enabled/proxy.conf

Code Block
<IfModule mod_proxy.c>

# If you want to use apache2 as a forward proxy, uncomment the
# 'ProxyRequests On' line and the <Proxy *> block below.
# WARNING: Be careful to restrict access inside the <Proxy *> block.
# Open proxy servers are dangerous both to your network and to the
# Internet at large.
#
# If you only want to use apache2 as a reverse proxy/gateway in
# front of some web application server, you DON'T need
# 'ProxyRequests On'.

#ProxyRequests On
ProxyRequests Off
<Proxy *>
        AddDefaultCharset off
        Order deny,allow
        Deny from all
        #Allow from .example.com
</Proxy>

# Enable/disable the handling of HTTP/1.1 "Via:" headers.
# ("Full" adds the server version; "Block" removes all outgoing Via: headers)
# Set to one of: Off | On | Full | Block
#ProxyVia Off
ProxyVia On
</IfModule>

Next, create a new virtual host for your CollectionSpace instance.
Here is a sample VH directive for the server at mmidev.collectionspace.org (96.126.108.110) saved as /etc/apache2/sites-enabled/cspace

Code Block
<VirtualHost 96.126.108.110:80>
        <Proxy *>
                Order deny,allow
                Allow from all
        </Proxy>

        ServerAdmin webmaster@localhost

        RewriteEngine on
        RewriteRule     /collectionspace/(.*)   http://mmidev.collectionspace.org:8180/collectionspace/$1 [P]

        # set server name
        ProxyPreserveHost On
        ServerName localhost

        DocumentRoot /var/www/html
        <Directory />
                Options FollowSymLinks
                AllowOverride all
        </Directory>
        <Directory /var/www/html>
                Options Indexes FollowSymLinks MultiViews
                AllowOverride all
                Order allow,deny
                allow from all
        </Directory>

        ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/
        <Directory "/usr/lib/cgi-bin">
                AllowOverride None
                Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
                Order allow,deny
                Allow from all
        </Directory>

        ErrorLog /var/log/apache2/error.log

        # Possible values include: debug, info, notice, warn, error, crit,
        # alert, emerg.
        LogLevel warn

        CustomLog /var/log/apache2/access.log combined

</VirtualHost>

The VH here will allow Apache to know what to serve when it gets a request for mmidev.collectionspace.org on port 80 (the default http port). Any requests for mmidev.collectionspace/* (port 80) will be sent to the tomcat server listening on port 8180. Apache acts as a proxy server in this case and rewrites all incoming and outgoing URLs so the URL can be 'prettified' by having the port number (8180) stripped out.

Next, we notify apache of the VH we want to enable. In this case, cspace

Code Block
a2ensite cspace

This will also create a symbolic link in apache's sites-enabled directory.

Reload the apache configuration

Code Block
/etc/init.d/apache2 reload

Finally, we want to create a landing page that will redirect the user to the full app location.
Save this template to your canonical default apache webdirectory: /var/www/index.html

Code Block
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
        <head>
                <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
                <title>MMI CollectionSpace</title>

                <style>
                        body {padding:0; font:1.1em/1.5 Verdana, arial, sans-serif; color: #000; margin:2em 0; text-align: center;}
                        img {padding: 0; margin: 2em 0;}
                        p {margin:1em 0 0 0; padding: 0;}
                        a {text-decoration:none; color:#88AFD8;}

                </style>
                <META HTTP-EQUIV="CACHE-CONTROL" CONTENT="NO-CACHE">
                <META
                        HTTP-EQUIV="Refresh"
                        CONTENT="0; URL=http://mmidev.collectionspace.org/collectionspace/ui/core/html/index.html">

        </head>

        <body>
                <p>If you are not automatically forwarded to the MMI CollectionSpace page please <a href="http://mmidev.collectionspace.org/collectionspace/ui/core/html/index.html">click here</a>.</p>
        </body>

</html>

...

Add the following lines to your virtual host configuration file:
 Code Block
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.
 Code Block
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.
 Code Block
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.
 Code Block
<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.
 Code Block
sudo systemctl restart apache2

CollectionSpace should now be accessible using an https URL, like https://cspace.mymuseum.org/cspace/core.
Add configuration to redirect http URLs to https.
 Code Block
<VirtualHost *:80>
	# Replace mymuseum.org with your domain
    ServerName mymuseum.org 

    # Replace mymuseum.org with your domain
    Redirect permanent / https://mymuseum.org/
</VirtualHost>
Restart apache.
 Code Block
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.