Configure Apache#

Allow HTTP/HTTPS traffic#

Add to your service’s Pillar file:

apache:
  public_access: True

This will:

  • Open ports 80 (HTTP) and 443 (HTTPS)

  • Install the Apache service

  • Enable the mod_http2, mod_md and mod_ssl Apache modules

  • Enable an Apache configuration for acquiring Let’s Encrypt certificates

If you are only using Apache to serve Python apps, continue from Configure Python apps.

Bind addresses#

If the server has multiple web servers for different IPs, add to your service’s Pillar file:

apache:
  ipv4: 65.21.93.181
  ipv6: 2a01:4f9:3b:45ca::2

Add sites#

Add to your service’s Pillar file:

apache:
  public_access: True
  sites:
    ocds-docs-live:
      configuration: docs
      servername: standard.open-contracting.org
      serveraliases: ['live.standard.open-contracting.org']
      context:
        ocds_cove_backend: https://cove.live3.cove.opencontracting.uk0.bigv.io
        oc4ids_cove_backend: https://cove-live.oc4ids.opencontracting.uk0.bigv.io
        timeout: 1830  # 30 sec longer than cove's uwsgi.harakiri

This will:

  • Create a /etc/apache2/sites-available/{site}.conf file that includes a /etc/apache2/sites-available/{site}.conf.include file, which, together:

    • If apache.public_access is True and https isn’t False:

    • Create a virtual host serving port 80

    • Set the virtual hosts’ servername and serveraliases, if any

  • Symlink the new files from the etc/apache2/sites-enabled directory

  • Reload the Apache service if the configuration changed

The example above uses the docs configuration. The keys of the context mapping are made available as variables in the configuration template.

Note

To delete a virtual host, follow these instructions.

Reference: What to use When

Add basic authentication#

  1. Add, in a private Pillar file:

    apache:
      sites:
        SITE:
          htpasswd:
            NAME: PASSWORD
    

    This will add the user to the /etc/apache2/.htpasswd-SITE file.

  2. Reference the htpasswd file from an Apache configuration file. For example:

    <Location "/">
        AuthName "My Site"
        AuthType Basic
        AuthUserFile /etc/apache2/.htpasswd-SITE
        Require valid-user
    </Location>
    
  3. Or, use the proxy configuration in your service’s Pillar file:

apache:
  public_access: True
  sites:
    kingfisher-collect:
      configuration: proxy
      servername: collect.data.open-contracting.org
      context:
        documentroot: /home/collect/scrapyd
        proxypass: http://localhost:6800/
        authname: Kingfisher Scrapyd

Note

To delete an htpasswd entry, follow these instructions.

Acquire SSL certificates#

If apache.public_access is True and https isn’t False, mod_md is used to acquire SSL certificates from Let’s Encrypt. If the server name is new, you must:

  1. Deploy the service, if not already done.

  2. mod_md will request a certificate from Let’s Encrypt. Check for a message in /var/log/apache2/error.log, replacing TARGET:

    ./run.py TARGET cmd.run 'grep "Managed Domain" /var/log/apache2/error.log'
    

    For example:

    AH10059: The Managed Domain ssl-test.open-contracting.org has been setup and changes will be activated on next (graceful) server restart.
    
  3. Reload the Apache service, replacing TARGET:

    ./run.py TARGET service.reload apache2
    

The service should now be available at its https:// web address.

Test#

Test the HTTP redirect, replacing SERVERNAME:

$ curl -I http://SERVERNAME
HTTP/1.1 301 Moved Permanently
Date: Fri, 11 Dec 2020 12:34:56 GMT
Server: Apache/2.4.46 (Ubuntu)
Location: https://SERVERNAME/
Content-Type: text/html; charset=iso-8859-1

Test the HTTPS response:

$ curl -IL https://SERVERNAME
HTTP/2 200
date: Fri, 11 Dec 2020 04:26:57 GMT
server: Apache/2.4.46 (Ubuntu)
strict-transport-security: max-age=15768000

Check the certificates’ status:

curl https://SERVERNAME/.httpd/certificate-status

Check md-status, replacing TARGET:

./run.py TARGET cmd.run 'curl -sS http://localhost/md-status'

Each certificate’s OCSP "status" should be "good".

You can test the SSL configuration using SSL Labs.

Troubleshoot#

In case of error, see mod_md’s troubleshooting guide. If you need to test the acquisition of certificates, use Let’s Encrypt’s staging environment.

Enable Apache modules#

You might need to enable Apache modules to use non-core directives in your configuration files.

There are state files for common modules:

apache.modules.https

Provides support for the HTTP/2 protocol.

apache.modules.md

Acquires SSL certificates from Let’s Encrypt.

apache.modules.passenger

Adds the Passenger app server.

apache.modules.proxy

Adds ProxyPass, ProxyPreserveHost and other directives. Included by apache.modules.proxy_http and apache.modules.proxy_uwsgi.

apache.modules.proxy_http

Provides support for HTTP/HTTPS requests in ProxyPass directives. Included by the python_apps state file.

apache.modules.proxy_uwsgi

Provides supports for the uWSGI protocol in ProxyPass directives. Included by the python_apps state file.

apache.modules.remoteip

Adds RemoteIPHeader, RemoteIPTrustedProxy and other directives.

apache.modules.ssl

Included and required by apache.modules.md.

apache.modules.watchdog

Included and required by apache.modules.md.

To enable a module, include the relevant state file in your service’s state file. For example:

include:
  - apache.modules.remoteip

If you need another module, consider adding a state file under the salt/apache/modules directory.

Note

To disable an Apache module, follow these instructions.