Koop CLI v1.1 release: add HTTPS support to the dev server

Jan 19, 2021 • Haoliang Yu

HTTPS support is one of the mostly requested features for Koop. In the recent release of Koop CLI v1.1, we have added the support of HTTPS to the dev server for Koop plugin projects, which allows to create a local HTTPS server with simple command options. In this blog, we will discuss this new feature.

New serve options

After updating the CLI version to v1.1 and checking the documentation for the serve command, you will see two new options --ssl-cert and --ssl-key. Note that these two options only work for Koop plugin (provider, output, auth, etc.) projects. If you use these two options in an app project, the values will be ignored.

$ koop serve [path]

run a koop server for the current project

  path  server file path                                                [string]

  --port      port number of the server                 [number] [default: 8080]
  --data      path to a GeoJSON data file for testing Koop plugin
                                         [string] [default: "test/data.geojson"]
  --debug     enable nodejs inspector for debugging                    [boolean]
  --watch     enable auto-restart on file change                       [boolean]
  --ssl-cert  path to the SSL certificate file                          [string]
  --ssl-key   path to the SSL key file                                  [string]

These options is used to provide the path to the SSL certificate and key files. If both paths are provided, the command will starts a HTTPS server, instead of a HTTP one.

For example, if I have the certificate file cert.pem and the key file key.pem in the project directory, I can run the server command

$ koop serve --ssl-cert cert.pem --ssl-key key.pem

and the server will start with the following message

Server listening at https://localhost:3000

Note that the URL protocol now is https, instead of http. Such URL is ready to be used in the client that requires HTTPS links.

Under the hood

The server command uses the native node moudle https to create the HTTPS server. You can see the exact implementation in the office guideline How to create an https server?.

What about production use? What about app?

As the whole blog post is talking about the dev server, you may ask “What about the production?”. Since Koop is a dedicated ET(L) server, it does not incldue the HTTPS feature. Implementing HTTPS feature directly in nodejs is not scalable and should not be used for production.

The common industrial practice is to use a proxy server (like nginx) or the service from your cloud provider.