Good Thymes with Spring Boot

Over the past few weeks I’ve been working quite a bit on my own personal pet project, mainly looking into ways that I can persist (store) data I’m collecting from the Transport for London (TFL) API, but also looking into ways in which I could efficiently present this data on the front-end to users.

This led to two new features in my code, firstly I implemented the Spring Data module to store search results in a local Mongo database and secondly I implemented a dynamic front-end using web templating (Thymeleaf). Out of this I’m going to write two separate blog posts on here, one on getting your Spring Boot app up and running with a local Mongo DB and this one, focusing on how to render data on the front-end using Thymeleaf.

In this post I will be using basic Spring Boot app we created in a previous post to demonstrate how to utilise Thymeleaf to provide dynamic templates for repeated use.  If you’re new to the idea of templating, by the end of this post you’ll notice that you’ll be able to create many front-end interfaces for your users without the need to create loads of separate HTML files! We’re aiming to re-use the same HTML files multiple times, that’s the main idea and beauty of using a web templating engine such as Thymeleaf!

What are we going to do?

  1. Add the Thymeleaf dependency to our projects’ pom.xml file
  2. Alter our existing controller code to pass data into a template HTML file
  3. Create a template HTML file to render content passed to it
  4. Add iteration to our template to loop through a list of data

Stuff you’ll need

A Spring Boot Application

I’ll be basing this post on modifying the project we completed in a previous post so either use git to clone that project down or complete the steps in that post to proceed.

IntelliJ Community Edition

You can download IntelliJ here for yourself, we only need the Community (free) Edition but if you happen to have the Ultimate Edition, that will work fine as well.

Let’s get to it!

The code for this blog post can be found on the ‘thymeleaf’ branch of my springBoot_StartingPoint project on GitHub. As mentioned above, the steps in this post are based directly on the basic app we built in the Suited & (Spring) Booted post but the general concepts are applicable to any Spring Boot application that is built with Maven.

1. Add the Thymeleaf dependency to our projects’ pom.xml file

Navigate to the pom.xml file of your project and add the thymeleaf dependency as shown in the screenshot below.


2. Alter our existing controller code to pass data into a template html file

Now that we’ve got all of the required dependencies, we can start modifying our existing code ready to pass data to a HTML file. The HTML file in question does not yet exist but we need to understand how our current code needs to work first before progressing on to that bit!

The first thing we need to do is open the class and make a few changes. The first change we need to make is to change the @RestController annotation above the class name, simply to @Controller. This will mean that our endpoint will no longer attempt to output literal values, but instead return a reference to a HTML file to render.  If this doesn’t make sense at the moment, don’t worry I’ll make sure I show and example of this in action at the end of the post, take my word on this just for now!

We also need to utilise a special type of object called a ‘Model’. This object will be used to contain any data (known as ‘attributes’) we want to send from our Java code to our front-end for rendering. Below is a screenshot of what I want your SampleController class to look like, make the alterations to your class accordingly and we’ll go through what this is doing exactly afterwards.


Now that you’ve gone through and edited your SampleController class accordingly you might already have an idea of how the Model object works but let’s make sure quickly.

As mentioned, the Model object is there to contain any bits and pieces you want your front-end HTML to display for you. To do this you can use the ‘.addAttribute(<reference>,<value>);’ method on your Model object, in the above example that translates to “model.addAttribute(“title”, “Home”);” for example.

You can also see that you’re able to add multiple attributes to a single Model object, so you can think of the Model object as a box that holds whatever your controller puts into it. This box can then be transported to a HTML file, where Thymeleaf can ‘unpack’ the attributes into the HTML template. To tell our controller where to send our Model object (‘where to transport our box of attributes’), we simply tell our method to return the name of the HTML file in which the Model object, and all of the attributes added to it, should be sent to.

You might be asking yourself, ‘but why is the Model object a parameter passed into the method rather than created inside the method?! and that is a great question, my simplistic answer is that you can consider each request providing its very own box for you to add attributes to then return back in the form of a response. So it’s like turning up at the supermarket with your very own shopping bag (Model object) and asking the kind shop assistant to go off and get you some bread and milk (your ‘request’), they get the bread and milk, then put it in the bag you provided (add it to your Model object), which is then handed back to you (their ‘response’). As a code example the above would look a little bit like this:


You’ll be glad to know that was the most complicated part to go over in this whole post, now that we understand how our newly modified controller works it’s all very straightforward from here on out!

3. Create a template html file to render content passed to it

In the previous step we altered our SampleController class to populate a Model object then return a String value of “index”. This string value directly relates to the name of a HTML file (without the .html extension), in our case the ‘index.html’ file. The first thing we need to do is create our very own index.html file in the correct place for Spring Boot to find it.


Under the src/main directory create a new folder called ‘resources’, then create a ‘templates’ directory under that, this is where your HTML files will call home. You’ll notice the resources file has a special icon, this shows that IntelliJ knows that this directory is a special area for resources to live in. To make this icon appear go to File -> Project Structure then click ‘Modules’ on the left hand side of the window.

From this point you need to use the central part of the window to navigate to the directory you want to flag to IntelliJ as a resources directory and click the ‘Resources’ button above the central window as shown below, then click OK when you’re done.


Now all we need to do is create a new HTML file inside the newly created resources/templates/ directory, right click the templates dir and click New -> HTML File, call it ‘index’ and press enter. You now have a HTML file with the same name as shown in the return statement of the controller we worked on earlier, it’s all coming together!

Open the newly created index.html file and firstly amend the meta tag with a closing ‘/’ as shown below. This just gets rid of an irritating error later on as for some reason IntelliJ forgets to add this in!


Now we’ve got that straightened out, proceed to edit your HTML file according to the screenshot below, we’ll go over each bit afterwards to make sure we’re clear on what each bit does.


If you’ve ever worked with HTML before, you’ll likely be wondering what these foreign ‘th:…‘ tags are all about, these are how thymeleaf renders content into the HTML template!

There are two main changes in that we’ve had to make, both using the ‘th:text’ notation. You’ll notice that in using this notation we use ${attribute_name} to access data passed into our HTML file. By now you should be able to put 2 and 2 together to figure out that these directly match the references we included when adding Java variables to the Model object earlier on. As a reminder, here is what we added in our SampleController earlier on, you can see that the first value of each attribute is referenced in the HTML, therefore we can imagine that the second value of each attribute is what will be returned to the user at runtime.


The best way to see all this in action is to run our application! Open up the Application class and click the green run button next to the main method then once your app has started up, navigate to http:localhost:8080/ in your browser to see your app using Thymeleaf in all of its glory as shown below!


At this point you might be be thinking ‘ok that’s great but you said we could use this template thing over and over?’, absolutely, let’s create another method in our controller to demonstrate this point. We’re just copying our original endpoint method for “/” and changing a few values, but still using the same HTML page so make sure you keep the return statement the same!


Now restart your app to use the additional ‘/hi’ endpoint added above and navigate to http://localhost:8080/hi to see the below output.


From our little experiment we’ve now proven that our one template HTML file can be used for different endpoints and purposes, great stuff! This is the aim of web template engines.

4. Add iteration to our template to loop through a list of data

Thymeleaf is much more advanced than just being able to pass text from Java to HTML, in their documentation they outline all of the possible functions you can use as well as providing loads of in-depth tutorials for you to play around with. For now I’d like to take you through one simple feature which I’ve found to be very useful, the ability to pass a list of items to a template and have Thymeleaf iterate over it.

In terms of a use case for iterating over a list of strings, I’ve used this to populate dropdown menus or bullet point lists on pages – as you can imagine it’s much more flexible to pass a list of options to a dropdown or list rather than have to edit to the HTML every time you add or remove options elsewhere!

Let’s pass a list of Strings from Java to Thymeleaf and make it render each item as an element (<li>) in a bullet-point list (<ul>). To do this, amend your SampleController class according to the below screenshot (including additional method to return a list of Strings).


You’ve likely noticed two things, firstly that we have a list of three Strings (Bacon, Eggs, Gofer) that we’re passing to our Thymeleaf template and secondly we’re only passing the list of strings to the “/” endpoint. Even though both of the endpoints use the same template. This is ok – if you decide not to provide variables that the template (i.e index.html) uses, it’ll just add null values, or as we’ll hopefully see in a while, it just won’t render that element of the page.

To visualise this, amend your index.html file to match the below and restart your application.


