Local Development

Setting up a local development environment with Scotch Box

Very recently I had the misfortune of being forced to uninstall Ubuntu from my laptop and go back to Windows. I won’t get into the reasons behind this, but the one thing I miss in the Windows environment is my LAMP (Linux/Apache/MySQL/PHP) stack and bash command line. Most web site hosts around the world use LAMP so I always prefer to develop in as close as environment as what the production server will be as possible. Developing on Ubuntu makes this super simple, as I am effectively running the same (ish) OS and software on my laptop as would be on the server.

When I’m on Windows I use a combination of GitBash and WampServer to power my default local environment (now that ZendServer no longer offers a free edition). It’s super quick and simple to setup and configure and you can have a local development environment up and running in minutes. However it’s still not a replacement for a proper Linux based development server.

Then I discovered Scotch Box.

Scotch Box is a zero configuration Vagrant Box that will have to up and running with a Linux (Ubuntu) based virtual web development environment in literally minutes. It comes pre installed with everything a modern web developer might need and requires very little in the way of configuration to get up and running. Simply clone the GitHub repo, run vagrant up and you’re off.

Now, having said all that, there are some things about it that I don’t like.

Directory structure – If you are coming from a WampServer environment and you want to use Scotch Box, you are going to have to change your folder structure slightly. ScotchBox by default creates a public directory inside your project directory, in which you should have your project files. WampServer typically uses one root web directory (typically c:\wamp\www or c:\wamp64\www for 64bit environments) with all your site/project directories inside that directory.

Database access – Scotch Box doesn’t come with PHPMyAdmin installed by default. Now while I understand the reasons behind this, sometimes you just want to be able to quickly view your data and PHPMyAdmin is one of the best web based tools to do this.

Multiple sites – While ScotchBox does support virtual hosts (for running multiple sites on the same instance) I prefer to run a single instance of ScotchBox for each project but with it’s own virtual IP. This means I can have two or three development sites running at the same time.

MySQL Password – this is a personal preference, but I prefer to use password as my MySQL password instead of ScotchBox’s default of root.

So, after playing around with the Vagrantfile a little I have successfully set up an environment that suits my requirements.

The Setup

Step one – you will need to install VirtualBox and Vagrant for your OS of choice.

Step two – either download (as a zip) and extract or clone (if you git) my scotch-box repo.

Step three – copy the Vagrantfile and vagrant.yml files to your project directory (this is the root of your development website, wherever the index.php file is located)

Step four – Edit the vagrant.yml file and change the ip and sitename variables to an IP address and virtual host name of your choosing. I usually start with the default Vagrant IP address and then increment it for each new project (, etc). I also usually make the sitename the same is my project directory name, but really all this is used for is the DNS record (next step)

Step five – in your hosts file (usually C:\Windows\System32\drivers\etc on Windows, or /etc/hosts on either Mac or Linux) add a record for the new site    yourchosensitename

This tells your browser that when you browse to http://yourchosensitename/ to look for its content on the IP, which will be bound to your project’s ScotchBox instance.

Step six – Using the command line tool of your OS, browse to the project directory and run the following command

vagrant up

It will do a bunch of stuff and then your ScotchBox will be ready.

You can use http://yourchosensitename/ to browse the project you are working on and http://yourchosensitename/phpmyadmin to access PHPMyAdmin for this instance.

When you are finished you can run the following from the command line (inside your project directory)

vagrant halt

This will stop your ScotchBox instance. You can start it up again with the vagrant up command and it will be there, just as you left it.

Under the hood

Let’s take a look at the Vagrantfile and vagrant.yml to see whats happened behind the scenes. You can read more about the Vagrantfile, but in short its the file that makes all the Vagrant and ScotchBox magic happen.


Line 4-6 include the vagrant.yml and make this site settings available to the Vagrantfile.
Line 11 sets the Scotch Box IP to whatever you have specified in the vagrant.yml
Line 12 sets the hostname to whatever you have specified in the vagrant.yml
Line 13 setups up a synced folder between the current directory (wherever the Vagrantfile is) and the ScotchBox’s /srv/users/serverpilot/apps/jonathanbossenger/public directory (this is the servers web root)
Line 18-54 runs the Shell provisioner. This is where you can run some shell commands to setup any extra server related stuff. Here you will see I have removed a scotchbox.conf site that is not needed, set the new mysql password, installed PHPMyAdmin and created a database, using the sitename as the database name. If you are a shell master you can set up pretty much anything else here, from installing any other software you might need to project specific configurations. Remember that this runs every time you start up the box, so make sure whatever you are provisioning can be tested to see if it already exists, otherwise you might get some errors that cause the provisioner to fail.


All this does is contain the settings for IP address, sitename and mysql password, to be used in the Vagrantfile.

What I love about ScotchBox is that there are a bunch of things that come pre installed, including WP-CLI and a MailCatcher for testing email sending. And with a little tweaking to the Vagrantfile I have it configured perfectly for my environment.





8 responses to “Setting up a local development environment with Scotch Box”

  1. Rich Avatar

    Thanks for writing this article. I’m very new to Vagrant and Scotchbox and trying to get my head around all these things coming from being a pure front-end developer. Can I ask why do you have to get rid of the ‘scotchbox.local.conf’ file in order to install PHPMyAdmin?

    1. Jonathan Avatar

      Hi Rich glad you found it useful.

      You actually don’t need to get rid of the local scotchbox.local.conf, I just like to clean that file up because I don’t use the ‘scotchbox’ virtual host in my development environments, rather opting to use a more project name based approach.

      I actually tried to roll my own vagrant box last year, to suit my specific requirements, but it was just much easier to configure scotchbox to how I needed it.

  2. Martin Avatar

    How can i change the document root? For Contao installation i need the site served only within “/web” folder inner the containing public folder.
    thx, martin

    1. Jonathan Avatar

      Hi Martin, take a look at the following line in the Vagrantfile

      config.vm.synced_folder ".", "/wordpress/core/5.9.3", :mount_options => ["dmode=777", "fmode=666"]

      Chance the synced folder on the box from /srv/users/serverpilot/apps/jonathanbossenger/public to /web and it should work.

      1. Martin Avatar

        Hi Jonathan, thanks for your fast repsonse! This worked not for me. My original vagrant file looks like:
        # -*- mode: ruby -*-
        # vi: set ft=ruby :

        Vagrant.configure(“2”) do |config|

        config.vm.box = “scotch/box”
        config.vm.network “private_network”, ip: “”
        config.vm.hostname = “scotchbox”
        config.vm.synced_folder “.”, “/var/www”, :mount_options => [“dmode=777”, “fmode=666”]


        If i change that to”/var/www/web, the site is not responding anymore. Perhaps the problem is deeper into Apache settings? Im not firm with that.

  3. VESHALEN Avatar

    Hi there, I have a weird question. I’ve watched a tutorial. where the guy had both a homestead installation as well as wamp. Is this possible with scotchbox too ?

    1. Jonathan Avatar

      Hi, so Homestead and Scotchbox are both Vagrant boxes, so yes you would be able to have scotch and wamp installed on the same machine.

      I’d also suggest checking out the Scotchbox update which was released recently. It makes a few of my configs unnecessary.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: