How to run SharePoint Framework Pattern and Practices Samples through Docker

I planned to write a blog post how to run the SharePoint Framework Workbench in a Docker container on Azure. After I found out this is currently not possible I switched the scope of my trial. Instead, I tried to create Docker container dynamically for projects based on SPFx.


There are two key takeaways explained in this post. You will learn how to build your Docker file specific for your upcoming projects, and you get to know how you can demo and try out all SPFx Pattern and Practices samples regardless the version currently needed by those projects.

Create Dynamic Dockerfile

First, let’s create a Dockerfile that automatically download the source code of any project. In my case, I used the SPFx PNP sample, but the same process works for any Git-based project. The result was the following ‘Dockerfile’ I created.

Docker file to create SPFX PNP Sample image

The FROM statement defines which NodeJS version the docker image should use. I set the NodeJS to version 4 LTS (long time support). Then I create a directory for the SPFx samples and directly cloned the pattern and practices samples to this folder. Now the base configuration of the image is ready.
If you like to adopt this for your next project change the source code URL to your project repository. Then the Docker image will include your project.

Some magic happens on the line where I define ‘ARG‘. This statement allows passing of additional arguments to the build process. I also set the name of the argument to be samplename which becomes a variable available throughout the rest of the build process.

I make use of this variable right after cloning of the GitHub repository by switching the current work directory. I appended the $samplename variable to the base path of the repository. When the build process starts, this variable will be automatically replaced with the defined argument.

After the new work directory in place, I install all node modules from the local package.json file. The only global dependency to run the sample is ‘gulp’.
Now we are ready to build the first Docker image.

Build Docker Image

The first sample I tried was I guess on of the oldest in the SPFX PNP samples repository. It is Waldek’s ‘jquery-cdn’ example, and as I explained earlier to build the Docker image successfully, we need to pass an argument to the build process.
The following command needs to be used to produce the ‘jquery-cdn’ sample image.

The ‘-t spfx-samples:jquery-cdn‘ argument follow the pattern ‘<imagename>:<tag name>’. The image name specifies the name of the docker image, and I used the tag name to identify the sample used.

The ‘–build-arg‘ definition sets the ‘samplename’ variable in the build process, and this is used to switch to the actual sample that should be included.
It will changes directory definiton ‘/usr/src/spfx-samples/samples/$samplename’ to the path ‘/usr/src/spfx-samples/samples/jquery-cdn’. If you like to try another sample simply change ‘jquery-cdn” to another proper folder name in the Github repository.

The build process will take some time to complete. This mostly depends on the version of SPFx Framework was used. The newer, the faster the build process will be. In the case of the ‘jquery-cdn’ sample, it took a couple of minutes.

First Run of sample image

Not that then build process has completed its time to start a new instance of the created image. Before please make sure you created a new entry in your host file.

I use a similar start command like Waldek did in his post but to launch the image some parameter are not required. No username needs to be passed, and the resulting command looks like this.

  • -h spfx‘ defines the host name that can be used to access the workbench from your local machine.
  • –name spfx-jquery-cdn‘ specifies the container name that should be set for the docker container. Without using a proper name, Docker will create random strings instead. Besides, every run will produce a new container which can eat up your free disk space. This is something you like to avoid.
  • -it‘ switch allows you to connect to the container via shell.
  • -p‘ specifies the ports that should be available to access the container.

The last part represented by ‘spfx-samples:jquery’ defines the image and tag that should be used to launch. Once it is running all you have to do is to open your browser and access the workbench using ‘https://localhost:5432/workbench‘.

After you tested and stopped your container, you won’t be able to execute the previously used command again. You get the following error message.

This error will be shown when you run a named container again.

This is because the container was defined with a particular name. Unless you remove or rename this container this command will always fail.

Start previously create container

Instead of provisioning container all the time it is easier to start and stop containers.

This command starts the container ‘spfx-jquery-cdn’ again. The command only returns the name without any indication if it is running. To check that the docker container is running you can execute the following command.

This lists all your currently running container.

Start and get running Docker Containers

Start and get running Docker Containers

With the container in running start, you are able to access workbench again.
This is really straightforward, and you can stop the container by using docker stop <container-name> to shut it down.
You can even connect to your running instance via shell. In general, this can be accomplished via SSH, but as long as you are working locally, the following command enables you to connect directly.

Most of the options shown here are similar to start and stop a Windows service. Even in case you are not that big fan of console commands yet, there is GUI tool available that comes with Docker. It allows you to execute the same commands by pushing buttons. It is named ‘Kitematic’ and can be launched via the Docker icon in your system tray.

Kitematic let’s control your container via a GUI

Summary – SPFx loves Docker

Wait – We haven’t installed the yeoman generator? This is because it is not needed to run the project. It is only needed when you like to create new projects or add web parts to existing solutions. All the information to run the workbench is stored in your main ‘package.json’ and the node modules properly resolved by npm install.

Docker used like this can help even other people than developers. Let’s say your project manager has a meeting with a customer and like to show your developed web parts. Only provision a Docker image containing your projects. Starting the workbench is as easy as starting a virtual machine. Have a software tester, simply hand over a docker image, and I think there are many other use cases this scenario is useful.

What’s next?

You will find the docker file on GitHub. Feel free to modify use it an reuse it as you like.

There are some issues I experienced testing this solution on Windows 10. For example, I wasn’t able to launch workbench in Microsoft Edge. This has nothing to do with SPFx it is more a limitation of Docker on Windows. For more constraints and workarounds check the common issues and fixes section of Docker on GitHub.
On Windows you also have two options for Docker container. You can use Linux Docker containers or Windows Docker containers. In the case of SPFx, I would recommend using Linux containers because they are much easier to handle in case of SPFx. You don’t need to install the build-essentials that you need to install on Windows.

Finally, I highly recommend to check out Waldek’s blog on SPFx on Docker too.

Primarily I am working on OSX, but I also tested this on Linux and Windows too. So it should work for you too.
You will find the Docker sample on my GitHub repository.
Currently, all the usage of Docker and SPFx is limited to localhost use only.
In future, you might be able to use your Docker container on Azure too, which makes absolute sense for me. I already opened an issue on Github, and it is likely that you are able to configure the hostname that should be used for the workbench.