Here we’ve implemented the ‘th:each‘ statement, this simply translates to ‘do something for each element in a given list’. Thymeleaf will now busily create list items (<li>) in a bullet-point (unordered, <ul> list for each of the values that are contained in a given list referenced as ‘listOfStrings’. You should now be able to see why I think this is immensely useful, for one thing the contents of these lists (which could be dropdown menus or other listed items  in HTML) are dynamically managed according to a single ‘source of truth’ in your controller code, and secondly the HTML code itself is much cleaner, succinct and easier to read.

Running this in the browser will output as shown below. As you can see, both endpoints are still using the same HTML template, however only the “/” endpoint provides the list of Strings for the template to render so is therefore the only place which the bullet-point list will be shown.



That’s all for now

Well not quite, I promised to show you the difference in output of a @RestController over a @Controller annotated class so if you modify the annotation of your SampleController class accordingly to @RestController and re-run the application we will see the difference in the browser as shown below.







As you can see, the methods in the SampleController class now return the literal Strings “index”, rather than using these values as a reference to the HTML file you wish to utilise, so revert your code back to using the @Controller annotation and only use @RestController when you want to return raw data!

As always, if you have any questions, suggestions or corrections please feel free to comment below, any and all feedback is gratefully received! 🙂

Thanks for reading,



Dockerising Spring Boot – the easy way

Since my last post (Suited & (Spring) Booted) I’ve been playing around with my own pet project, trying to make it run in a Docker container so that I can quickly and easily deploy it whenever and (for the most part) wherever I like.

In this post I want to take you through the most simple and straightforward way I found of Dockerising a Spring Boot application, by modifying the app we made in the Suited & (Spring) Booted post. In fact this means of Dockerising an application is not just for Spring Boot applications, this is a general means of Dockerising any project that is built using Maven.

Note: Although I will be pointing out the steps involved in getting an app running in a docker container, this post won’t necessarily be a ‘beginners guide to docker’. If you are very new to docker and containers, it might be worth having a look at the official docs or Googling around for beginner-level tutorials to make sure you can get to grips with it.

What is Docker?

You may have heard of the term containerisation while googling ways to deploy your revolutionary new web application – this basically means that you intend to package absolutely everything your application needs into a single, independent, ‘container’.

In a nutshell, docker packages up everything the app needs to run independently, and enables you to deploy that as a single item onto an environment such as a web server, your own laptop, or wherever you might need it to run. It saves messing around setting up your deployment environments, which is especially useful if you want to deploy an application across many machines and don’t want to spend all week configuring each one ready for your app to run on!

To do this it goes through the following steps:

  1. Builds an ‘image’ of your application using a ‘Dockerfile’ to define the application’s environment needs
  2. Runs a ‘container’ representing your application based on the ‘image’ generated in the previous step
  3. (Optional) Pushes the image to a ‘docker image registry’ (imagine a ‘github’ sort of thing just for docker images) so it can be accessed by machines anywhere, not just locally/where the image was built
  4. Viola! That’s it.

Aside from step 3, I’ll highlight each of these steps as we go through this post and show you how they are accomplished. If you want to push your images to a remote docker registry (step 3), I would recommend getting to grips with creating an image locally and running it first, i.e. conquer the stuff in this post then google that bit (it’s dead easy).

What are we going to do?

  1. Add a new plugin to an existing Maven project in order for Maven to use Docker
  2. Create a Dockerfile for the application
  3. Build a Docker Image of our application
  4. Run a Docker container locally

Stuff you’ll need


Installation of docker is well documented on their official site so head over there and get yourself set up.

A Spring Boot Application

I’ll be basing this post on modifying the project we completed in the previous post so either use git to clone that project down or complete the previous post to proceed.

IntelliJ Community Edition

You can download IntelliJ here for yourself, we only need the Community (free) Edition but if you happen to have the Ultimate Edition, that will work fine as well.

Let’s get to it!

As mentioned, this will be based on the Spring Boot application we wrote in the previous post but this should work just fine for virtually any Spring Boot (Maven-based) project out there.

1. Add the docker-maven-plugin to the pom.xml

This step is pretty self-explanatory, below you can see how the build section of my pom.xml looks after adding the new docker-maven-plugin so make sure yours matches this!


Just to clarify, the ${project.x} tags relate to the <artifactId> etc tags that are specified by default at the top of the pom.xml when you create a maven project. the <dockerFileDir> tag specifies the location of your Dockerfile for this project, we’ll leave it pointing at the base directory of the project as in this example we’ll just create it there for simplicity.

In using this particular plugin, we also need to add an additional file to the root of our project called .maven-dockerignore as shown below. To the best of my knowledge, this prevents some form of ‘docker inception’ but I’m not 100% sure, all I know is, without this later stages will definitely fail so add it in now to save pain later. Don’t forget to add target/docker/ inside it. (Thanks to this awesome post for helping me solve this issue!).

Screen Shot 2017-10-15 at 11.49.48.png

2. Create a Dockerfile for the application

Now that we’ve updated Maven to enable the use of Docker we can get started on setting up Docker itself! The Dockerfile is the key component to defining what our application needs when it’s running, even including information such as the operating system it requires to run on!

Create a new file in the root directory of the project called ‘Dockerfile’, your project structure should now look similar to the below image.

Screen Shot 2017-10-15 at 11.33.22.png

Below is the information in which you can copy into your Dockerfile to get it to work, we’ll go over the main elements briefly after you’ve added it in.

Screen Shot 2017-10-15 at 11.36.42.png

These are the four main parts of the Dockerfile that we need to know about:

FROM – defines the OS that the application will run on. Alpine is the most lightweight Linux based operating system going so we’re using that to save making a needlessly bulky image. As you can see, this particular flavour of Alpine comes with the Java 8 JDK which is useful for us as we also need Java installed to run our Spring Boot application! You can search docker for available OS’s by typing docker search <searchterm> in terminal or by searching  the Docker Hub site.

ADD – this command will take a local file and bake it into the image you are building. In this example we are interested in taking the jar file of our application and storing it in the image simply named as app.jar. Without this step our application would never make its’ way onto the image that we’re generating! You can add whatever files you desire from your local machine onto an image.

ENV – sets any prerequisite environment variables that might be required during the running of the application.

ENTRYPOINT – think of this as “when I run the container, what should happen immediately?“, in our example we are stating that as soon as the container starts running it should use java to run the jar file that represents our application. A.k.a. run our application as soon as its container is fired up.

3. Build a Docker Image of our application

That’s pretty much all the hard work done. All we need to do now is run a Maven command in the terminal and we should be able to see a new docker image generated locally. In the terminal (at the project root) run ‘mvn clean install docker:build. This one-liner will re-download all dependencies for your project if required, compile your code, create the project jar file and then eventually build a docker image according to the Dockerfile which it can find at the location specified originally in the pom.xml! A lot of stuff going on for such a simple command!

Note: At first you might see an error similar to “[ERROR] DOCKER> Unable to pull ‘openjdk:8-jdk-alpine'” in the terminal, don’t panic, this just means that docker needs to get hold of a copy of Alpine OS so as we can build our image. Run docker pull openjdk:8-jdk-alpine in the terminal and you’ll be all set ready to run the previous command again with no issues!

Now in the same terminal window run docker images and you should see something similar to the below. Note that we have both the Alpine OS image downloaded locally as well as the image of our very own application.

Screen Shot 2017-10-15 at 12.02.52.png

4. Run a Docker container locally

Now that we have an ‘image’ of our application, all we need to do is run it! To do this from the terminal run docker run -d -p1234:8080 68b2546b4148. Let’s break that command down a bit:

docker run – pretty self-explanatory, this is the docker command to state that you are going to run a container based on a given image

-d – this states that you would like to run the container as a daemon process (i.e. in the background rather than rendering your terminal window useless while the container is running – try running without this flag and you’ll see what I mean!)

-p1234:8080 – defines the mapping between host port and container (application) port. The app that we built in the previous post we know runs on port 8080, what if there is something else using port 8080 on the machine we’re deploying the app to? In this case we would specify that anyone wanting to use the app would actually use port 1234, which would be routed to the correct port for our application, ahhhh crisis averted! When we access the app in just a moment, you’ll see this in action.

68b2546b4148 – the IMAGE ID that we saw when we ran docker images a moment ago, replace this number with the IMAGE ID of your application (not the Alpine OS image one) and that’s it!

If we now run docker ps which loosely translates to “what docker processes are running locally?”, we should see that our app is up and running in all its majesty as shown below. You can also see under the PORTS heading that any requests on our local machine to port 1234 are now being routed to port 8080 on our app, fantastic stuff!

Screen Shot 2017-10-15 at 12.18.00.png

So now, if we open up a new web browser window and navigate to ‘http:localhost:1234’ we should see our amazing application working in all of its glory.

Screen Shot 2017-10-15 at 12.20.34.png

That’s all for now

And that is it! There’s really nothing more to it unless you want to work on automating the steps shown above into a shell script. For an example of this you can check out the script I wrote for my little pet project which handles all of the above with an incredibly satisfying level of automation 🙂

As always, if you have any questions, suggestions or corrections please feel free to comment below, any and all feedback is gratefully received! 🙂

Thanks for reading,


Suited & (Spring) Booted

Since my last post (Getting Started with Spring) I’ve been able to learn a little more about Spring in general, but the most notable part of Spring that I’ve begun experimenting with is Spring Boot.

What is Spring Boot?

Spring Boot provides an efficient means of creating web applications as all-in-one, ready-to-run standalone apps. It does this by bundling all of the required elements together in a single application, it even includes a built-in server for you (such as Tomcat). This makes your applications much less reliant on the servers that you want to run them on while also making the process of developing your applications much more simple. Spring’s official website explains the concepts of Spring Boot in much more detail, so for the most part I’ll leave you to dive in to the nitty gritty over on their site in your own time. For now, just know that Spring Boot is designed as a way to build standalone  webapps that you can get up and running quickly and easily. In this post I’ll briefly go through the main steps of creating a simple Spring Boot application. Stick with me and by the end of this post you’ll see how simple it is to build and run your very own Spring Boot applications.

What are we going to do?

  1. Create a new Maven project
  2. Write a basic Spring Boot application
  3. Run the Spring Boot application!

Stuff you’ll need

IntelliJ Community Edition

If you’ve been reading any of my posts to date, you’ll know by now that I am a massive fan of this IDE for coding of any kind, Spring is no exception! You can download IntelliJ here for yourself, we only need the Community (free) Edition but if you happen to have the Ultimate Edition, that will work fine as well.


Head to the Oracle website to download the latest version of Java for your machine as we’ll need this installed to compile and  run our Java code!

Let’s get to it!

For this post I am going to use the official Spring Boot Quickstart guide as this is the simplest means of getting up and running. While we go through the quickstart guide, I’ll show you how I refactored the official quickstart guides’ example to improve my own understanding. Hopefully this will not only help you with your understanding of how the individual elements of a Spring Boot app fit together, but will also result in you having an easy to understand template Spring Boot app that you can use for your own projects!

1. Create a new Maven project

Open IntelliJ and choose File -> New -> Project… then select the option for Maven from the list on the left hand side (it should be about halfway down).

Leave the Create from archetype option un-ticked and click next.

Give it a GroupId e.g. com.mark.springbootblog. This option isn’t too important, it’s mainly important only for enterprise-level project where you’d need to define the domain or team your app will fall under such as com.marksCompany.financeWebApp.

ArtifactID is the name you want to assign to your app type in something like springbooted and click next. In the following screen the Project Name will likely autopopulate with the ArtifactID you gave your project so just check it is set and that you’re happy with the location of where your project will be stored and then click Finish.

You should now be presented with a screen similar to the below.


2. Write a basic Spring Boot application

As mentioned, we’ll be using the official Spring Boot Quickstart guide so I’ll try not to repeat too much information, however I am aiming to walk you through the steps required to get there with the assumption that you’ve never used Maven or Spring Boot before just to prove that anyone, regardless of experience can create Spring Boot applications!

The quickstart guide provided by Spring is so simple that aside from creating a package and a new class, less than 20 lines of code and a few dependencies need to be added to a basic Maven project in order to get your first Spring Boot application up and running! However, in fiddling with Spring Boot a little bit, I’ve refactored their example into something that helped my personal understanding of how it all works a little bit better, so stick with me and hopefully my little walkthrough will help you out as well.

Hopefully you were able to create your basic Maven project successfully in the step above, if not go back and try again! If so, we need to a few things into the main project file (the pom file) before we dig into the actual code. So open up the pom.xml  file and add the parent section and a new dependency as shown in the image below.


Now that we have the required dependencies in place (e.g. org.springframework.boot – enables you the usage of spring boot libraries and features, simple right?), we can start writing code for our Spring Boot app.

Following along with Spring’s quickstart guide still, create a package (right click -> new -> package) under the src/main/java directory called ‘hello’, the structure of your project should now look similar to the image shown below.blog3

From this point on I’m going to start deviating from the official documentation. The changes in my version of the application are simply to separate elements of the application into their dedicated classes. This should make it more readable  and very straightforward to add your own code into if you wish later on.

Inside our new ‘hello’ package we’re going to create only two files (Java classes), the first one will contain the controllers and logic to handle requests received by our application, the second will be there to start (or ‘bootstrap’) our application.


You can create these new classes now and add the code to them in the next couple of steps to make life easier (right-click the hello package -> new ->Java Class). Once created,  your project structure should look similar to the image on the right. Don’t worry if the icon next to the class name looks different (see Application), this will change once all the code has been added into each of the classes we’ve just created.


This class will be relatively similar to the one provided in the Spring’s Official Quickstart guide however it has a bit of code taken out of it. My version of this class is shown below.


The main difference in my version is that I have moved the main (‘public static void main’ ) method out of this class. Much like any other Java program in the world, Spring Boot associates this method as the main entrypoint of the application. Therefore it made sense to me to move it away from the actual inner workings of the application, this made it a little easier to read and if this were to be used as a starting point for a potentially much bigger project, it will now already slightly refactored and ready to add new functionality in with relative ease.

The SampleController class now only focuses on one job, handling requests and executing the required logic. Simple!

Aside from that, there are some annotation differences (the yellow bits starting with ‘@’) on the ‘home’ method. This is for simplicity and understanding more than anything, now the method reads very simply as:

‘if we receive a HTTP request to the endpoint “/”, e.g. http://localhost:8080/, then return a response containing the String “Hello World!”‘


So, now for the main entrypoint of the application, the mythical ‘public static void main’ method, known and loved (probably) by Java developers around the world. This is a very simple class as shown in the image below. (Ignore most of the icons next to the line numbers, the only icon of significance is the green ‘play’ button looking one on lines 7 and 9).


Most of this class is fairly self-explanatory. As mentioned above this is the main entrypoint of a Spring Boot application so the annotation above the class name ‘@SpringBootApplication’ is self-explanatory. The ‘main’ method within this class uses…). And that’s all there really is to it, the application will now be able to bootstrap itself ready for use whenever you need it to.

