Getting Started

Installation

Install VirtualBox
Install Vagrant
Run the following commands in a directory to create a Vagrantfile for our box:
```
vagrant init joomlatools/box
```
Only for Ubuntu users - start the NFS service to be able to mount directories:
```
sudo service nfs-kernel-server start
```
Start the box:
```
vagrant up
```
Add the following line into your hosts file (/etc/hosts on Linux and Mac OS X, for other operating systems see here):
```
33.33.33.58 joomla.box webgrind.joomla.box phpmyadmin.joomla.box
```
The dashboard is now available at joomla.box

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

Once you have installed the box, you can run terminal commands right from the dashboard at joomla.box. Alternatively, you can SSH into the box from the command line with the vagrant ssh command.
Create your first Joomla website with this command:
```
joomla site:create mysite
```
Click on the Sites tab on the dashboard to refresh the list of installed sites. Your new site is available at joomla.box/mysite. 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 33.33.33.58 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.

Symlink your code into a Joomla site

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:

synced_folders:
    /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.