Skip to content

How To: HTTPS

By default, the Reactor UI and API are served on unencrypted connections. If you prefer to use encrypted connections, this document describes how to configure Reactor to do that.

You will, of course, need a server certificate. You can either use a self-signed certificate, or a "real" certificate sourced from a trusted issuer (these often come at a cost, but there are trusted issuers of no-cost certificates like letsencrypt.org).

Trusted-issuer Certificates

Trusted-issuer certificates are only worthwhile if you (a) access Reactor using a full, publicly-resolvable DNS name (e.g. reactor.example.com) and (b) you access Reactor from outside your LAN. Getting a certificate from a trusted issuer varies by issuer and will not be covered here. If you go this route, make sure you get your certificate in PEM format.

Creating a Self-Signed Certificate using OpenSSL

OpenSSL is available on almost all Linux- and similar systems, so the procedure described below assumes you have it available. Windows users can read this article.

Create a self-signed certificate by issuing the following command:

openssl req -x509 -nodes -newkey rsa:2048 -days 365 -keyout reactor.key -out reactor.crt

The certificate generated from this command will be valid for 365 days (-days option). You can make it longer or shorter, as you wish. Using the command as shown, the key files will be generated in the current directory. Remember their name and location for later steps.

Self-Signed Certificate Warnings

Self-signed certificates, because they are not issued by a trusted issuer, will cause your browser to display warnings that the connection is not secure. This is because the certificate you create yourself can't be verified by all the world's browsers to really be you and your Reactor system (an attribute that trusted-issuer certificates have to reduce the risk of "man in the middle" attacks on connections). However, your self-signed certificate still contains all of the necessary attributes to perform the encryption of the connection and protect the data in transit from casual disclosure. You may need to instruct your browser or other tool to "ignore certificate warnings" (or similar) before it will proceed and complete the request.

Installing your Certificate and Enabling HTTPS

Whether self-signed or from a trusted issuer, your certificate will come in two parts: the certificate and the private key. The certificate is the public portion of a two-part symmetrical encryption key pair. Data will be encrypted using this public part, and then (reputedly) can only be decrypted using the private part. It is important that you keep the private key safe and private, as its name says. Since it's typically in a separate file, make sure the file's owner and access permissions restrict access so that only the user under which Reactor runs can read the file.

To install your certificate:

  1. Place your certificate and private key files in Reactor's config directory.

  2. Make a backup copy of your reactor.yaml configuration file (at least; a full backup of Reactor is recommended if you haven't done one in a while).

  3. In your reactor.yaml configuration, change the baseurl protocol from http: to https: and change the port number from 8111 to 8554 (IP address shown as a placeholder only -- use you actual host IP address):

    reactor:
  baseurl: "https://192.168.0.11:8554"

    Note that we are changing the port on which Reactor runs from 8111 to 8554. This is typical of HTTPS connections; for example, most public web sites use port 80 for HTTP and port 443 for HTTPS. Reactor will still take HTTP requests on 8111, it will just redirect them to HTTPS on 8554 (or whatever port your choose).

  4. In your reactor.yaml configuration, add the following two lines after the baseurl line (and indented to the same level with spaces) to configure the certificate and its private key:

    reactor:
  baseurl: "https://192.168.0.11:8554"
  pki_certfile: reactor.crt
  pki_keyfile: reactor.key

  5. If you are running Reactor in a docker container, you need to add port 8554 to the container's list of published ports.

    If you are using docker-compose, modify your docker-compose configuration file and add port 8554 to the expose and ports arrays, duplicating the formatting used for port 8111 in each.

    If you are using docker run to start the container, add a -p 8554:8554 to the command line.

    If you are using a GUI like Portainer or a NAS-provided management interface, you will need to figure out how that tool publishes ports for the container, and add port 8554 to that configuration. This should not be too difficult, because you can probably just look at how port 8111 is configured and duplicate that for 8554.

  6. Restart Reactor.

  7. Open the Reactor UI using the new HTTPS URL (from baseurl in step 3 above).

If you're having trouble connecting to the Reactor UI after enabling HTTPS, the reactor.log file will contain messages about what protocol (HTTP or HTTPS) and port Reactor is attempting to use. If you do a case-insensitive search in the log file for "httpapi" you should find messages that will help you.

If you're enabling HTTPS for Reactor, you may also be interested in configuring access control. Do not make Reactor available on any publicly-accessible address or port without enabling and configuring access control.

If the HTTPS port is other than 8111, Reactor's default port for (unencrypted) HTTP requests, Reactor will start an HTTP service on port 8111 to redirect requests to HTTPS. You can disable this feature by setting redirect_http to false in the reactor section of config/reactor.yaml.

Updated: 2024-May-22