3. Run the Spring Boot application!

This is even easier than any of the previous steps, open up the class and click on either of the green arrows on line 7 or 9. The run window at the bottom of the IDE should come to life with the Spring logo and eventually tell you that the application is running as shown below. If it fails to start, open the terminal tab at the bottom of the screen in the IDE and type ‘mvn clean compile’ and try to run it again.


The output shown above tells us a few things about our app, most notably:

  • “Tomcat initialized with port(s): 8080 (http)” – Spring Boot works as a self-contained application as it supplies its own server so need for a separate Tomcat server to deploy to!
  • “Mapped “{[/]}” onto public java.lang.String hello.SampleController.home()” – Spring ( has found the @RequestMapping annotation for the controller which we defined in the class so any requests to “/” should be handled appropriately without error (unless there’s a logic issue)
  • “Tomcat started on port(s): 8080 (http)” – great, now we know that the application is running locally on port 8080, so we should be able to check this easily in our browser by navigating to http://localhost:8080/
  • “Started Application in 2.495 seconds (JVM running for 2.887)” – Spring is happy that the application is running 🙂

Now if we navigate to http://localhost:8080/ we should see the following. Even though it doesn’t show the “/” on the end of “localhost:8080” the mapping for a slash on its own essentially means ‘home’ so this is normal. You can play around with mappings by changing the value in the @RequestMapping annotation e.g. change it to @RequestMapping(“/an_endpoint_woz_ere”) and you’ll need to navigate to http://localhost:8080/an_endpoint_woz_ere to see the “Hello World!” message instead.


That’s all for now

So although that was a simple app, you should now understand how to create a very basic standalone Spring Boot application, in addition to this you should also be able to work out how to add new endpoints (add more methods with “@RequestMapping()” annotations into the SampleController class) and also how to run your application. If you got stuck while following along with this post or would like to download my source code for it, I’ve uploaded it publicly on GitHub so please feel free to clone it down and play around with it.

From this point on it’s just a matter of playing around with the code, checking out new annotations and seeing what you can do with your new found love of Spring Boot! For a bit of inspiration, I’ve created a public repository of my own Spring Boot application that anyone is welcome to check out here on my GitHub repository. Based on what I learn from experimenting with Spring and Spring Boot in this hobby application I should be able to write some more blog posts in the future as my little project progresses.

As always, if you have any questions, suggestions or corrections please feel free to comment below, any and all feedback is gratefully received! 🙂

Thanks for reading,


Getting Started with Spring

Note: I’ve now (Sep 2017) added an extra step ‘3. b)’ to cover running Spring apps using IntelliJ Community Edition, so it is now possible to follow along without needing IntelliJ Ultimate Edition 🙂

