Getting Started


  1. Install VirtualBox
  2. Install Vagrant
  3. Run the following commands in a directory to create a Vagrantfile for our box:

    vagrant init joomlatools/box
  4. Only for Ubuntu users - start the NFS service to be able to mount directories:

    sudo service nfs-kernel-server start
  5. Start the box:

    vagrant up
  6. Add the following line into your hosts file (/etc/hosts on Linux and Mac OS X, for other operating systems see here):
  7. 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.

Note: Some users reported issues on Windows 10 machines when mounting the shared directories. Please refer to this FAQ item for a temporary fix.

Creating new Joomla sites

  1. Once you have installed the box, you can run terminal commands right from the dashboard at 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. Click on the Sites tab on the dashboard to refresh the list of installed sites. 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 mysite.test line you can browse to the site via mysite.test.

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 than just 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.