Fronting Studio with Apache Web Server

Introduction

Often people will want to have Studio accessed via a web server such as Apache. This allows users to not have to enter the specific port number and/or obscure URL provided by semaphore or to configure Apache integrated authentication. The following describes how to configure Apache 2.4 on a 64-bit CentOS or RHEL 7.x deployment.

By default CentOS 7.x or RHEL 7.x come with Apache 2.4 and a collection of modules including “mod_proxy”, “mod_proxy_ajp” and “mod_jk”. Those modules can be used interchangeably to front Semaphore Workbench with Apache. They are subtly different and you should refer to the Apache document to chose the most appropriate for your environment.

The “mod_proxy” way

Most deployments should use the simple “mod_proxy” approach. Assuming that the “mod_proxy” Apache module is installed and Studio is installed and already available at http://<your-server>:5080/ the following steps are needed:

1. Under the “/etc/httpd/conf.d” directory create a new “semaphore.conf” configuration file containing the following:

<Location /studio/>
  ProxyPass http://localhost:5080/ retry=1 acquire=3000 timeout=600 Keepalive=Off
  ProxyPassReverse /
</Location>

2. Restart Apache by issuing

systemctl restart httpd

The “mod_jk” way

Assuming that the “mod_jk” Apache module is installed and Studio is installed and already available at http://<your-server>:5080/ the following steps are needed:

1. Under /etc/httpd/conf.d create a new “semaphore.conf” configuration file containing the following:

JkOptions     +ForwardURICompatUnparsed
AllowEncodedSlashes NoDecode

2. Under /etc/httpd/conf.d edit “uriworkermap.properties” to add an entry for Studio:

# This file provides sample mappings for the example
# worker "balancer" defined in workermap.properties.
# The general syntax for this file is:
# [URL]=[Worker name]

/admin/*=balancer
/manager/*=balancer
/examples/*=balancer
/workbench/*=balancer

3. Restart Apache by issuing

systemctl restart httpd

The “mod_proxy_ajp” way

Assuming that the “mod_proxy_ajp” Apache module is installed and Studio is installed and already available at http://<your-server>:5080/ the following steps are needed:

1. Under the “/etc/httpd/conf.d” directory create a new “semaphore.conf” configuration file containing the following:

ProxyRequests Off
AllowEncodedSlashes NoDecode

ProxyPass /studio/ ajp://localhost:8009/ nocanon
ProxyPassReverse /studio/ ajp://localhost:8009/

2. Update the Studio configuration file conf/server.xml to uncomment this line:

<!-- <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" /> -->

That is, change it to read:

<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

2. Restart Apache by issuing

systemctl restart httpd

and restart studio using

systemctl restart semaphore-studio

Optimizing the Apache configuration

When hosting Studio behind Apache Web Server it is often useful (and recommended) to ensure that Studio is served over SSL and that public KMM static resources are served directly by Apache instead of Studio (Tomcat). After standard SSL configuration of Apache, the SSL redirect can be configured as follows:

# Redirect to HTTPS
RewriteEngine On
RewriteCond %{HTTPS} !=on
RewriteCond %{REQUEST_URI} !^/widgets/.*$ [NC]
RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R,L]

In that case the “mod_proxy”, “mod_jk” or “mod_proxy_ajp” configurations above should be done in the correct virtual host.

Serving public resources via Apache directly AND performing the proxying of the studio request can be achieved by adding the following “mod_proxy” syntax to a configuration file under “/etc/httpd/conf.d/”:

ProxyPass "/studio/kmm/public" "!"
Alias "/studio/kmm/public" "/opt/semaphore/kmm/webapps/ROOT/public"

ProxyPass "/studio/" "http://localhost:5080/"
ProxyPassReverse "/studio/" "http://localhost:5080/"

SetOutputFilter DEFLATE
SetEnvIfNoCase Request_URI "\.(?:gif|jpe?g|png)
quot; no-gzip