In the last couple of weeks I’ve moved into a new team at work – the people are great, the office is amazing, life is wonderful. However, joining a new team means learning how they work and learning the technology they use, in this case I’m facing down the Spring Framework.

In the past I’ve worked with the Play! Framework to create and deploy a webapp, choosing it more or less entirely due to its simplicity and close knit relationship with plain old Java. This isn’t to say that Spring isn’t closely knit with Java, just that learning a billion annotations and figuring out how Java Beans worked seemed quite a daunting task at the time, as opposed to being able to to get straight into Java code in a fully-featured (perhaps a little bloated, in retrospect) framework. In essence, I was being lazy and doing my best to dodge having to learn a ton of new stuff before developing anything meaningful. Lesson learnt!

Anyways, karma has come right back around on me and here I am, now attempting to get up to speed with Spring as soon as my little brain can manage!

The purpose of this post is to share a brief ‘getting started’ guide. This isn’t here to explain all of the intricate steps in detail, this will come when I know these steps intimately myself, this guide is here to get anyone from a blank Maven project in IntelliJ to a very basic web application hosted on a local Tomcat server. Any code I’ve used is available on my GitHub repo for anyone to clone/download and play around with.

FYI – this guide is based on me using a Windows 10 PC, so some steps will be slightly different (read: ‘easier’, ‘less painful’ etc.) if using a Mac.

What is Spring?

As a one-liner – ‘Spring is a framework for developing applications or services that can be accessed/used through the web (via http)’. Basically, it lets you write applications (in Java) that can be deployed and then accessed by users through their web browser of choice (Chrome, Firefox, Safari etc.) by navigating to a URL e.g.

The main benefit of Spring is that it is designed to be modular. You start with the core functionality (Spring Boot) and from there you can choose to extend that by installing additional Spring modules. For instance, if you wanted to hook your application up to a database, you can use the Spring Data module, or if you want to account for security concerns you could apply the Spring Security module, or what if you wanted to develop your app towards Android users, there’s the Spring For Android module! There are loads of different modules to fit most needs, these are all described on the Spring projects website.

The inherent modularity of Spring means that you don’t need to start with a monolithic project and then strip away what you don’t need, it means that you can start with a simple, understandable base and build up gradually according to your needs. The obvious downside to this if you are a beginner (like me), is that implementing additional modules may require a bit of a learning curve, but I’ll find out as I use it more in future posts!

What is Tomcat and how do we use it with Spring?

Tomcat is a ‘web server’ technology, this means that installing and running it on a machine (be it your laptop, or a server in the cloud etc.) will enable you to ‘serve’ content or applications to other machines (clients) in your network, or over the internet if you host your Tomcat machine publicly. If you’re new to the idea of client-server architecture, have a look at this quick (~2 min) video to get an idea of how a server (machine with Tomcat installed, for example) can provide content, data or services to clients (other machines out there able to connect to the server) through the use of requests and responses.

Just to give a quick example of client-server interaction (request-response); by typing into your browser you are issuing a http request to the UK Google URL, Google will issue a response in the form of a webpage (HTML/CSS/JavaScript content) hosted from its server(s). If you typed in instead, you’ll notice that it causes a 404 error, this is still a valid response from Google, all it’s saying is that it doesn’t understand your request (it can understand and provide content for, but does not have anything it can serve you for aside from an error code). But what if you mistyped the url of Google? Say you typed in instead, you’ll notice that nothing is served back to you, not even a custom error message like the 404 we saw a minute ago, from Google or anyone, because there isn’t (at the time of writing) a web server in the world that is setup to handle requests and provide responses for that URL. Simple!

In our case, we are going to install Tomcat on our PC and rather than sending requests to our Tomcat server externally, we can use a special ‘localhost’ URL which will allow us to write a Spring web application, host it (serve it from) our local Tomcat server installed on our machine, then access it using a URL of http://localhost:8080. This just means “send a http request to a local server on port 8080 (Tomcat’s default port)”.

What are we going to do?

  1. Create a new Maven project
  2. Download Apache Tomcat 8 to deploy our application to later on
  3. Set up a run configuration in IntelliJ to run our project on a local Tomcat server
  4. Write a basic SpringMVC (Spring 4) application
  5. Deploy and run your webapp!

Stuff you’ll need

IntelliJ Ultimate or Community Edition

If you haven’t already got hold of a free copy of IntelliJ Community Edition, I would highly recommend it. For general coding, in my opinion, it is THE BEST integrated development environment (IDE) for Java, Scala or pretty much anything else it supports!

In this guide we can use either the Ultimate Edition or the Community (free) Edition, if you’re a student you’ll likely be able to get the Ultimate edition for free using your institution’s details here. Step 3 (Setting up Run Configurations) has now been split into part a, and b, to set up a run configuration in either Ultimate or Community Editions’ respectfully. If you’re using Ultimate Edition you can use either of the two methods, however Community Edition will only allow you to use the latter of the two steps.

Apache Tomcat 8

It’s all good and well writing a Spring application, but we need some way of ‘hosting’ it from our machine so we that it can be accessed using a web browser (Chrome, Firefox, Safari etc.) to see it working as a live application! We’ll install and set it up for sue with IntelliJ after we run it manually to test it. We’ll set this up a step in the guide so that you can see the process of going from nothing at all on your machine, to deploying a Spring webapp to your very own local Tomcat server as a matter of easy steps.

Java 1.8

In this guide we’ll be using Tomcat 8 which relies on Java 7 or upwards being installed on your machine. I’d recommend using Java 8 straight away anyway though just to stay a little bit more up to date and allow you to take advantage of features such as Java Streams later on in development if you take your Spring project further.

Head to the Oracle website to download Java for your machine.

Let’s get to it!

A lot of the steps in this guide have been taken from a fantastic YouTube video by LynAs Sazzad, have a look at his video to get up and running quickly! As he moves quite fast through the steps in his video (a lot of pausing and going back was required!) and as he already had Tomcat set up to run his application, I’ve decided to write out some of the required steps but for the most part I’ll point you at his video to set up the code you need.

1. Create a new Maven project

Open IntelliJ and choose File -> New -> Project… then select the option for Maven from the list on the left hand side (it should be about halfway down).

Leave the Create from archetype option un-ticked and click next.

Give it a GroupId e.g. com.myTestProject. This option isn’t too important, it’s mainly important only for enterprise-level project where you’d need to define the domain or team your app will fall under such as com.marksCompany.financeWebApp.

ArtifactID is the name you want to assign to your app type in something like springMVCTest and click next. In the following screen the Project Name will likely autopopulate with the ArtifactID you gave your project so just check it is set and that you’re happy with the location of where your project will be stored and then click Finish.

2. Download Apache Tomcat 8 to deploy our application to later on

On my hunt to find a nice easy way of understanding how to install Tomcat on Windows 10, I found this awesome guide. It is a lengthy read but if you want to get to grips with webapps and understanding Tomcat, this covers everything you’ll likely need to know, conveniently enough it’s also got a nice section of downloading and running Tomcat. Below I’ve summarised the steps to downloading Tomcat and testing it by running it on your machine manually.

To download Tomcat for Windows, the easiest way I found was to download a zip file from Tomcat’s official website. At the time of writing, under the 8.5.14 heading there is a section called ‘Binary Distributions’ and in there is an option to download the ‘Core’.zip file (see red box below).


When it had finished downloading, I moved the downloaded .zip file into a new folder called H://Tomcat/Tomcat8/ on the hard drive of my computer and unzipped it there (right click .zip file -> Extract Here). This is just to give it a permanent home on my machine so any of my run configurations that I might put together later on have a definitive location in which to find and use Tomcat from.

