Serving matchbox server over https

I get asked quite often how to deploy matchbox to the public web over https. In this post, I'll explain the how I do it for my own projects, using docker-compose and letsencrypt at $2 per month.


This is just how I do it, I'm not an infrastructure expert or anything. I just wanted something that was cheap and easy for me to maintain and use, and picked the solution that looked most appealing to me... If you think something I do is a bad idea, or there are easier ways, please tell in the comments, and we might all learn from it.

For now, I'll keep this pretty brief, and link to external projects/guides, but maybe I'll expand it into a full tutorial some day, if it gets really popular.


matchbox_server is available both an installable rust-crate, and as docker image, jhelsing/matchbox-server. We'll use the docker image in this post.


A Docker image makes it very easy to deploy it in a variety of places. I use a VPS (virtual private server), which is basically just a (in this case linux) virtual machine hosted somewhere where you can log in with ssh.

I'm using a single VPS from DigitalOcean running Ubuntu... Mostly out of habit. I've had for at least 5 years. It should work just as well with another provider. It just needs to have Docker installed.

For instance, Ionos has a deal at $2 per month, which looks pretty appealing.

I also use the same instance for a lot of other services/experiments I have on the web. For instance hosting this blog, my wife's portfolio page, and micro-services for authentication, user-data and matchmaking for one of my games in development.

https reverse proxy

With the approach I'm using, the matchbox server container actually just serves over regular http, while I let an Nginx container proxy the requests and add https to them.

web browser  <--https-->  nginx container  <--http-->  matchbox_server container

The image I'm using is nginx-proxy/nginx-proxy. Which has great documentation (go read it), so I'll keep it very brief here.

You'll want to also set up nginx-proxy/acme-companion as well. This image works in tandem with nginx-proxy and automates certificate registration and renewal through letsencrypt.

When nginx-proxy and acme-companion is running correctly, all you need to do to host something over https, is set four environment variables in the docker container you want proxied (jhelsing/matchbox-server):

  • VIRTUAL_PORT: The port where regular http is served on the container. For matchbox_server, it should be 3536
  • VIRTUAL_HOST: The (sub-)domain name name where you want the container to be reachable
  • LETSENCRYPT_HOST: The same domain again
  • LETSENCRYPT_EMAIL: your e-mail to use with letsencrypt

I like to save this configuration in a docker-compose.yml file. This is the one I'm using for my public instance.

version: '3.6'
    image: jhelsing/matchbox-server:0.7
      - "3536"
    restart: always
      VIRTUAL_PORT: 3536
    - nginx

    name: "nginx-network"

Then I can just start it by running...

docker-compose up -d the same folder, and letsencrypt certificates will be registered, installed and renewed automatically. And nginx-proxy will forward requests to my container... provided I have properly configured DNS to point to my VPS.

Using it with matchbox_socket

All you need to do know, is update the url you use when connecting to you matchbox socket to your new domain, and also use the wss:// prefix instead of ws://. That is:

let (mut socket, message_loop) = WebRtcSocket::new_unreliable("wss://")

Getting in touch

I hope you found this useful!

If you have questions, let me know in the comments, or ask me in the #matchbox room on my discord server.


Loading comments...