Joomlatools Vagrant

Joomlatools Vagrant automates the setup of a Joomla development environment. It is capable of running a full featured LAMP stack with a single command so that you can start working on your Joomla projects quickly.

Requirements

Vagrant 2.0 and up
VirtualBox 5.1 and up

Installation

Install VirtualBox
Install Vagrant
Run the following commands in a folder of your choice:
```
vagrant init joomlatools/box
vagrant up
```
This will download the Vagrant box and get it running.
Add the following line into your hosts file (/etc/hosts on Linux and MacOS, 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 folders created called www and Projects. These folders act as shared folders between your host computer and the box.

Usage

Once you have installed the box as described above, SSH into the box:
```
vagrant ssh
```
Create your first Joomla website with this command:
```
joomla site:create mysite
```
Your new site is available at joomla.box/mysite. You can login using the credentials admin / admin.
You can now symlink and install your custom extensions into the site, manage PHP versions and much more. Head over to our documentation pages to learn more about the box and its possibilities.

Updating to the latest version

When new versions of the box are released you can update your local machine by executing:

vagrant box update

Note that updating the box will not update an already-running Vagrant machine. To reflect the changes in the box, you will have to destroy (vagrant destroy) and bring back up the Vagrant machine (vagrant up).

For more details refer to our FAQ.

Sharing access to the box

HTTP

One of the great features of Vagrant is Vagrant Share. Note that Vagrant Share requires ngrok to work. We recommend you follow these set up steps first:

Upgrade Vagrant to the latest version.
Create your (free) account on ngrok.
Download and install ngrok.
Set up the authentication token on your machine as described in the ngrok documentation.

Now you're ready to start sharing access. Run this command and share the resulting Ngrok HTTP URL:

vagrant share --http 80

For more options and background please refer to the Vagrant docs.

Terminal

You can also share access to the terminal via SSH. There are two methods:

With tmate: run the tmate command on the box and share the resulting ssh connection string.
Using Vagrant's built-in SSH sharing feature.

Hacking on the box

Set up

If you want to make changes to the box's infrastructure, you can do so by building the box from scratch. Follow these steps to get started:

Clone this repository:

git clone https://github.com/joomlatools/joomlatools-vagrant.git

Install required Vagrant plugins

vagrant plugin install vagrant-puppet-install
vagrant plugin install vagrant-vbguest

Install dependencies with bundler:
```
bundle install
```
Go to the repository folder and build the box:
```
cd joomlatools-vagrant
vagrant up
```
You can now edit the Puppet configuration. To apply your changes, provision the box again:
```
vagrant provision
```

Building and releasing using Packer

We use Packer to automatically build the box. To start a build, follow these steps:

Clone this repository:

git clone https://github.com/joomlatools/joomlatools-vagrant.git

Install dependencies with bundler:
```
bundle install
```

Download the required Puppet modules using librarian-puppet:

cd puppet
librarian-puppet install --path modules/common/

Install Packer
Now edit the packer.json file. Look for the current version and increase the version number. The version number is defined in the variables section and can be found at the top of the file. It looks like this:
Also increase the $box_version variable in puppet/manifests/default.pp and update the changelog.
Commit the change and push back to GitHub.
Instruct packer to start the build:
```
packer build -on-error=ask packer.json
```
Once finished a joomlatools-0.0.0.box file will be created with the correct version number. Upload it to Vagrant Cloud to make it available to everyone else.

Run ServerSpec tests

Go to the tests directory: cd tests/
Install serverspec with bundle install
Run the tests: bundle exec rake spec

Note: to run on the box, run BACKEND=exec bundle exec rake spec

Reporting issues

The box is a very complex piece of technology, based on many different open source tools and libraries many of which are far beyond our capabilities and understanding.

We therefore deliberately keep the Issues section on this specific Github repo closed for such questions as we want to encourage people to submit code to add features or fix bugs by opening up Pull Requests instead of report bug or problems through Issues.

If you do have a problem running the box please use either our forum or chat room to get in touch with us and we are most happy to try and help you.

Contributing

Joomlatools Box is an open source, community-driven project. Contributions are welcome from everyone. We have contributing guidelines to help you get started.

Contributors

See the list of contributors.

License

Joomlatools Vagrant box is free and open-source software licensed under the MPLv2 license.

Community

Keep track of development and community news.

Follow @joomlatoolsdev on Twitter
Join joomlatools/dev on Gitter
Read the Joomlatools Developer Blog
Subscribe to the Joomlatools Developer Newsletter

CB9TOIIIA / joomlatools-vagrant