As mentioned at the start. we need at least Java 1.7 (Java 7) installed on the machine running Tomcat 8 in order for it to work. Additionally we need to set up an environment variable called JAVA_HOME to point anything on our machine to its location. Hopefully, you’ve already downloaded Java through the Oracle website as explained at the beginning, if so follow the very last few instructions under the heading ‘to install the JDK Software and set JAVA_HOME on a Windows System’ on this site.

Now we are able to test that our downloaded version of Tomcat works, to do this click into the newly unzipped Tomcat file and go into the /bin directory. In here hold down shift and right click a blank are of the window to view the option to ‘Open command window here’, click this to enter command prompt. The only thing you need to do now is type ‘startup’ (without quotes) and press enter, this should open up another little command window, the whole thing should look similar to the output shown below.

Note: the equivalent command in Linux/Mac is ‘./ run’


Great, so in this new little window it’s telling you that Tomcat is running and that it’s listening on port 8080, so how do we access this? As we mentioned earlier on, we need to send it a request, as Tomcat is a web server, this therefore needs to be via http, so let’s open a web browser such as Chrome and navigate to http://localhost:8080. The result should look similar to the screenshot shown below.


This is Tomcat’s default page to serve to any requests, all this means is that we’ve not told Tomcat to serve anything other than this in response to any requests it receives, simple!

I don’t want to go too far into Tomcat stuff in this guide but I do want to quickly show you how to host your own content from this server manually before moving on. To do this I have created a very simple HTML file called index.html and stored this within a folder called marksApp in Tomcat’s webapps folder (see below).


You should now be able to go to localhost:8080/marksApp (in my example) and take in the awesome beauty of my website.

marskapp.JPGNow that we’re happy that we have a working Tomcat installation, we just need to set up IntelliJ to use it and write the webapp to be served from it!

3. a) Set up a Tomcat run configuration in IntelliJ Ultimate Edition

In this step we’re simply telling IntelliJ how we would like it to run a program, in this case we’ll be writing a bunch of code that we’d like to run on a Tomcat server locally, so we’ll tell it just that by defining a ‘run configuration’ – a way of setting a particular way to run something.

To do this, from the top menu bar in IntelliJ choose Run -> Edit Configurations. In the


Click the little green ‘+’ in the top left of the window that opens (see screenshot on the right).

You might get an option to choose Tomcat Server as shown in the image to the right, if not, click the option at the bottom titled ‘x items more (irrelevant)…’ and scroll down to find the Tomcat Server option. Once you’v found this click it to choose the Local or Remote options, we want to serve our app from a local Tomcat server so click ‘Local’ as shown below.runconf2.png

A new run configuration has now been created, you just needintellijtomcatlocalserversetup.JPG to edit it to your needs.

Firstly, set the Name field to something meaningful like SpringTomcat, now click the ‘Configure…’ button in the Application server section to bring up a small window (see screenshot to the right).

Clicking the ‘…’ therunconf2.png the right of the Tomcat Home box will allow you to tell IntelliJ where your Tomcat installation lives. Simply put, navigate to the unzipped version of Tomcat that you downloaded earlier, and click OK as shown on the left. You should now be presented with the original small window without the error icons and with some details of your Tomcat installation, click OK.


The final thing we need to do is address the warning at the bottom of the run configuration, click the Fix button and choose the option suffixed with ‘exploded’ then click Apply and OK to finalise the run configuration.

3. b) Set up a Maven run configuration in IntelliJ Community Edition

In the more likely event that you’re following along using IntelliJ Community Edition, here is how you can easily set up a Maven run configuration to run your Spring applications. In this section I will be using the Tomcat7 plugin for Maven (rather than Tomcat8 as used previously in this guide). For the purposes of this guide the version of Tomcat being used isn’t important though.

Add the following plugin to your pom.xml.

Screen Shot 2017-09-16 at 16.23.24.png

From the Run menu, select ‘Edit Configurations…’


The Run Configuration window will now pop up – click the grey ‘+’ icon in the top left of this window and choose the Maven option.


Enter a name for your new run configuration and add ‘tomcat7:run’ in the Command Line box. Now click Apply and then OK to exit the window. This may require you to download and install Tomcat


All you need to do now is choose your new run configuration from the Run menu!


If your application fails to start, make sure that no other applications are running on the same port as the current application you’re trying to run. Most tutorials use the default port of 8080 so if this is the case, just stop any other apps you might be working on and try again. Other common issues relate to either the contents of your WEB-INF folder, or the dependencies in your pom.xml, so be sure to check them and Google any specific errors that come up.

4. Write a basic SpringMVC application

For this section I will point you directly at LynAs Sazzad‘s fantastic video for instructions on setting up all of the Spring code and dependencies in the pom.xml file. If you get stuck at any point or are having difficulty getting it working, my code is up on GitHub so feel free to use it for comparison or as a starting point for your own app!

The reason I’ve followed this tutorial specifically is that it uses Spring version 4, the latest release. Older versions of Spring use different annotations and also rely on .xml files for configuration of Beans etc. So this is all in aid of using the most up-to-date (at time of writing) version of Spring which uses Java instead of xml to work with Beans and in my opinion uses better structured annotations.

5. Deploy and run your webapp!

Once you have completed all of the above steps you can now use your run configuration to deploy your Spring webapp to your local Tomcat server and access it through the browser!runapp.PNG

At the top of the window in IntelliJ you’ll notice a Run Configuration dropdown with a green ‘play/run’ button next to it, make sure your new run configuration is selected and click the green run button.

The run console at the bottom of the screen will start churning out all sorts of messages, a lot of them will be in red text but are only ‘info’ messages rather than errors! When it’s finished deploying your app to the local Tomcat server it will show you the ‘deployed successfully’ message (see white lines of text in screenshot below) and will open up your application automatically in a web browser window, if it doesn’t just navigate to http://localhost:8080/ in your browser to view it.


That’s all for now

That’s it! You’ve successfully set up a local Tomcat server, written a Spring application and deployed it to your server to be accessible by clients on your network (localhost)! In addition to this guide, I intend to write a sequel showing you how to deploy your application to a remote Tomcat server so it can be accessed by anyone on the internet. But for now that’s pretty good going 🙂

Also, as I start to learn more than just the absolute basics I’ll figure out what I can write about coherently and add that up on there as well!

If you have any questions or comments please as always feel free to message me or put them in the comments section below 🙂

Thanks for reading,


Programming the Parrot AR 2.0 Drone – Beginners Guide 2

In the previous guide we used NodeJS and some basic JavaScript to control the drone, however this is all a bit static – what if we want to control the drone in real-time during flight, rather than having to pre-define a route for it to fly? Or what if we want to view a live feed from the drone? This is where WebFlight comes in. WebFlight is a superb open-source project created by Laurent Eschenauer that can be downloaded/cloned for free from Laurent’s GitHub repository.

What are we going to do?

  1. Go over thenewboston tutorial on installing Git bash
  2. Download (Clone) WebFlight and install required components
  3. Configure WebFlight
  4. Download and install a program to render the feed from the drone’s camera as a live stream in our web browser (FFMPEG)
  5. Start flying our drone in real time using our laptop/PC keyboard!

Stuff you’ll need

Same as last time (mostly)

In this guide you’ll need exactly the same bits and pieces as in the previous guide  (Win10 laptop/PC with Wi-Fi, drone, Notepad++). You’ll also need to have completed the previous guide to ensure you have NodeJS installed as well.

Aside from that we also need an application called Git installed. We will need to use ‘Git Bash’ in order to get all the bits and pieces we need set up.


Git is a piece of software that falls under the bracket of Version Control Software (VCS). Git’s job is to make sure files are up to date as well as keeping a history of the different versions of files up to the current point, just in case you need to revert to an older version.

Going into detail about Git and its uses is a little out of the scope of this guide, but you absolutely need Git installed on your laptop/PC to get WebFlight installed correctly. Bucky Roberts over at has put together a great series of easy to understand video tutorials on getting up and running with Git so I would recommend you go through at least the first tutorial on installing Git before continuing. The tutorials after the first one are great if you have a GitHub account and want to understand a bit more about Git and its uses. For the sake of this guide, we only need Git to do some very basic stuff so it’s not totally necessary to know loads about it.

Also, have a look around the tutorials on, there are absolutely loads of really well put together and clearly explained tutorials on programming. It’s an absolute goldmine of programming knowledge!

Let’s get to it!

1. Go over’s tutorial on installing Git Bash

Make sure you’re familiar with Git (Git Bash) before going any further; this will ensure that you can get everything set up ready to use WebFlight! Head over to thenewboston’s Git tutorials here .

