- How do I stop the box?
- How do I destroy a box?
- How do I transfer an existing Joomla website to a vagrant box?
- How can I update the box to the latest version?
- How can I backup and restore my box?
- How can I access the command line on the box?
- How can I access the MySQL databases?
- Where are the error logs and access logs?
- How to test e-mails?
- Can I mount more shared directories?
- Where can I find phpMyAdmin?
- How can I use PhpMetrics?
- How to use Webgrind?
- I don’t like the command line! Is there another way to manage the Vagrant box?
- Can I SFTP into my box?
- Unable to connect Vagrant Guest VM’s in a private network?
- How can I run other PHP versions?
- How can I change PHP ini settings?
- How can I fix mount issues on Windows?
How do I stop the box?
vagrant halt to stop the box.
How do I destroy a box?
To completely destroy the virtual image, run
To create the image again run
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
mywebsitedirectory. You can find this directory in the
wwwdirectory on your machine, in the directory where you started the Vagrant box from. This path translates to
/var/www/mywebsiteon the box itself.
If you can access your website over SSH, you can transfer all your files at once with
rsyncwhich 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
wwwdirectory. 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:
Make sure there are no other configuration variables that need to be changed for the box, like
Note: you can also generate a configuration file automatically using this command:
joomla site:configure joomla --overwrite
but this requires that the
configuration.php-distfile is still present in your website, either in the
Now you can access your site at
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:
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:
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:
After you have verified everything is working again, you should manually remove the
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:
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:
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: 220.127.116.11
- 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?
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
synced_folders: /home/vagrant/MyProjects: /Users/johndoe/MyProjects
Save this file and restart the Vagrant box using the
vagrant reload command.
MyProjects directory from your host machine will now be available inside the Vagrant box at
Where can I find phpMyAdmin?
After you modify
/etc/hosts file as described in the installation steps, you can use phpMyAdmin at
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:
- Now run phpmetrics:
- Revert the memory limit to its original value:
- Read the generated report at joomla.box/mysite/report.html.
How to use Webgrind?
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
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.
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 wish to test the upcoming PHP 7.2 release, run:
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:
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
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
How can I fix mount issues on Windows?
It has been reported that the current 1.5 version of the box fails on some Windows installations to mount shared directories. If you encounter this issue, follow these steps to solve it:
Locate the box’s packaged Vagrant file. Its path looks like this:
Open this file in a text editor and look for the following string:
mount_options: ["rw", "tcp", "nolock", "noacl", "async"]
Replace it with:
Restart the box.
This should solve get the shared directories correctly mounted again.
We are looking for a permanent fix in issue #77 on GitHub. We’d love your help: feel free to comment your experiences or send us a pull request!
Let our developers personally assist you. You can ask development related questions in our Support Center. Only for Business or Agency subscribers.