Skip to content
PathcoreFlow User Manual

HTTPS


By default, an on-premise deployment serves content via unsecured HTTP on port 80. To enable secure connections using HTTPS (port 443), a valid TLS/SSL certificate is required that is either self-signed or from a certificate authority (CA). These are the steps needed to configure HTTPS after a valid certificate is acquired.

Managing HTTPS

To enable HTTPS, some environment variables need to be changed in the .env file. For additional information on changing the environment for PathcoreFlow, see Configuration. The minimum configuration needed is:

  • The HTTP_ONLY environment variable must disabled via the .env configuration file
  • The certificate and key files (purchased, self-signed, or from Let's Encrypt) must be placed in the directory defined in PCW_SSL_DIR
Certificates should be renewed with the appropriate certificate authority and updated in PathcoreFlow before they expire.
To configure PathcoreFlow to use HTTPS

  1. Place the certificate and key files in the appropriate directory on the host server or VM. By default, the following path and names are used:

    • Certificate directory: /opt/pathcore/certs
    • Certificate file: fullchain.pem
    • Key file: privkey.pem
    These files must be in the PEM format.

  2. Use your preferred text editor to update the relevant environment variables in the .env file (the default location for this file is /opt/pathcore/compose/.env)

    1. PCW_SSL_DIR=/opt/pathcore/certs: the path to the directory containing the certificate and key files:

    2. PCW_HTTP_ONLY=0: enable HTTPS

    3. (Optional) PCW_SECURE_COOKIES=1: only allow user sessions via HTTPS. Enable this only if all users will be connecting to the PathcoreFlow service via HTTPS

  3. Restart the affected service components

To use a different certificate or key filename

  1. Use your preferred text editor to add the following environment variables to the .env file (the default location for this file is /opt/pathcore/compose/.env)

    1. PCW_SSL_CERT_NAME=server_cert.pem: to change the filename of the certificate file

    2. PCW_SSL_KEY_NAME=server_key.pem: to change the filename of the key file

To update the certificate

  1. Backup the existing certificate and key files

  2. Place the new certificate file(s) in the appropriate directory on the host server or VM. By default, this is /opt/pathcore/certs

    These files must be in the PEM format.

  3. Restart the affected service components

    It is recommended to backup the existing files before overwriting them.

Purchased Certificates

When purchasing certificates from a certificate service you must first provide them with a Certificate Signing Request (CSR). Creating a CSR is out of scope for this documentation.

Once you have received the certificate bundle you will need to create the full certificate chain to use as your certificate. This will help prevent issues with older browsers and operating systems.

The certificate issuer should provide documentation on how to create a certificate chain. In general, the certificates from the bundle need to be combined in a specific order:

  • Server Certificate -> Intermediate Certificate(s) -> CA Root Certificate
The certificate bundle MUST start with the server certificate, then any intermediary certificates, then the root certificate. If there are multiple intermediary certificates they need to be added in the correct order.

Here is an example command to generate a certificate chain bundle. This command is for illustrative purposes — the actual command will vary depending on certificate issuer. Here we also assume you have all of your certificate files supplied by the issuer in one directory on a Linux server.

cat ComodoRSAAddTrustCA.crt \
    ExtendedvalidationSecureServerCA.crt \
    AddTrustExternalCARoot.crt > fullchain.pem

Self-Signed Certificates

Self-signed certificates are only accepted by browsers where users have manually added the self-signed certificate to their list of trusted certificates.

OpenSSL can be used to generate the key and certificate files for a self-signed certificate:

openssl req -newkey rsa:2048 -new -nodes -x509 -days 365 \
    -keyout privkey.pem -out fullchain.pem

For more information on the openssl req command line options, see the openssl-req manpage.

Let's Encrypt

Let's Encrypt is a free, automated, and open Certificate Authority (CA). You can read more about the services they offer and how to subscribe on their documentation page.

To use Let's Encrypt with PathcoreFlow:

  • PathcoreFlow must be externally accessible via TCP ports 80 (HTTP) and 443 (HTTPS)
  • PCW_HOST must be set to a valid hostname which routes to PathcoreFlow. See Configuration - Environment Variables for more details on how to set this value
  • certbot must be installed on the host server or VM
To configure PathcoreFlow to use Let's Encrypt

  1. Enable HTTPS via the environment variables described above

  2. Use your preferred text editor to update the relevant environment variables in the .env file (the default location for this file is /opt/pathcore/compose/.env)

    1. PCW_ENABLE_CERTBOT=1: enable the certbot automation

    2. PCW_CERTBOT_EMAIL=your@email.address: an email address to receive communications from Let's Encrypt

  3. Request the initial certificate by running the certbot.sh script manually:

    /opt/pathcore/compose/scripts/certbot.sh

  4. Restart the affected service components

To renew a Let's Encrypt certificate

If the pathcoreflow-maintenance.timer systemd unit is installed and enabled, then the certificate should be automatically renewed 30 days before it expires.