2. Download (Clone) WebFlight and install required components

Scrolling down a bit on the WebFlight GitHub page you’ll see the below instructions for installation. The yellow highlighted line has been added by me as I found that bower wasn’t recognised by the computer without this (bower install will fail, unknown command).

If you still have your ‘Drone’ folder from the previous guide and you have Git Bash installed, open the Drone folder and right click an empty area in the folder, now choose ‘Git Bash Here’ to open the Git Bash command window. Now run the below commands in the Git Bash window one at a time.


What we are doing by entering these commands is explained below:

  1. “git clone…”  “Grab me my very own copy of some software stored on GitHub”
  2. “cd ardrone-webflight” – change from the current directory into the (newly cloned) ardrone-webflight directory (cd = change directory, cd )
  3. “npm install” – get the Node Package Manager to auto-detect any dependencies within the current directory and install them
  4. “npm install bower -g” – , Bower is another package manager (handles any required packages that NPM doesn’t look after) so needs to be installed seperately and given global (-g) access so you can run it from anywhere in the system
  5. “bower install” – now Bower is installed we can get it to auto-detect any dependencies within the current directory (ardrone-webflight) and install them.

Above I mentioned ‘dependencies’ a couple of times. As I described in the previous guide dependecies can be though of as tools to complete a job. In the last guide we used the command ‘require(‘ar-drone’); this is saying that in order to complete some or all of the commands in the program, it requires (or depends on) the ar-drone library being installed. As programs get bigger and bigger, they may likely use many dependencies, hence the need for dependency managers and the ability for them to automatically detect any required dependencies and get them installed ready for you. Imagine if you had a program with 50 dependencies, it would take a loooooong time to type ‘npm install abc’ 50 times manually!

The three screenshots below demonstrate the process of installing everything, and installing bower using NPM, using the –g tag to set a global path variable to it as well (this just means that you can run the command ‘bower’ anywhere and it’ll be recognised, rather than having to run it from the directory it lives in).

Clone the WebFlight repo from GitHub, then using npm install:


At first your computer will not understand what bower ‘is’


Use NPMto install bower and use the -g tag to set it to the computers’ global path, bower is now recognised and you can run bower install


Random error I ran into

When testing the installation of WebFlight a second time for this guide, I ran into an error when running the bower install command (last line). Unfortunately I closed the window before I thought about screenshotting it so I apologise for that. However, part of it included “exit code #128 fatal” so if you see that at all, it’s the same error.

While I was googling the error and trying to figure out how to fix it, the gremlin in the system causing this issue magically disappeared and I was able to run the bower install command without any errors at all. I literally did nothing to my PC, nadda, it just started working all of a sudden!

3. Configure WebFlight

Now that everything is installed we need to make sure that Webflight is configured as we like it. To get a basic level of operation running we won’t need to do much so we’ll do the bare minimum for now to get up and running.

If you navigate to the ardrone-webflight folder that you recently cloned from GitHub, you’ll find a file called config.js.EXAMPLE – simply put, this is the configuration file that tells Webflight which plugins to use etc. For now, rename the file to config.js (remove the ‘.EXAMPLE’ bit at the end), this will make sure that this file is recognised as the correct file for Webflight to use.

Aside from config.js, there is one other file in the same directory that is very important, that being app.js. App.js is the main, central JavaScript program for controlling the drone. This file includes links to the config.js file (hence why renaming this a minute ago was important!) as well as bindings from the keyboard to the basic drone controls etc. There’s no need to edit this right now, that’s the basic configuration done!

If you now open a command prompt window in the ardrone-webflight directory and type ‘node app.js’ you will initialise the WebFlight application! At the moment you will see a couple of errors pop up under the ‘node app.js’ command to do with something called ‘ffmpeg’ not being installed, for now don’t worry about that, simply open up your web browser and type  localhost:3000 in the URL bar at the top – press enter and you should see the following.


You’ll notice that your drone is (probably) not pointed at a nice view of clouds, this is a stock image. The reason it displays this stock image is due to FFMPEG not being installed, this is the program used to render any images and videos from the drone to a format our browser can understand and output, so until we get that set up we’re stuck staring at the stock image!

Saying that though, it’s not all bad! We’ve got some nice HUD (Heads Up Display) elements including a compass along the bottom of the screen and some subtle instruments in the centre of the screen so we must be doing something right!

4. Download and configure FFMPEG

This section is a bit fiddly so take your time and go through it carefully!

In the previous guide I took you through how to find out if your PC/laptop is 32 or 64-bit, the same rules apply to downloading FFMPEG. If you get stuck, go back to section 2 of the previous guide for a reminder. You can download FFMPEG here.

When the download has finished, navigate to your Downloads folder and copy your new FFMPEG ZIP file (notice it has ‘.zip’ after the file name) from the Downloads folder, into the ardrone-webflight folder, inside the Drone folder (Drone\ardrone-webflight\). As the folder is a zip file, we need to ‘extract’ it to use the contents of it. You can do this by right-clicking the zip file and then selecting ‘extract here’. Rename the extracted folder to ‘ffmpeg’ for easier referencing later on.

I found FFMPEG to be a bit of a pain to install overall, however after Googling around a bit I found this guide which helped me eventually. If you run into issues installing FFMPEG, I would recommend having a look at the guide linked above, or Googling any specific errors you run into.

Within the ffmpeg folder you’ll find another folder called ‘bin’, enter this folder and copy the location of this. To do this, click on the address bar (the bit that says ‘Drone -> ardrone-webflight > ffmpeg > bin’ in the image below) and copy the whole path that shows up. See the two images below, first image is before the address bar is clicked on my computer, second image shows it when it is clicked. In my example below, I copied all of the path highlighted in blue, you need to copy the whole path shown on yours as well.



Now we need to edit the environment variables for your computer so you can use ffmpeg from anywhere. It would make sense that you could use the –g tag like we did earlier for bower, but I haven’t figured out why that doesn’t work in this case so I’m just putting it down to FFMPEG being awkward and doing it the good old fashioned wcortana.pngay.

In Windows 10 all you need to do is start typing ‘env’ in the ‘Ask me anything’ search bar in the bottom left of your screen (Cortana I think it’s called?), you should see an option to edit the system environment variables as shown in the screenshot to the right, click this.

The next bit is a little more fiddly so I’ve included three windows in one image to try to explain the process as clearly as possible!

You should now be presented with the top left window shown in the screenshot below, click the Environment Variables… button to be taken to open the top right window from the screenshot below. Click on the Path item (PATH, path – whichever way it’s shown on your computer), then click on the Edit button to reach the window shown at the bottom of the screenshot below. Click New and then paste in the path you copied earlier from the ffmpeg/bin folder.


Now if we close any command prompt windows and reopen them, typing ‘ffmpeg –version’ you should see an output similar to below, if so, FFMPEG is installed and ready to be used with WebFlight!


If you now navigate back to your ardrone-webflight folder and run ‘node app.js’ in command line, you should notice that the FFMPEG errors have gone and if you open ‘localhost:3000’ in your browser you are receiving a feed live from your drone! Below is my feed while writing this guide, the drone is currently looking out of the window enjoying a view of perfect English summer weather.


5. Controlling the drone using the keyboard

Seeing the live feed from your drone’s camera is all good and well but what about flying it? As long as your drone has at least 20% battery life (see top left of WebFlight display in your browser), you can press ‘T’ on your keyboard to take off and ‘L’ to land!

However you might notice that other commands seem to be missing. The up and down arrows seem to make drone go up and down, but what about forwards and backwards? By default the config.js file is set to use a different keyboard layout from QWERTY (UK/US layout) so we just need to change one line in there first.

Open the config.js file, you’ll notice on line 13 there is a keyboard variable set to ‘azerty’, simply change this to ‘qwerty’ to use WebFlight with a standard UK/US keyboard layout. Save and exit the file and restart WebFlight for the changes to take effect (close browser window/tab running WebFlight and use ctrl+c to stop it in the command prompt window – then re-run node app.js in command prompt and reopen localhost:3000 in your browser).


Once you’ve reconfigured Webflight in the config.js file, start Webflight up again with ‘node app.js’ (make sure you’ve closed down all other windows running Webflight first). You’ll notice that you can run the following commands in the browser window:

  • W – Forward (pitch)
  • A – Left (roll)
  • S – Backward (pitch)
  • D – Right (roll)
  • Up – Increase height
  • Down – Decrease height
  • Left – Rotate left (yaw)
  • Right – Rotate right (yaw)
  • F – Flip (make sure you’ve got lots of room around the drone!)

