If you have looked at setting up the Ionic Framework or have it done it before, you know on much of a pain it can be, especially when something doesn’t work. Luckily, Ionic offers a free virtual machine called Ionicbox that is already configured with all of the software that you need.
VirtalBox is a free virtual machine program. A virtual machine is a complete computer and operating system run from within your current operating system. It makes it possible to run Linux on a Windows Machine, Windows on a Mac, etc.
Vagrant is an easy way to manage virtual machines. A full explaination is out of scope for this article.
Make sure that you installed VirtualBox and Vagrant before proceeding.
Open Windows Explorer and create a directory where you want to hold all of your Vagrant configuration files
Instead the directory created in step 1, create a directory called IonicBox
In Windows Explorer, create the directory under the c drive called projects (i.e. c:\projects)
In Windows Explorer, do a shift+right click on the IonicBox directory and select Open Command Prompt
Run: vagrant init drifty/ionic-android
In notepad, open the VagrantFile created in the IonicBox directory.
select all of the text in the VagrantFile and remove it
Copy the following text into the VagrantFile
So what do all of those options in the VagrantFile mean?
In the configuration we configure the video and physical memory of the virtual machine. Since IonicBox is just a shell without a GUI, it doesn’t need a lot of resources, so we only give it 2 gigs of memory. Now if your host system doesn’t have a lot of memory, you will need to dial this down.
Ionic uses port 8100 for the web site and the live reload function use port 35729. We forwarded these ports from IonicBox to the host machine so we can access the web server. The following two lines do the port forwarding
The IonicBox is just a Linux shell with no GUI so you will want to use a feature in VirtualBox called Shared Folders to be able to edit the files from your host machine. In our case we are using c:\projects on the host machine which is linked to ~/vagrant_projects on the IonicBox
Next we set up the VirtualBox options
- We don’t need the VirtualBox GUI since we are going to SSH into the machine so we can turn it off with. Set this to true the first time, just so you can see it
- We set the Video Ram to 128 megs
- Turn on the USB drivers so that we can connect an Android device
- Add a usb device filter for a Android Device
- On Windows, You need to turn on Symlinks to the synced_folders. This is needed if your Host Operating System is Windows in order node/npm to work correctly. Remember you have to run your command prompt as an administrator for this command to work.
- Set the system memory for the virtual machine. If you host machine is low on memory you can reduce this down. You must have this much memory free when the virtual machine starts up
- Number of Physical CPUs to allocate. My machine only has 2 physical CPUs. You can allocate more or take it down to 1
- The name to use for the virtual machine in the VirtualBox Manager UI
Starting up the IonicBox and Getting logged in
- Open a command prompt and navigate to the IonicBox folder that contains the VagrantFile.
- If on Windows, open the command prompt as an Administrator.
- To open the command prompt as an administrator in Windows 8 go to the Start Menu Screen, type cmd, then ctrl+shift+click or ctrl+shift+enter
- Run command below. This command will take a while the first time you run it since it has to download the vagrant box container which is about 1 gig in size.
If you have the vb.gui = true in your VagrantFile, the first thing you will notice when you boot up the IonicBox is that it just comes to a command prompt and it leaves you wondering now what. Luckily, this is exactly what we want and it is very easy to manage it. The IonicBox basically just replaces the command prompt that we would normally use for all of the Ionic commands with a linux machine.
- To login to the machine, use the same command prompt as previous step and run
- if everything went successful you should be logged in
Testing the IonicBox
Now lets create our first Ionic project.
On the IonicBox ssh connection:
You now have a Ionic project in a directory called firstApp and the web server is running.
Open up your web browser and navigate to http://localhost:8100
You can view all of the files that make up this project on your host machine under c:\projects\firstApp
If you are NOT using Windows as your host operating system that we are done with configurations. Unfortunately, if you are using Windows as your host operating system, we have one more step to get npm working correctly, so that you can download all of the dependencies for Ionic. WARNING: Unless you have npm 3.0+. This may not fix the issue with node and long file names on Windows with npm.
We need to setup a symbolic link for the node modules folder since windows has a length limitation when using shared folders. A symbolic link is basically a point from one directory to another. Windows has a directory name length limitation that we encounter when host our files through a shared folder. Since our npm dependencies (node modules) folder doesn’t need to be checked into source control, we can move it to a directory on the IonicBox and just point to that from within our Ionic projects.
On the IonicBox from the firstApp folder run the following commands:
Remember: If on Windows, you need to run the vagrant up command from an administrative command prompt.
You may also need to manually install bower
I am done with IonicBox, now what?
To exit vagrant ssh session, just type exit from the command prompt that is logged into the IonicBox. This will put you back into the original command prompt.
Hibernate: from the IonicBox directory with the VagrantFile run
- Shutdown and Turn Off: from the IonicBox directory with the VagrantFile run
- Delete the whole IonicBox Virtual Machine: from the IonicBox directory with the VagrantFile run
- Note that sometimes this leaves behind the directory that contained the Virtual Machine. Before you can run vagrant up again, you will need to manually delete this directory.
This is a nice easy way to get started with ionic without having to install much onto your current machine.
However, if you are going to spend a lot of time developing ionic applications, it won’t be long before you go down the route of installing everything onto your machine to do the development work.
Check out my installation guides to help you out: