FAQs

How do I destroy a box?

To completely destroy the virtual image, run vagrant destroy.

To create the image again run vagrant up.

How do I transfer an existing Joomla website to a vagrant box?

It's very easy to do but it does depend on where and how your Joomla site is currently hosted. In general, these steps will help you set up the box:

Create an empty site:

joomla site:create mywebsite --release=none

Download or copy your website files into the mywebsite directory. You can find this directory in the www directory on your machine, in the directory where you started the Vagrant box from. This path translates to /var/www/mywebsite on the box itself.
If you can access your website over SSH, you can transfer all your files at once with rsync which is available on the Vagrant box. For example:
```
rsync -avz -e "ssh" ssh_user@server_ip:/var/www/yourwebsite.com/public/
```
The required parameters will depend on your hosting set up. There are a lot of examples available on Google!
Download a dump of your MySQL database and make it available to the box. You can easily do this by placing the dump file in the www directory. You can then set up the database like this:
```
joomla database:install mywebsite --sql-dumps=/var/www/mywebsite-dump.sql   
```
Finally, open up the configuration.php file and update the database settings accordingly:
- $database: localhost
- $user: root
- $password: root
- $db: sites_mywebsite
- $host: localhost
Make sure there are no other configuration variables that need to be changed for the box, like $cache_handler, $log_path or $tmp_path.
Note: you can also generate a configuration file automatically using this command:
```
joomla site:configure joomla --overwrite 
```
but this requires that the configuration.php-dist file is still present in your website, either in the installation/ or _installation/ directory.
Now you can access your site at joomla.box/mywebsite.

How can I get rid of the SSL warnings?

You can access your sites or the Joomlatools Vagrant dashboard easily via https. However, your browser might present you with a big warning sign, telling you that the certificate is invalid. This is expected behavior because the certificates on the box are self-signed and not actually validated by a trusted third party.

You can instruct your system to trust this certificate by default, but the way to do this is different on each Operating System and browser. You 'll first need to get the certificate itself, and then add it to your list of trusted certificates.

Finding the certificate is easy. You can find it at /etc/apache2/ssl/server.crt on the box, or export it from Chrome by clicking the lock icon in the address bar, opening the Certificate window and then dragging the certificate icon to any other location.

To install the certificate, please refer to this excellent guide on how to do this on both Windows and Mac OS X. You can skip the certificate creation step.

How to troubleshoot NFS mount issues

The directories that are shared with your host machine are mounted by Vagrant using NFS. If you run into trouble with mounting shared directories, we recommend you start by installing the vagrant-vbguest plugin to automatically update your box's Guest Additions:

vagrant plugin install vagrant-vbguest

Outdated Guest Additions are the most common cause of NFS mounting issues.

How can I update the box to the latest version?

If a new version of the box is released, Vagrant will let you know when you run vagrant up. It's important to note that Vagrant stores the original box separately. Your running Vagrant environment is actually a copy of that box. From the Vagrant docs:

Finally, you can update boxes with vagrant box update. This will download and install the new box. This will not magically update running Vagrant environments. If a Vagrant environment is already running, you'll have to destroy and recreate it to acquire the new updates in the box. The update command just downloads these updates locally.

In short: if you have important data on the box, be sure to back it up first. See "How can I backup and restore my box?"

To replace your current box with the latest version, you need to run these commands in the following order:

vagrant destroy
vagrant box update
vagrant up

How can I backup and restore my box?

We included a backup command that will create a tarball containing your Apache and Nginx vhost configurations. It will also create a MySQL dump of each database and add it to the tar archive. To run it, simply execute:

box backup

This will create a joomla-box-backup.tar file on your host machine.

Your sites (in the www directory) and project files (Projects directory) are mounted from your host machine, so they will always remain there. We don't include these in the backup.

To restore your virtual hosts and databases, after upgrading the box for example, you need to run this command:

box restore

After you have verified everything is working again, you should manually remove the joomla-box-backup.tar file.

How can I access the command line on the box?

You can always run commands via the web terminal, accessible at the joomla.box dashboard as soon as the box is up.

Alternatively, you can SSH into the box by using the command:

vagrant ssh

How can I access the MySQL databases?

The MySQL server on the box runs with these default user credentials:

User: root
Password: root

So to connect via PHP you would pass in these details:

$connection = mysqli_connect('localhost', 'root', 'root', 'mydatabase');

If you prefer to, you can use phpMyAdmin at phpmyadmin.joomla.box if you setup your hosts file correctly, as described in the installation steps.

We highly recommend the Sequel Pro desktop client on Mac OS X over the use of phpMyAdmin however. You can connect to the database using a desktop client with the following details:

Host: 33.33.33.58
User: root
Password: root

Where are the error logs and access logs?

You can access Apache, MySQL and system logs via the browser at joomla.box/pimpmylog.

How to test e-mails?

We have installed MailCatcher on the box. You can access it via the dashboard.

PHP is configured to automatically send any mail to MailCatcher. You can test this real quick by creating a new Joomla site, creating a contact form and submitting it. Your message will show up in MailCatcher immediately.

If your applications use SMTP, you can configure your SMTP server as follows to send everything to MailCatcher:

IP: 127.0.0.1
Port: 1025

Can I mount more shared directories?

Yes, you can mount as many shared directories as you like. You can do so by creating a config.custom.yaml (example) file in the same directory that contains your Vagrantfile.

To mount the /Users/johndoe/MyProjects directory on the box, put the following configuration in config.custom.yaml:

synced_folders:
    /home/vagrant/MyProjects: /Users/johndoe/MyProjects

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

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

Where can I find phpMyAdmin?

After you modify /etc/hosts file as described in the installation steps, you can use phpMyAdmin at

http://phpmyadmin.joomla.box

How can I use PhpMetrics?

To gather various metrics about your PHP project, you can invoke PhpMetrics from the command line. Please note that PhpMetrics uses a lot of memory and so it is best to increase the allowed memory limit first.

Let's say you want to analyze the mysite site which you installed using joomla site:create mysite:

Open up the web terminal
Increase the memory limit:

box php:ini memory_limit 1024M

Now run phpmetrics:

phpmetrics --report-html=/var/www/mysite/report.html /var/www/mysite

Revert the memory limit to its original value:

box php:ini memory_limit 256M

Read the generated report at joomla.box/mysite/report.html.

How to use Webgrind?

After you modify /etc/hosts file as described in the installation steps, go to webgrind.joomla.box.

Enable the Xdebug profiler with the terminal command box xdebug:profiler start and reload the page you want to profile. Every page you visit will now generate a cachegrind file in /var/www.

Refresh the list of files by pressing the refresh icon in Webgrind (top-right corner of the page), select the file you want to investigate and hit the Update button.

See the box documentation for more info.

I don't like the command line! Is there another way to manage the Vagrant box?

There's a great tool we use to start and manage our Vagrant boxes once you've installed them, called Vagrant Manager. It is currently available on OS X only, though!

If the Vagrant box is running, you can execute commands on the box using just your browser. All you need is to browse to the dashboard. You can also edit files on the filesystem directly using the file browser.

We also installed Cockpit, which is an easy to use, web-based interface for the box. You can access it at joomla.box/cockpit.

No need to connect via the command line at all.

Can I SFTP into my box?

Use following details to connect:

Host: 127.0.0.1
Port: 2222
User: vagrant
Password: vagrant

Unable to connect Vagrant Guest VM's in a private network?

Can't reach the virtual network from your host at all (not even ping) although vagrant ssh works? You will need to have VirtualBox recreate the private hosts.

Luc Russell wrote a great tutorial on this matter.

How can I run other PHP versions?

It's possible to build both older and newer PHP versions using the box command. For example, if you need to test your code against a previous PHP release, run:

box php:use 5.6.24

Note that on your first run, the script will need to download and install additional build dependencies. This can take up to 15 minutes.

For more information on this command, please refer to the documentation.

Warning: switching the PHP version can potentially leave the box in a broken state. Use at your own risk. If something goes wrong and the box command stops working, you should be able to revert to the default PHP version using the phpmanager restore command.

How can I change PHP ini settings?

You can change PHP's configuration using the box php:ini command. For example, to disable display_errors, run this command:

{% highlight bash %} box php:ini display_errors Off {% endhighlight %}

This also works for custom PHP builds. For more information on this command, please refer to the documentation.

If you need to make changes directly to the .ini files, you can find php.ini at /etc/php/7.1/fpm/php.ini and additional config files at /etc/php/7.1/fpm/conf.d.

If you switched to a non-default PHP version, you can find php.ini at /opt/php/php-x.y.z/lib/php.ini and the additional configuration directory at /opt/php/php-x.y.z/etc/conf.d/.

How can I override mount options?

Vagrant uses NFS to mount directories on your host machine into the box. On some systems, the default settings might not be the most optimal. That's why you can override these settings easily using the config.custom.yaml file.

Create this file in the same place where you start the box and where your Vagrantfile is located. You can find an example of this file here.

Use the mount_options property to configure custom mount options. The default is set to:

mount_options:
 - vers=3
 - rw
 - tcp
 - nolock
 - noacl
 - async

If you are running on a Windows machine, we recommend the following configuration:

mount_options:
  - dmode=777
  - fmode=777

Start or restart the box for these new settings to take effect.

How can I change my Virtualbox settings?

It's also possible to override the default configuration for the Virtualbox image that Vagrant creates.

Create a copy of our example file in the same directory where your Vagrantfile is located and rename it to config.custom.yaml.

You can change the name of the machine, the IP address and the allocated CPU cores or memory using this file.