That’s all for now

With any luck you now have a drone flying around according to your controls, as well as a feed from the drones’ camera in the web browser (localhost:3000)! Check out Laurent Eschenauer’s WebFlight repository on GitHub for more controls, plugins etc. As always, if you ran into any issues getting up and running with WebFlight please feel free to comment below and we’ll look into it together, alternatively head over to the WebFlight repository linked above and click the ‘issues’ tab to search any issues/fixes other users ran into!

In the next guide we’ll look into installing and some additional plugins for Webflight to extend its functionality even further!

Thanks for reading,


Programming the Parrot AR 2.0 Drone – Beginners Guide 1

Welcome to my first beginners guide on programming and flying the Parrot AR 2.0 drone! The guides I’ll be writing are based on my own experience of learning and working with the AR 2.0 drone. The aim is to write these in a way that I would’ve found useful and easily understandable when I was getting started.

Although there are other great resources out there such as this Instructables guide and this video, I wanted to write a guide for absolute beginners – explaining as much as possible as I go along. This way there is absolutely no expectation to have any prior understanding of programming or working with technology. I hope to assume as little knowledge as possible so please feel free to comment on this post if you have any questions or issues while following along.

What are we going to do?

In this guide we are going to achieve the following:

  1. Create a folder on the Desktop to work in
  2. Install an application that will allow us to send and receive information to and from our drone (NodeJS)
  3. Connect to the drone using Wi-Fi
  4. Use NodeJS to tell the drone to take off and land from our laptop/PC
  5. Write some simple JavaScript programs to save us typing lots of commands each time we want to fly the drone
  6. Add some more functionality into our JavaScript programs and understanding the use of these to control the movement of the drone

In writing this guide, I’ve used my experience of going through a fantastic guide from the Instructables website. This contains many of the commands that we’ll use, however I’ve tailored this guide to fill in any gaps in understanding that I came across, as well as explaining a little bit about the technologies we’ll need to use along the way.

Stuff you’ll need

Before we get into anything, these are the things you’ll need to get going with this guide.

1. Windows 10 PC/laptop with Wi-Fi

For these tutorials, I am using a Windows 10 PC with a USB Wi-Fi adapter to connect to the drone, if you don’t have Wi-Fi capability on your PC, something like this USB Wi-Fi adapter should solve that for you.

If you have a Windows 10 laptop, you should be all set (built-in Wi-Fi) 🙂

Windows: Other versions of Windows should be fine, I originally got this all working on a Windows 7 laptop so that should be fine, Windows 8 (and 8.1) are notoriously awkward operating systems however so there may be a need to Google some bits and pieces if you run into issues. Feel free to comment on this post with any issues as well though and we’ll try to work through them.

Linux/Mac: At the moment I’m looking into getting a MacBook of my own so one day I should be able to try this all out on Mac and write a guide on that if needed. Might as well wait to do Linux until that point as well!

2. A drone!

You’ll also need a Parrot AR 2.0 drone for this guide. You can find these on Amazon for under £200 brand new (at the time of writing), but check the used/new options from other sellers as I managed to get it even cheaper through Amazon Warehouse Deals, just with a slightly damaged box! Click this link to see the current cost of these drones on Amazon (UK).

3. Spare battery (optional, but recommended)

I would definitely recommend getting hold of an additional battery for the drone as the flight time on the standard battery (1000mAh Li-ion polymer) is around 10-12 minutes, give or take. I got hold of a 1500mAh battery to use while the other one is charging which worked out quite nicely. The 1500mAh I bought can be found here and will allow for about 18 minutes of flight time. This will cost around £40 which seems like a bit of a sting to the wallet but it with save you twiddling your thumbs for around an hour while you’re waiting for a battery to charge!

Third-party batteries: If you’re going to get a spare battery, I would absolutely recommend getting an official Parrot one rather than from another manufacturer. Although these batteries may well be a bit cheaper and probably absolutely fine for use, I remember reading some horror stories online when I originally started looking for a spare battery.

4. Notepad++

Aside from the above, I would also recommend downloading Notepad++ as we’ll be fiddling with some code in JavaScript. Notepad++ is a nice, basic text editor that understands code formatting so will highlight elements of code for us, which will really help anyone get to grips with basic coding.

Let’s get to it!

1. Create a folder to work from

Just before we get into installing NodeJS, the first thing I did was create a folder on the Desktop called ‘Drone’ which contained an empty folder called ‘nodejs’. When we install NodeJS below we’ll change the default install location from C:\Program Files\nodejs\ to C:\Users\Mark\Desktop\Drone\nodejs\ (just change ‘Mark’ to the user name on your PC!)


2. Download and Install NodeJS

Now we’ve got a place for NodeJS and our other files to live, click this link to view the available NodeJS downloads.

The version you download will ultimately depend on the operating system you are running, in Windows you can check this in the following ways:

  • Windows 7 – right click the ‘Computer’ option in the start menu and click the ‘Properties’ option
  • Windows 8 and 10 – hold down the windows key (key in-between CTRL and ALT on the bottom left of keyboard) and press E to open the Windows File Explorer, then right click ‘This PC’ on the left hand side of the file explorer window and click ‘Properties’.

The resulting window should contain the ‘System’ section as shown below.


According to the result given above for my PC, I’m running a 64-bit operating system (‘System type’ field) so I’ll need to download the 64-bit version of NodeJS (use the .msi installer) as shown by the red box in the next screenshot.


Clicking the link in the red box above will start to download NodeJS, once the file has downloaded double-click it in your Downloads folder to start the installation process. Accept the license agreement and click Next on each screen if you’re happy with the defaults, apart from the screen that includes the below (install location of NodeJS).


Click the ‘change’ button and in the new window that opens, type  ‘C:\Users\<yoursystemusername>\Desktop\Drone\nodejs\’ as the location to install NodeJS, click OK to confirm and close the new window and then click Next on the original window for all further steps of the installation.

We now have NodeJS installed on our machine! There’s just one last step to complete which will make sure that NodeJS knows what a drone is and how to work with it. To do this we need to use the windows command prompt within the nodejs folder – do this by holding down the left ‘shift’ key on your keyboard and right click an empty area inside the nodejs folder, then choose ‘Open command window here’ as shown below (ignore any additional files you can see in the background, you’ll create these soon!).


At this point you should have a command window open much like the one below.


Type in npm install ar-drone and press enter.

The result should look something like the output shown below, ignore the yellow warning (WARN) messages.


What this has done is tell the Node Package Manager that we need a new set of ‘tools’ (or ‘package’ of tools), the tool in question is one created by Felixge which enables the NodeJS application to work with our drone and perform commands such as take-off, land etc.

If you head to the npm website, you can search for available npm packages for a range of uses, below I’ve entered ‘ar-drone’ to see the packages available for our drone.


3. Connect to the Drone

First things’ first, if you’re using a desktop PC like me – make sure you have a wireless network adapter (see recommended USB Wi-Fi device mentioned earlier in this guide), and be sure to test it works by connecting to your Wi-Fi at home and accessing the internet through your web browser.

Attach a charged battery to the drone and set it on the side for now, the lights should come on and the propellers should perform a quick test (small jolt of each propeller, don’t worry it won’t take off until you tell it!).

Assuming your Wi-Fi is working as expected on your PC, a new connection should appear if you click the Network icon in the system tray (bottom right of your screen), ‘ardrone2_062272’ in my case. Click on your ardrone2_xxxxxx network, and then click the ‘Connect’ button to establish the connection between your laptop/PC and the drone.


Note: I’m not under police surveillance (promise), my Wi-Fi network was named by my housemate!

When you’ve connected to the drones’ Wi-Fi it will say ‘No internet, open’ regarding the connection to your drone, don’t worry about this at all, it’s only showing this as your PC would normally expect a connection to a router/hub that provides internet access to your machine, our drone isn’t that clever unfortunately.

4. Running NodeJS and controlling the drone (takeoff and land)

Once you’re on the Wi-Fi of your drone, open the node program that we installed into ‘…Desktop\Drone\nodejs\’ earlier, double-click node.exe (green hexagon-shaped icon with a white ‘n’) to open the NodeJS terminal window.

NodeJS will be your means of sending commands to the drone and receiving data back (such as receiving a live stream from the drone to your PC, which we’ll get into in the next guide). Now that we have the NodeJS terminal window open, we can start typing in some commands to explicitly establish our connection between the NodeJS application and the drone to start sending it commands.

At this point I’m going to borrow some bits from the Instructables guide as they do an amazing job of going over the commands. To save you having to jump between different guides, I thought it would be better to copy and paste a couple of images from their guide (all credit for the below images of code to Instructables!)

In case you’d like to use the guide though, the Instructables guide can be found here.

If you’re still with me, we’re going to start entering some stuff into the NodeJS command window we recently opened (node.exe). The image below shows four lines that each needs to be entered into the NodeJS command window, one-by-one. Before we enter these commands, let’s go over each one briefly:

  • var arDrone = require(‘ar-drone’); this command lets NodeJS know that it needs to use the library of tools called ar-drone that we downloaded earlier to complete some or all of the commands that follow.
  • var client = arDrone.createClient(); we’re now getting a bit into networking, NodeJS is what’s called a ‘server-side’ language so its job is to provide stuff (commands, data, files etc.) to ‘clients’. In this case we’re telling Node that our drone is the client and we’re about to provide it some instructions, simple as that!
  • client.takeoff(); so we’ve told Node that our ‘client’ is the drone, this line is telling the drone to go ahead and run a command from the ar-drone library (see first command) called takeoff(). No prizes for guessing what happens when this command is executed!
  •; same idea as client.takeoff(); – it makes the drone land with the command called land() in the ar-drone library.


So now that we’ve gone over each command hopefully you have a better idea of how everything we’ve done up to this point fits together. We need NodeJS to send data to and from our drone, but to do that we need the package of tools called ‘ar-drone’ to ensure NodeJS understands what a drone is and how to communicate with it.

Once you’re happy with the above ideas, go ahead and enter each command. I’ve written them out below so you can copy and paste them into the NodeJS window a line at a time if you like. Word of warning, when the drone takes off it will hover about a meter off the ground and stay roughly there until you tell it to land. Just in case you need to stop/land it quickly for whatever reason, I would make sure you copy the command to land the drone (highlight command with cursor, right click, copy) before pressing enter on the take-off command. This will make sure that you can paste the land command into the NodeJS command window (right click NodeJS window and choose Paste, ctrl+v doesn’t work!) and press enter to stop the drone whenever you need.

var arDrone = require(‘ar-drone’);

var client = arDrone.createClient();


If you run into any errors, make sure each line ends with a semicolon (;) and you’ve run each line separately by pressing enter after each semicolon at the end of the line. If it presents you with an error about not knowing what ar-drone is, make sure you’ve used the npm install ar-drone command as shown earlier in the guide. When all is said and done your NodeJS window should look more or less exactly like mine below:


5. Running commands as a simple, repeatable JavaScript program instead

To write our JavaScript files I installed Notepad++ as this is a fantastic, free and simple text editor that comes equipped with code assistance tools which will help us more easily visualise the structure of our code. In case you skipped the link above, you can download Notepad++ here. You can just use Notepad it you like, but Notepad++ does make the code a little more understandable.

First thing’s first, let’s make a new Notepad++ file for our program. Open Notepad++ from wherever you installed it and enter the code shown below.


Now save the file as firstflight.js in the same folder as your node.exe application (e.g. …\Drone\nodejs\firstflight.js). To do this click File -> Save As…, enter firstflight.js as the ‘File name‘ and change the ‘Save as type’ option to JavaScript file (*.js) as shown below.


If you don’t fancy writing this file for yourself, firstflight.js and some other JavaScript files (which we’ll be going over soon) can be found in my GitHub repository, feel free to download/clone this repository and mess around with the code! Alternatively, if you’re not familiar with working with GitHub/Git, typing out the files will achieve the same result.

GitHub: In case you’ve not bumped into these terms before, I’ll give you a quick explanation. GitHub is a website which software developers use to store and maintain code on. If they choose to store their code in public repositories then me or you can find it on the GitHub site, download it, play with it etc. The main major reason people use Git(Hub) as well is that it offers ‘Version Control’. This means that whenever updates are made to code,the previous versions of that code are still kept in case the creator needs to roll back to a previous version for any reason (say, the new code has a massive bug in it, but the old version didn’t).

Git: This is the application you install on your laptop or PC to manage the use of code repositories, enabling you to clone (make a copy of) someone’s code from the GitHub site (remote repository) onto your own machine (local repository) to mess around with. If you choose to set up a GitHub account, you too can create repositories of code that you can share with others and utilise Version Control.

To complete this guide, you don’t need to use GitHub at all if you don’t want to, nor do you need to install Git so don’t worry about these for now. In the next guide we will need to though so I’ll point you at some resources later on that will get you up to speed on what you need to know.

To run our program we’ll need to open the Windows Command Prompt (not the NodeJS command window) in the location of your firstflight.js file and enter the following command. Remember, to open the command window in a location in your file explorer you can hold left-shift and right click a blank area within the nodejs folder, then choose ‘Open command window here’.

node firstflight.js

Your drone should now take-off, and about 5 seconds after starting to take off it will start to land. So it’ll take-off, hover for a couple of seconds, then land.

Note: if your drone just sits on the ground with its lights flashing, it is likely you’ve got a NodeJS window open somewhere, make sure all NodeJS windows are closed! The above command calls node and tells it to run a particular program – node firstflight.js essentially means “computer, I want you to use a program called node [node.exe as we know it] to run a JavaScript program called firstflight.js, simple as that!

Another note: I asked you to open command prompt in the directory of the firstflight.js program you wrote, this isn’t mandatory, it just saves you having to type out the whole path to your program like node C:\Users\Mark\Desktop\Drone\nodejs\firstflight.js – that would be a pain to enter every time compared to node firstflight.js, much more typing involved each time!

6. Adding more commands in JavaScript

We now have a simple program that makes the drone take-off, float about a bit, then land. Altogether not too exciting, but we can add some more commands into the program to make it do a bit more for us.

When making this guide, I created a JavaScript file called secondflight.js to demonstrate a few more simple commands, these commands are described nicely in the Instructables guide so I’ve used their examples along with my own description of what each one does below.

Any reference to (speed) is a value between 0 (no speed at all) to 1 (max speed), you can replace the word ‘speed’ inside the brackets with any value from 0.1 to 1 to set the speed of the given action. (E.g. front(0.1) will make the drone go forward very slowly but front(0.9) will make it go forward at 90% of its maximum speed).

  • up(speed) – drone will gain altitude (go up)
  • down(speed) – drone reduce altitude (go down)
  • clockwise(speed) – drone spins clockwise at a given speed
  • counterClockwise(speed) – drone spins counter-clockwise
  • front(speed)/back(speed) – changes the pitch causing horizontal movement
  • left(speed)/right(speed) – changes the roll causing horizontal movement
  • stop() – keeps the drone hovering in place

The file secondflight.js in the screenshot below demonstrates us adding a bit more functionality to our drone program. In this file we’re telling the drone to take off, go forward a bit (front) at 20% (0.2) of maximum speed, then stop after 2 seconds/2000 milliseconds of going forward (lines 10 and 11, .after(2000, function() {this.stop()}. The same is then repeated but instead of going forward again (front), we’re telling it to go backwards (back), before stopping and then landing.


That was pretty straightforward, so just to concrete the idea in our minds about how these commands are built and work with the drone, thirdflight.js (below) demonstrates the concept of ‘yaw’ using the clockwise and counterClockwise commands.


Yaw is a movement where the drone will stay at the same height/altitude, but rotate mid-air without going forward or backwards – like putting a pen flat on its side on a table and rotate it, this is yaw! The image below shows the concept of yaw in terms of an aeroplane, linear rotation on the perpendicular axis of the object.


Above image source –

Another example of using navigational controls in NodeJS is making the drone perform a simple route around an object. This is exactly what I did when I was learning about the use of NodeJS with the drone as shown in this video..

Feel free to copy the code I wrote to perform the square route in the video linked above, this too can be found in my GitHub repository.

That’s all for now

With any luck you now have a drone flying about breaking every lampshade in its vicinity! If you ran into any issues that you couldn’t figure out please comment below and we’ll have a go at fixing it together. Similarly, if you ran into issues using this guide and were able to overcome them, please comment as well so I can update this guide with your input!

In the next guide, I’ll be taking you through how to use an amazing open-source (free) application called WebFlight (all credit to Laurent Eschenauer) to enable us to control the drone in real time using the keyboard as well as allowing us to view a live feed from the drones’ camera through our web browser.

Thanks for reading,