Skip to content

Apache

sudo## Apache setup

This guide assumes you have apache set up and running. It covers creation of a virtual host for each facility you want to manage.

In this case we are going to create a virtual host for the Example University of Examples and another for Staging (i.e. a test facility).

Prerequisites:

  1. you have purchased the domain zsm.com
  2. you have set up a sub-domain for the Example University of Examples called eue.zsm.com
  3. you have chosen to run the zf-server for eue on port 3004.
  4. you have built the zf-client and installed it in the appropriate directory. In the deployment doc we suggested /var/www/zsm/zf-client

Virtual Host Files

You are now ready to create your virtual host for eue.zsm.com

Note

This is what the file looks like before you do the SSL configuration. That process will update this file.

  1. go to your apache configuration directory. On Debian this is in /etc/apache2/sites-available.
  2. create a new virtual host configuration file called eue.zsm.com.conf.
  3. edit the file appropriately by copying the example below and adjusting it to how you have deployed your client and configured your server.
<VirtualHost *:80>
    ServerAdmin email_for_your_server_administrator@some_email_provider.whatever
    ServerName eue.zsm.com

    # Note *ALL* facilities share the same zf-client 
    DocumentRoot /var/www/zsm/zf-client

    ErrorLog ${APACHE_LOG_DIR}/eue.error.log
    CustomLog ${APACHE_LOG_DIR}/eue.access.log combined

    # We need to use the RewriteEngine
    RewriteEngine On

    # If the incoming request is aimed at the server,
    # proxy to the port the facility-specific server is running on.
    # The port you choose has to be different for each facility.
    # The port you choose must be added to server configuration file to this facility.
    RewriteRule ^/zf-server/(.*) http://localhost:3004/$1 [P]

    # If there is an existing asset or directory in the request, then route to it.
    RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -f [OR]
    RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -d
    RewriteRule ^ - [L]

    # Otherwise links like /stock_manager (for which there is no static file)
    # are all written to /index.html where the angular app will handle the route.
    RewriteRule ^ /index.html
</VirtualHost>

After editing the file you need to:

# enable the new site
sudo a2ensite .../sites-available/eue.zsm.com.conf

# validate your configuration
sudo apachectl configtest

# reload apache
sudo systemctl reload apache2

Am I ready to move on?

In order to proceed, the DNS configuration for the sites you are going to secure must be working. You can test this with a simple ping:

ping eue.zsm.com
# should tell you the IP address of your deployment host

Once that is working, you can now enter your subdomain in your browser. In the example you would put http://eue.zsm.com. If you get a message like "This site can't be reached", then there is a problem with your Apache configuration. If you get a blank screen your site has been reached, but it is not up yet. You can move on.

Note: forwarding requests to the appropriate zf-server

When the client sends requests to the zf-server the requests go first to the web server (Apache in this case) which provides all kinds of value, not the least of which handling SSL decryption, before passing the request on to the zf-server.

We have configured Apache to do this with the following line in the config file:

RewriteRule ^/zf-server/(.*) http://localhost:3004/$1 [P]

Apache recommends that you proxy with ProxyPass rather than RewriteRule. That * could* be accomplished with the following configuration:

ProxyPass /zf-server http://localhost:3004
ProxyPassReverse /zf-server http://localhost:3004

But we have another RewriteRule in the configuration that looks like this:

RewriteRule ^ /index.html

The problem is that this RewriteRule takes precedence over the ProxyPass rule. We would have preferred to use and would therefore rewrite all requests to the zf_server to index.html before the ProxyPass rule would take effect.

Consequently, we have decided to implement proxying to the server with a RewriteRule.

Secure your site with SSL

To ensure secure connections, you need to get a certificate that will secure your domain and all "per-facility" subdomains you are going to deploy.

Here is a good description of the process using Certbot How to secure Apache .

Once you have done all the legwork there to set up Certbot you need to generate a certificate that for your domain and the subdomain for each facility.

# one time only for your domain
sudo certbot --apache -d zsm.com

# every time you set up a new subdomain
sudo certbot --apache -d your-new-subdomain.zsm.com

When you run the above command, we suggest that you allow certbot to modify your apache configuration to redirect all http traffic to https.

Certbot will guide you through the rest of the process of installing the certificate. Again, we recommend that you allow it to redirect all http traffic to https.

All facilities (first or subsequent)

Certbot will have created and enabled a https site for you. It will even have tried to edit the Virtual Host file you already created, but the RewriteRules it added to the config file are insufficient. Just edit your apache config file ( eue.zsm.com.conf) to permanently redirect all insecure (http://) traffic to your secure (https://).

The file will look like this:

<VirtualHost *:80>
    ServerName eue.zsm.com
    Redirect permanent / https://eue.zsm.com
    RewriteEngine On
    RewriteCond %{SERVER_NAME} =eue.zsm.com
    RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
</VirtualHost>

Am I ready to move on?

Your site should now be fully functional.

You might also want to go to this site:

https://www.ssllabs.com/ssltest/

Enter your subdomain (in this case eue.zsm.com) in the Hostname, hit the "Submit" button. You should get a reasonably good report! It takes a couple of minutes to run.