You can buy a certificate and configure Ktor to use it, or you can use Let's Encrypt to automatically get a free certificate to serve
wss:// requests with Ktor. In this page you will discover how to do it, by either configuring Ktor to directly serve the SSL certificate for a single domain or by using Docker with nginx to serve different applications in different containers on a single machine easily.
Option1: With Ktor serving SSL directly
Configuring an A register pointing to the machine
First, you have to configure your domain or subdomain to point to the IP of the machine that you are going to use for the certificate. You have to put the public IP of the machine here. If that machine is behind routers, you will need to configure the router to DMZ the machine with the host, or to redirect at least the port 80 (HTTP) to that machine, and later you will probably want to configure the port 443 (HTTPS) too.
Generating a certificate
The Ktor server must not be running, and you have to execute the following command (changing
This command will start a HTTP web server in the specified port (that must be available as port 80 in the public network, or you can forward ports in your router to 80:8889, and the domain must point to your public IP), it will then request a challenge, expose the
/.well-known/acme-challenge/file with the proper content, generate a domain private key, and retrieve the certificate chain:
❌ Error output sample:
✅ Working output sample:
Converting the private key and certificate for Ktor
Now you have to convert the private key and certificates written by
certbot to a format that Ktor understands.
The chain and private keys are stored in
This will request a password for the export (you need to provide one for the next step to work):
With th p12 file, we can use the
keytool cli to generate a JKS file:
Configuring Ktor to use the generated JKS
Now you have to update your
application.conf HOCON file, to configure the SSL port, the keyStore, alias, and passwords. You have to set the correct values for your specific case:
If everything went well, Ktor should be listening on port 8889 in HTTP and listening on port 8890 in HTTPS.
Option2: With Docker and Nginx as reverse proxy
When using Docker with multiple domains, you might want to use the nginx-proxy image and the letsencrypt-nginx-proxy-companion image to serve multiple domains/subdomains on a single machine/ip and to automatically provide HTTPS, using Let’s Encrypt.
In this case you create a container with NGINX, potentially listening to port
443, an internal network accessible only between containers so nginx can connect and reverse proxy your websites (including websockets), and a NGINX companion handling the domain certificates by introspecting the configured Docker containers.
Creating a internal docker network
The first step is to create a bridge network that we will use so nginx can connect to other containers to reverse proxy a user's HTTP, HTTPS, WS, and WSS requests:
Creating an Nginx container
Now we have to create a container running NGINX doing the reverse proxy:
--restart=alwaysso the docker daemon restarts the container when the machine is restarted.
--network=reverse-proxyso NGINX is in that network and can connect to other containers in the same network.
-v certs:rothis volume will be shared with the letsencrypt-companion to access the certificates per domain.
-v conf, vhostso this configuration is persistent and accessible from outside in the case you have to do some tweaks.
-v /var/run/docker.sockthis allows this image to get notified / introspect about new containers running in the daemon.
-e --labelused by the companion by identify this image as NGINX.
You can adjust
/home/virtual/nginx* paths to the path you prefer.
Creating a Nginx Let's Encrypt companion container
With the nginx-proxy container, now we can create a companion container, that will request and renew certificates:
--restart=alwaysas the NGINX image, to restart on boot.
--network=reverse-proxyit need to be on the same network as the NGINX proxy container to communicate with it.
--volumes-from nginxit makes accessible the same volumes as the NGINX container so it can write the
-v certs:rwit requires write access to write the private key and certificates to be available from NGINX.
-v /var/run/docker.sockrequires access to docker events and introspection to determine which certificates to request.
Creating a service
Now we have NGINX and Let's Encrypt companion configured so they will automatically reverse-proxy your websites and request and serve certificates for them based on the environment variables
Using docker-compose, you can create a
docker-compose.yml file (without additional services) that could look like this:
You can find more information about how to deploy a docker and the Dockerfile.
The XForwardedHeaderSupport plugin
In this case you are using nginx acting as reverse-proxy for your requests. If you want to get information about the original requests, instead of the proxied nginx request, you will have to use the XForwardedHeaderSupport plugin.