Getting webpack-dev-server running with boot2docker

(Solution is available on github).

You encounter two problems with this setup:

  1. webpack-dev-server detecting file changes made in OS X
  2. in the OS X web browser hitting the correct address to communicate with the container

Before continuing a quick illustration of how boot2docker works:

boot2docker toplogy

To begin fixing these issues firstly use this fantastic script It handles installing boot2docker but comes with two extra parts needed:

  1. uses an rsync solution instead of VirtualBox’s vboxsf filesystem that has problems of slow performance and not working with some file watchers running inside containers.
  2. adds a dockerhost entry to OS X’s /etc/hosts that is used as a URL to reach docker containers.

After running that script it is advisable to run boot2docker upgrade to make sure the boot2docker VM is up-to-date and the docker daemon and docker client versions match.

The directory structure for this example is very much like a typical webpack project structure:


In OS X run the docker-osx-dev command to get rsync watching the directories to be synced. It is advantageous to not be syncing the node modules by using the -e flag docker-osx-dev -e node_modules.

Next start a docker container. This example is mapping port 3030:

docker run -it --name myproject -v ${PWD}/:/usr/src/ -w /usr/src/ -p 3030:3030 iojs /bin/bash

Inside the container webpack-dev-server is running with this command inside package.json via npm run start.

"scripts": {
"start": "webpack-dev-server --config webpack.development.js --devtool eval-source --progress --colors --hot --inline --history-api-fallback --host --port 3030 --content-base build"

See more about the flags being passed check the webpack docs.

The hostname needs to be changed from the default localhost to This is because localhost is not mapped to the VirtualBox boot2docker VM. And port 3030 is mapped so it matches up with the docker run command.

With the dev-server running index.html should now be accessible from OS X at http://dockerhost:3030. Changes to files inside app/ should be detected and synced by rsync and the dev-server running inside the docker container will detect these changes and reload.

It is important to know of the current limitation that if you modify a file inside the container it will not propagate back up to OS X. So if inside the container you run npm i react --save package.json will not update in OS X.

An example solution is available on github. It includes a Makefile with alias’s to the commands needed to be run from OS X and inside the docker container.