Saturday 24 January 2015

Dockerize a node.js WebSocket server in 5 minutes

Docker is an incredibly useful tool to build prototypes of Linux hosts and applications.

You can easily build a network of servers inside a single virtual machine, with each server represented by a docker container. Clients can access the services on the same IP address, but different ports.

In this post I'd like to talk about a common prototype case in WebRTC platforms: a WebSocket server. This will be a node.js server and will run inside a Docker container (hosted by an Ubuntu Trusty VM).

The server logic can be as complex as you can imagine, but since it's not the point of this post I'll keep it as simple as the server example in the node.js websocket module:

The WebSocket server will listen on port 8080, accept incoming connections, send back "something" upon client connection, and log the content of the messages from the clients.

We can assume all the files in this article are in the same folder, and we're cd into it. The server logic is inside a 'server.js' file.

As explained in this interesting post from Ogi, you can find docker images with node.js all set and ready to be used, but the purpose of this post is to go a level deeper and build our own image.

Let's create a Dockerfile like this:
Even if you're not familiar with Dockerfiles, I'm sure you find this self-explanatory. The tricky bits are on line 13, where we symlink the nodejs executable to the desired '/usr/bin/node' (see here why), and line 16, where we install the node.js ws module via the npm package manager.

Line 18 tells docker what port this container is expected to receive connections to.

Line 20, the ENTRYPOINT definition, tells docker what command to execute when running.

(Remember that a docker container will run as long as there's a running command in foreground, and will exit otherwise.)

From inside the same folder, we can build our container image with:

docker build -t gvacca/nodejs_ws .

'gvacca' is my username, and 'nodejs_ws' is an arbitrary name for this container. Note the '.', which tells docker where to find the Dockerfile. You've probably noticed I've run 'docker build' without 'sudo': for practical purposes I've added docker into the sudo group.

The command above, when run for the first time, generates about 1K lines of output; you can find in this gist an example.

I can see the image is available:

gvacca@my_vm:/home/gvacca/docker/nodejs_ws$ docker images|grep nodejs_ws
gvacca/nodejs_ws            latest              332dae6a34f1        4 minutes ago       493.1 MB

Time to run the container:

docker run -d -p 8080:8080 -v $PWD:/root gvacca/nodejs_ws

This is telling docker a few things:

1. Run the container in daemonized mode (-d)
2. Map the port 8080 on the host with port 8080 on the container (and yes, they can be different)
3. Create a VOLUME, which is a mapping between a folder on the host and a folder on the container (this is handy because allows you to change files without rebuilding the image)
4. Use the 'gvacca/nodejs_ws' image.

The reason why I don't need to specify a command to be executed is that this is already enforced by the Dockerfile with the ENTRYPOINT specification.

The container is up and running:

gvacca@my_vm:/home/gvacca/docker/nodejs_ws$ docker ps|grep nodejs_ws
6ce3498a67e2        gvacca/nodejs_ws:latest         /usr/bin/node /root/   17 seconds ago      Up 16 seconds>8080/tcp   ecstatic_feynman

gvacca@my_vm:/home/gvacca/docker/nodejs_ws$ sudo netstat -nap |grep 8080
tcp6       0      0 :::8080                 :::*                    LISTEN      18807/docker

Now, if you want to test quickly you can use this Chrome extension, which provides a GUI to instantiate a WebSocket connection and send and receive data through it, and play with it. The URL will be: 'ws://IP_ADDRESS:8080'.

You can also access the server's logs with:

docker logs 6ce3498a67e2

(where 6ce3498a67e2 is the first part of the container's unique identifier, as shown in the 'docker ps' output).

Once you have this in place, which takes much longer to describe than to do, you can start building your WebSocket server logic.


  1. Thanks for the post!

    By IP_ADDRESS do you mean the address returned by `docker inspect 6ce3 | grep IPAdd`? The container seems to be running without errors, but trying to connect over a websocket is failing both in my code, and with the GUI tool:

    > WebSocket connection to 'ws://' failed: Error in connection establishment: net::ERR_CONNECTION_REFUSED

    I don't seem to be having any better luck with or localhost, though, so I'm not sure what the issue is.

  2. Hi Don,
    IP_ADDRESS is the public IP address on the host.
    Docker has already set up port forwarding (look at iptables output) in order to route requests directed to IP_ADDRESS:8080 towards the private docker IP address (which should be in your example), and at a specific port that you can see, again, by looking at iptables.

    Try accessing from outside the host.

    I hope this helps, and thanks for commenting.


About ICE negotiation

Disclaimer: I wrote this article on March 2022 while working with Subspace, and the original link is here: