Getting Started


  1. Install VirtualBox
  2. Install Vagrant
  3. Run the following commands in a directory of your choice to download and start the Vagrant box:

    vagrant init joomlatools/box vagrant up

  4. Add the following line into your hosts file (/etc/hosts on Linux and Mac OS X, for other operating systems see here):

  5. The dashboard is now available at

There will be two new directories created called www and Projects. These directories act as shared directories between your host computer and the box.

Creating new Joomla sites

  1. Once you have installed the box, open up the web terminal by browsing to Alternatively, you can SSH into the box from the command line with the vagrant ssh command.

  2. Create your first Joomla website with this command:

    joomla site:create mysite

  3. Your new site is available at You can login using the credentials admin / admin.

    Note: the box always creates a separate virtual host for every Joomla installation but you have to add the hostname to your /etc/hosts file yourself. After adding the line you can browse to the site via

Now that the Joomla site is running, we can push our own work into it.

Let’s say you are working on your own Joomla component called Awesome and want to continue working on it using the Vagrant box. We should start by making the source code available to the Vagrant box. You can move your existing code into the Projects directory, which is automatically created for you in the directory where you executed vagrant up.

Or, even better, you can tell the box to include other directories. Let’s assume the source code is located at /Users/myname/Projects/awesome:

Create a file called config.custom.yaml (example) in the directory that contains your Vagrantfile (this is the location you started the box from on your host machine) and make it look like this:

    /home/vagrant/Projects: /Users/myname/Projects

Save this file and restart the Vagrant box using the vagrant reload command.

The “Projects” directory from your host machine will now be available inside the Vagrant box at /home/vagrant/Projects.

Next step is to create the new site you’ll be working on. Execute the following command on the box (via the web terminal or through vagrant ssh):

joomla site:create testsite --release=3.2 --symlink=awesome

Or to symlink your code into an existing site:

joomla extension:symlink mysite awesome

Run discover install in the Joomla Extensions manager to make your component available to Joomla and you are good to go!

For more information on the symlinker, refer to the Joomlatools Console docs or run:

joomla extension:symlink  --help

Next steps

The joomla command is the most important piece in our Vagrant box. It’s the workhorse for everything related to Joomla on the box. This Joomlatools Console package can do a whole lot more except installing sites. You can also automatically install your custom extensions and even create your own plugins.

To find out more about its options and usage, you can get an overview by running the joomla list command, or head over to the documentation pages for a full explanation.

Need Help?

Let our developers personally assist you. You can ask development related questions in our Support Center. Only for Business or Agency subscribers.