December 30, 2013

Tutorial: How to get started with Apache Cordova and Firefox OS on Nitrous.IO

It's time to go mobile. And it is time to go cloud. Why not go mobile in the cloud? In this tutorial we'll learn how get started building mobile web apps using Apache Cordova (formelly PhoneGap) and testing your app using the Firefox OS Simulator. To avoid some setup complexity and to allow for coding entirelly in the cloud, let's build the app using a Node.js Nitrous.IO box.

1 - Signup for Nitrous.IO and spawn a Node.js box

Nitrous.IO is cloud development environment, that allows you to quick and easy setup a linux box in the cloud with zero-install: just using your browser. If you don't have a Nitrous account yet, you can signup for one on, using Google, Github, or by using a username and password.

Once logged into Nitrous, start a new box, and choose the Node.js box template:

The IDE will open after your box is ready, with the following image:
The black screen in the bottom is the Console window, where you will type the commands.

2 - Install Apache Cordova CLI using npm

Apache Cordova is a mobile application container, that allows you to build Web Apps that can be installed on mobile devices, and benefit from the device features, such as Camera or GPS. I recomend reading the documentation to get a grasp on it: at least Overview and Command Line Interface (or the Web Project Dev).

To install cordova on your box, run the command below in the console window:

$ npm -g install cordova

NPM is the Node Package Manager, and the Cordova CLI is distributed as a node module. The above command will download and install the Cordova CLI tools and install them on your Nitrous box, under the ~/.nvm folder. This may take some minutes, and when it the instalation is complete, you can test it with the command

$ cordova info

This command will display some details about how to use cordova, and about your cordova instalation.

3 - Start a new cordova project

With Cordova installed, we are ready to start the project itself. In your console window, run the commands:

$ cd ~/workspace
$ cordova create hello

This will create a project under ~/workspace/hello, and you will be able to see some folders:

$ ls hello/
merges  platforms  plugins  www

The folders merges, platforms and plugins will be empty, but we will fill some of them soon. The merges folder hosts platform specific content overrides. The platforms folder will host the cordova.js JavaScript bindings, plus some configurations and other media. The plugins folder will host additional plugins, as you add them.

The www folder is your application root. Cordova will create a small sample app that responds to the 'deviceready' event in that folder. The index.html file references the app script, style sheet and image assets.

4 - Add the Firefox OS platform

To make your app deployable, Cordova needs some platform specific JavaScript bindings, plus the target platform SDK to build the final app. You can add as many platforms as you wish, with the command cordova platrorm add <platform shortcut>. Some platforms, like ios (from Apple) or wp8 (from Microsoft), require a particular operating system to build and run your app on emulators (see details here). In this tutorial, we'll be using the firefoxos (from Mozilla) platform, since it can be tested entirelly using the web.

To add the Firefox OS platform, run the command, from the hello folder

$ cd ~/workspace/hello
$ cordova platform add firefoxos

After that command finishes, the platforms folder will have a new sub-folder, with the cordova bindings and some sample configurations. We are ready to test our app now!

5 - Test in the Nitrous.IO browser

Cordova can serve your app from a built-in web server, so you can test your preview the app on your browser.

Once we have added a platform, we can run:

$ cordova serve 3000
 Generating config.xml from defaults for platform "firefoxos"
 Preparing firefoxos project
 Static file server running on port 3000 (i.e. http://localhost:3000)
 CTRL + C to shut down

Nitrous allow you to do live testing of servers started from your box. Click on the Preview menu -> Port 3000, and a new browser window will open, displaying the Cordova serve main page:

This page lists some app info, and the platforms and plugins available. Note that the firefoxos platform is a link you can click and, voila! Your app is running!

The same URL can be used to access the app on your mobile phone or tabled, using the device browser, so you can preview how it may look like in the smaller screen.

6 - Install the Firefox OS Simulator

Besides using a tools that allow you to preview the web page on mobile device iframes, you can also use a real device emulator for this task: the Firefox OS Simulator. The device simulator is a Firefox add-on that allows you to test web apps designed to Firefox OS. To install it, launch Firefox (or Iceweasel if you're on Debian), and go to the Firefox OS Simulator add-on page, then click "Add to Firefox" button. The download and setup may take some time, the add-on has more than 60MB.

Once installed, the simulator can be launched from the Firefox (Iceweasel) menu -> Developer Tools -> Firefox OS Simulator.

7 - Run your app in the simulator

The simulator will allow you to add a URL for your app. Copy the link of your app preview and paste it to the Firefox OS Simulator URL bar, then click on the "Add URL" button:

The device simulator will launch, download and install your app for testing. And you will see the app running on the simulator:

The simulator is a pretty nice, and give you an idea on how your app fits on a real device. You can test the device with your mouse, and navigate over the OS and test launching and closing the app.


The web of today is the web accesible from Mobile to 4K TVs. The mobile market is growing fast, and the web is here to help you jump in. Using technologies such as Cordova (PhoneGap) you can reach a broader audience of mobile customers, by using well known web standards. Cloud Computing enables infinite scaling and computational power, helping you build awesome apps that can do amazing things. Nitrous helps you get started on almost everything, by providing a simple and easy to use web interface, with a powerfull GNU/Linux box in the cloud.


/happy hacking