LettuceEncrypt Support for Stormancer

Easily enable HTTPS on your stormancer server. This plugin leverages LettuceEncrypt to automatically create and renew certificates from Let’s Encrypt.

  1. Obtain a domain name for your server.

  2. Add Stormancer.LettuceEncrypt to your active plugins in bootstrapper.config.json:

    "plugins": {
        "Stormancer.Server.Node": "*",
        ...
        "Stormancer.LettuceEncrypt": "*"
    }
    
  3. Configure LettuceEncrypt in your node’s configuration file:

    1. In the api.public.bindings section, add an HTTPS endpoint, as follows:

      {
        "endpoint": [ "*" ],
        "settings": {
          "https": "lettuceEncrypt"
        }
      }
      
    2. Add a corresponding endpoint to the published array (we assume your domain name is set in a myDomain constant at the top of your configuration file):

      "published": [
          "https://{myDomain}"
      ]
      
    3. Add a lettuceEncrypt section under the plugins section if it does not already exist, with the following values:

      "lettuceEncrypt": {
          "enabled": true,
          // Which API type to use LettuceEncrypt with. Due to a current limitation, it cannot be enabled for both public and admin APIs.
          // Valid values are "public" and "admin".
          "apiType": "public",
          // Email for certificate renewal (required). Change this to your email address.
          "email": "email@email.com",
          // Domain name(s) to request certificates for
          "domainNames": [ "{myDomain}" ],
          // Use Let's Encrypt staging server for issuing certificate. true for testing ; false for prod
          "useStagingServer": true,
          // Directory to be used to save LettuceEncrypt data. Required.
          "certificateDirectory": "C:/strm-data/lettuceEncrypt",
          // Show detailed LettuceEncrypt (and Kestrel) logs.
          "showLogs": false
      }
      

    Make sure your certificateDirectory is writable by the user running Stormancer.

    Set useStagingServer to false when you are ready to request a real certificate. When it is set to true, Let’s Encrypt’s staging server will be targeted, letting you request as many certificates as you want for testing purposes, without consequences. Note that the root CA of the staging server is not trusted by default.

  4. Make sure port 443 is open to connections from anywhere, so that the domain name verification can be performed.

  5. Start Stormancer as usual. A certificate will be generated automatically for your endpoint.

In theory, you can add as many HTTPS endpoints as you like, using the same format as explained above.

Limitations

  • At least one of your endpoints must be listening on port 443, and this port must be open to any outside connection. This is required for Let’s Encrypt’s ALPN challenge, which is used to verify ownership of the domain name.

  • Currently, you have to choose between enabling LettuceEncrypt for either public or admin APIs, but not both. Enabling it for both public and admin APIs would cause domain name ownership verification to fail, for yet unknown reasons.