Containerizing a workflow: using Docker to “Build A Banner”
We use a custom-built animation workflow at JMX2 that we’ve containerized with Docker to ensure it runs consistently on any machine we work on. We’ll go over that process in this post.
The background
At JMX2, we build a lot of animated advertising banners. (You’re welcome! :winking_face:) In 2015, we created a Yeoman generator called “Build A Banner” to quickly create a consistent starting point for each project. This required having Yeoman, Node, Gulp.js, and Sass installed on the development machine.
Before we dive in further, let’s get some terminology out of the way. Yeoman is a scaffolding tool that creates and customizes files to help start nearly any type of project. Gulp.js is an automation tool written in Javascript. Sass is a CSS preprocessor that adds helpful things like nesting, mixins, and inheritance.
The Yeoman Build a Banner generator, which we refer to as BAB, asks a series of questions, like the dimensions of the animation, the advertising platform, the naming convention you’d like to use, and more. These values customize the generated files. For example, you could start with a set of files customized to create a 300×250 ad for use with Google Ad Words.
A “generator” is the set of instructions that can generate any type of project. For example, my friend, Andrew Welch, has created a Yeoman generator, generator-craftplugin that scaffolds out the starting point for a module or plugin for Craft CMS. A Craft plugin combines PHP, HTML, Javascript, and CSS. Microsoft has a Yeoman generator that scaffolds out a starting point for a VSCode extension, vscode-generator-code. There’s even a generator, called generator-generator to help you create new Yeoman generators!
The Build a Banner generator, generator-buildabanner, scaffolds out a project that combines Javascript, including the Greensock animation library, HTML, and Sass for CSS generation. Once a project has been generated, it uses Gulp.js to spin up a development server with live-reload during development. It also uses Gulp.js in a build process to minify the files in the correct format that media companies expect to receive an animated. When you’ve completed a project, it uses Gulp to create a small archive file of the banner files for long-term storage.
You can see the BAB project on npm here. If you look at the releases page, you’ll see there have been 57 releases at the time I write this.
We use a custom-built animation workflow at JMX2 that we’ve containerized with Docker to ensure it runs consistently on any machine we work on. We’ll go over that process in this post.
The background #
At JMX2, we build a lot of animated advertising banners. (You’re welcome! :winking_face:) In 2015, we created a Yeoman generator called “Build A Banner” to quickly create a consistent starting point for each project. This required having Yeoman, Node, Gulp.js, and Sass installed on the development machine.
Before we dive in further, let’s get some terminology out of the way. Yeoman is a scaffolding tool that creates and customizes files to help start nearly any type of project. Gulp.js is an automation tool written in Javascript. Sass is a CSS preprocessor that adds helpful things like nesting, mixins, and inheritance.
The Yeoman Build a Banner generator, which we refer to as BAB, asks a series of questions, like the dimensions of the animation, the advertising platform, the naming convention you’d like to use, and more. These values customize the generated files. For example, you could start with a set of files customized to create a 300×250 ad for use with Google Ad Words.
A “generator” is the set of instructions that can generate any type of project. For example, my friend, Andrew Welch, has created a Yeoman generator, generator-craftplugin that scaffolds out the starting point for a module or plugin for Craft CMS. A Craft plugin combines PHP, HTML, Javascript, and CSS. Microsoft has a Yeoman generator that scaffolds out a starting point for a VSCode extension, vscode-generator-code. There’s even a generator, called generator-generator to help you create new Yeoman generators!
The Build a Banner generator, generator-buildabanner, scaffolds out a project that combines Javascript, including the Greensock animation library, HTML, and Sass for CSS generation. Once a project has been generated, it uses Gulp.js to spin up a development server with live-reload during development. It also uses Gulp.js in a build process to minify the files in the correct format that media companies expect to receive an animated. When you’ve completed a project, it uses Gulp to create a small archive file of the banner files for long-term storage.
You can see the BAB project on npm here. If you look at the releases page, you’ll see there have been 57 releases at the time I write this.
The problem we’re trying to solve
We’ve installed Yeoman and BAB on many different computers since 2015. We’ve had to debug installations quite a few times along the way, and these installation issues typically revolved around the Node installation, permission problems, or conflicting versions of other software.
In 2022, we’re at the point where we’ve updated our computers again, and instead of debugging another installation of Node, Gulp, Yeoman, we’ve created a Docker image that contains all the pieces of the BAB project.
Moving the workflow to a Docker image has changed the requirements of running Build A Banner. The new setup requires Docker Desktop, and that’s the only requirement. It doesn’t matter what version of Node you have installed because it isn’t needed to use BAB. No node? No problem! (Hey, I should write that down!)
Once Docker Desktop is on your computer, you can pull the BAB image and run the container. The container has the needed versions of Node, Gulp, and Sass already installed. You don’t need to install them on your own machine.
Try it yourself
Confirm that Docker is installed and running. Now open up your terminal and create a new empty directory somewhere on your filesystem and then cd
into that directory. Then run the following command.
docker container run -p 8080:8080 -p 35729:35729 -v "$PWD":/app -it --rm johnfmorton/yo-buildabanner
You should see the image download and run when it’s ready. Then you will see a command prompt again. You’re no longer in “your” computer, though; you’re now inside the custom Docker container with Yeoman and Build A Banner installed and configured. The command prompt is customized to make it easy to recognize that you are inside the container.
The problem we’re trying to solve #
We’ve installed Yeoman and BAB on many different computers since 2015. We’ve had to debug installations quite a few times along the way, and these installation issues typically revolved around the Node installation, permission problems, or conflicting versions of other software.
In 2022, we’re at the point where we’ve updated our computers again, and instead of debugging another installation of Node, Gulp, Yeoman, we’ve created a Docker image that contains all the pieces of the BAB project.
Moving the workflow to a Docker image has changed the requirements of running Build A Banner. The new setup requires Docker Desktop, and that’s the only requirement. It doesn’t matter what version of Node you have installed because it isn’t needed to use BAB. No node? No problem! (Hey, I should write that down!)
Once Docker Desktop is on your computer, you can pull the BAB image and run the container. The container has the needed versions of Node, Gulp, and Sass already installed. You don’t need to install them on your own machine.
Try it yourself #
Confirm that Docker is installed and running. Now open up your terminal and create a new empty directory somewhere on your filesystem and then cd
into that directory. Then run the following command.
docker container run -p 8080:8080 -p 35729:35729 -v "$PWD":/app -it --rm johnfmorton/yo-buildabanner
You should see the image download and run when it’s ready. Then you will see a command prompt again. You’re no longer in “your” computer, though; you’re now inside the custom Docker container with Yeoman and Build A Banner installed and configured. The command prompt is customized to make it easy to recognize that you are inside the container.
Ports exposed
You will see that 2 ports were opened in the docker command, port 8080 and port 35729. BAB uses 8080 for viewing the banner in development in your browser. Port 35729 is used to communicate with the browser for live-reloading of the page when you update the HTML, JS, or CSS during development.
Working in the container
There are several commands you can run here. Since you’re just starting a banner, you’ll first need to generate the banner with Yeoman. Enter this command.
yo buildabanner
A series of prompts appear to customize your banner. After you complete the prompts and are again at the command line prompt, enter the following to get the local dev server running.
gulp
Open your browser and go to http://localhost.com:8080. You should see a basic animated banner. At this point, you edit the HTML, CSS, and Javascript, which will cause your web browser to reload each time you save your work.
After customizing the banner to your liking, stop the gulp
process with CTRL‑C. Then build the banner with gulp build
. You can also archive the banner project with the gulp archive
command. In this case, my definition of “archive” means taking the customized files and zipping them up for long-term storage.
Ports exposed #
You will see that 2 ports were opened in the docker command, port 8080 and port 35729. BAB uses 8080 for viewing the banner in development in your browser. Port 35729 is used to communicate with the browser for live-reloading of the page when you update the HTML, JS, or CSS during development.
Working in the container #
There are several commands you can run here. Since you’re just starting a banner, you’ll first need to generate the banner with Yeoman. Enter this command.
yo buildabanner
A series of prompts appear to customize your banner. After you complete the prompts and are again at the command line prompt, enter the following to get the local dev server running.
gulp
Open your browser and go to http://localhost.com:8080. You should see a basic animated banner. At this point, you edit the HTML, CSS, and Javascript, which will cause your web browser to reload each time you save your work.
After customizing the banner to your liking, stop the gulp
process with CTRL‑C. Then build the banner with gulp build
. You can also archive the banner project with the gulp archive
command. In this case, my definition of “archive” means taking the customized files and zipping them up for long-term storage.
Here’s a quick video of me creating a banner and launching the development environment to show you how I use BAB.
I won’t get into the process of actually customizing the banner animation. I’ve left comments in the HTML and Sass files but building the animation where the work is for an animation project. The goal of BAB is to let us focus our time on the animation and not the development setup process.
Here’s a quick video of me creating a banner and launching the development environment to show you how I use BAB.
I won’t get into the process of actually customizing the banner animation. I’ve left comments in the HTML and Sass files but building the animation where the work is for an animation project. The goal of BAB is to let us focus our time on the animation and not the development setup process.
Aliases
The final thing we do on our computers is to make the docker command easier to remember. We’ve updated our rc
files, specifically the .zshrc
file since we’re on Macs using the ZSH shell, with aliases. The first is the most useful one.
alias banner='docker container run -p 8080:8080 -p 35729:35729 -v "$PWD":/app -it johnfmorton/yo-buildabanner'
This alias allows us to type banner
into the terminal and quickly be in the Build A Banner container.
We have a 2nd alias that we use only occasionally.
alias bannerupdate='docker pull johnfmorton/yo-buildabanner:latest'
This alias is handy for updating our local Docker image with the latest one posted on Docker Hub. We can simply type bannerupdate
to download the latest image.
As always, I hope this was helpful. You can find me on Twitter if you’ve got any feedback. Thanks.
Aliases #
The final thing we do on our computers is to make the docker command easier to remember. We’ve updated our rc
files, specifically the .zshrc
file since we’re on Macs using the ZSH shell, with aliases. The first is the most useful one.
alias banner='docker container run -p 8080:8080 -p 35729:35729 -v "$PWD":/app -it johnfmorton/yo-buildabanner'
This alias allows us to type banner
into the terminal and quickly be in the Build A Banner container.
We have a 2nd alias that we use only occasionally.
alias bannerupdate='docker pull johnfmorton/yo-buildabanner:latest'
This alias is handy for updating our local Docker image with the latest one posted on Docker Hub. We can simply type bannerupdate
to download the latest image.
As always, I hope this was helpful. You can find me on Twitter if you’ve got any feedback. Thanks.