Using Docker to speed Experience Builder development

Simplifying version changes and widget development.

One of the challenges I faced on a project recently, was the need to upgrade the underlying version of Experience Builder as new versions came available. Out of the lessons of this, and after seeing some videos on the Esri YouTube channel, I have put together some Docker images that wrap Experience Builder Developer Edition and allow you to keep focussed on widget and app development, and not have to worry about upgrading Experience Builder as new versions become available.

I cannot take the credit for this approach, it was demonstrated by Chris Dougherty and Andrew Breeding from Langan in this YouTube video from the 2021 Esri Dev Summit. I have taken this approach and modified it for my needs to allow for a full CI/CD approach with Azure DevOps.

Prerequistes

1. Docker installed on your local machine.

2. An account with Esri.

3. Knowledge of Experience Builder Dev Edtion and how to install it.

---

Get Experience Builder

The first thing to do is head to the Esri developers page for Experience Builder and download a copy of the latest (or not) version of the Developer Edition.

Select the version you want to use, and download it.

Once its downloaded, you will need to unzip it, as we need to make one small change.

In the unzipped folder, navigate to client/webpack/webpack-extensions.common.js and open it.

Search for

devServer: webpackCommon.devServer

Add in the following below, making sure to add in a comma at the end of the above line.

    watchOptions: {
      poll: 1000,
      ignored: /node-modules/
    },

Adding this in ensures that each time we save our files in the your-extensions folder, we will trigger the build process to push our updates in to the dev server.

Compress the folder in to a zip file again, and make sure you take note of the name, I like to keep the name the same as the download.

Create a new folder to act as the container for all your files,within this, create two folders

-build-commands

-setup

Copy your zipped updated Experience Builder files in to the setup folder.

Now open up your IDE of choice, I prefer to use Visual Studio, while some like to use VSCode. It doesn't matter, you just need access to the files and the ability to run some commands and navigate to your container folder

Now add in a new file, ths file should not have an extension, call it Dockerfile-<ExB Version>, eg Dockerfiler-1.9 or Dockerfile-1.8

Copy in the following to the file.

FROM node:lts

#Copy and unzip configuration files
WORKDIR /home/node
COPY setup setup/
RUN unzip setup/arcgis-experience-builder-1.9.zip

#Install dependancies
WORKDIR /home/node/ArcGISExperienceBuilder/client/
RUN npm ci

WORKDIR /home/node/ArcGISExperienceBuilder/server/
RUN npm ci

The above is what we will use to build our Docker image for Experience Builder.

The first line states that we want to use the latest node version as the basis for our container.

Next we state, where in that image, we should put all our files.

We then copy the files out of the setup folder in to the image.

Next we unzip the folder.

When then change the working directory and call the npm ci command to install the client folder for Experience Builder.

We then do the same for the server folder.

Now, open a terminal window, and make sure you are at the root of your container folder.

Run the following command:

docker build -f Dockerfile-1.9 -t esri-exb:exb-1.9 .

The above command will use the docker file we created to build the image, the -t lets us tag the image, here we are using exb-1.9, also note the final "." this is important as it tells the machine where we want to build the image (this is the PATH). More details on the build command can be found in the Docker documentation.

If you have your own docker account on Docker Hub, you can also build this against your account.

docker build -f Dockerfile-1.9 -t <docker-username>/esri-exb:exb-1.9 .

Docker will now go through the process of building the image for you. Once its done you can optionally push this to Docker hub with the following command.

docker push <docker-username>/esri-exb:exb-1.9

With that all done, you have now built a Docker container with Experience Builder. Easy huh!

---

Using your container

Now that you have your container, you want to see it up and running. For a full description that shows how to do this, and connect a full CI/CD workflow, see the blog post here

If you just want to get up and running, then read on.

Create a folder on your machine, call it something useful like, docker-exb.

Within that folder, create another folder called volumes.

Within volumes, create three folders,

• public

• themes

• widgets

We will now map these folders in to our Experience Builder container.

Create a new file in the root of the project and call it docker-compose.yml and paste in the following.

version: "3.9"
services:
  exb:
   image: esri-exb:exb-1.9
   ports:
       - "3000:3000"
       - "3001:3001"
   volumes:
       - ./volumes/widgets:/home/node/ArcGISExperienceBuilder/client/your-extensions/widgets/
       - ./volumes/themes:/home/node/ArcGISExperienceBuilder/client/your-extensions/themes/
       - ./volumes/public:/home/node/ArcGISExperienceBuilder/server/public/
       - ./volumes/types:/home/node/ArcGISExperienceBuilder/client/types
   command: >
        bash -c "cd ../server &&
        npm --prefix ../client start & npm start"

The above compose file will instruct docker how to start up Experience Builder. in the image section we specify the image we created earlier, and map the ports from the container to our local machine.

We then map in the folders we just created to the equivalent folders within the container.

We then run the Experience Builder commands to start the Experience Builder servers.

To start everything up, open a terminal window and run

docker compose up

When Docker starts up, you may see some errors, these will be related to us not having anything in the widgets folder. You can copy in the simple widget from the orginal download.

If we start developing now, we can't take advantage of the type ahead features provided by TypeScript as the complier does not know where our types are. This can be seen by the red squiggly line under jimu-core.

We need to make the types from the jimu libraries available to the TypeScript compiler. To do this, create a new folder under widgets called node_modules.

Next, in a terminal window run the following to get the id of the container.

 docker ps -aqf "ancestor=cargr563/esri-exb:exb-1.9"

Next substitute the containerId in to the code below.

docker cp <containerId>:/home/node/ArcGISExperienceBuilder/client/jimu-arcgis ./volumes/widgets/node_modules/@types
docker cp <containerId>:/home/node/ArcGISExperienceBuilder/client/jimu-core ./volumes/widgets/node_modules/@types
docker cp <containerId>:/home/node/ArcGISExperienceBuilder/client/jimu-for-builder ./volumes/widgets/node_modules/@types
docker cp <containerId>:/home/node/ArcGISExperienceBuilder/client/jimu-for-test ./volumes/widgets/node_modules/@types
docker cp <containerId>:/home/node/ArcGISExperienceBuilder/client/jimu-icons ./volumes/widgets/node_modules/@types
docker cp <containerId>:/home/node/ArcGISExperienceBuilder/client/jimu-layouts ./volumes/widgets/node_modules/@types
docker cp <containerId>:/home/node/ArcGISExperienceBuilder/client/jimu-theme ./volumes/widgets/node_modules/@types
docker cp <containerId>:/home/node/ArcGISExperienceBuilder/client/jimu-ui ./volumes/widgets/node_modules/@types

Then copy the result in to the terminal window and run it. This will copy the Experience Builder types out of the container in to your local machine.

This should mean the red error line under jimu-core disappears, meaning the compilier can find the correct types.

With this done, you can now start creating custom widgets and applications. If you need to upgrade, you can reproduce the steps above with the new version of Experience Builder, and then in your docker compose file, simply update the image.

eg, I could run the below to start version 1.8 (assuming I had an image for 1.8)

version: "3.9"
services:
  exb:
   image: esri-exb:exb-1.8
   ports:

You can now also run the application widgets through a CI/CD pipeline to build and deploy the application automatically. For information on that, see the blog post here.