8 Local Development Options for Craft CMS
Posted: 12th Jan 2020
The first step on any new Craft project is getting up and running for local development work. Unfortunately this can also be a significant pain-point for developers who are just getting started or are trying to switch from one local development environment to another.
The first hurdle is figuring out what options are available. The second is deciding which is the best choice for our specific needs. Let's try to answer both of those with an overview of the most popular Craft CMS local development solutions and a look at their pros and cons.
How to decide which option is best?
Everyone's perfect solution will be different because we all work in different contexts. It's important to keep that in mind when reading through this list. Keep asking yourself: "Will this help or hinder my day-to-day work?".
Some specific things that you'll want to think about before we embark:
- Do I mainly work alone or as part of a team?
- Do I build mainly applications or simple marketing/catalogue sites?
- Do I have time to invest upfront, or need to get up and running quickly?
- Will my production environment(s) use any non LAMP-stack technologies?
- Do I regularly work on legacy projects, or projects that have specific base software version requirements? (E.G. PHP 5.4)
If one of the local development solutions below feels as though it provides a balanced answer to these questions your next step is to try it out and see! We've included as many links as we can to 'getting started' articles for each option so you should have a good set of resources to use to get yourself up and running.
If you're still stuck, reach out to the Craft community to see what their opinions are. You'll always find someone happy to evangelise about their preferred tools (I'll be shouting about Docker 💖), but if you explain your context you'll definitely get some sensible advice. You can find Craft devs on Discord and Stack Overflow.
DIY WAMP / MAMP / LAMP
To run Craft anywhere we need a few pieces of software to act as a webserver, interpreter and database. The traditional choices to fill these roles for Craft projects are Apache, PHP and MySQL. Each of these tools can be installed and run on Windows, Mac or Linux operating systems.
Our first local development option is to simply install these three tools on our development machine manually, wire them together and get to work.
But things are rarely that straight forward, and it's the 'wire them together' part that can cause a lot of problems with this solution. There are hundreds of different versions of Apache, PHP and MySQL each compatible with different versions of each other and with your operating system. There are also many different methods of installing each of them which could result in the installed files ending up in different locations on your filesystem! 😬
Because of this variability during setup your final results may be difficult to exactly reproduce. When working in a team with other developers, you will likely all end up with different versions of the software installed which can cause projects that work fine on your laptop to fail spectacularly on someone else's. Classic "It works for me" problems.
If you try to stick to specific versions of the software (maybe so you can match the versions in use in your production environment) you'll likely run into problems when performing operating system updates.
If you work really hard you can avoid these problems by diligently ensuring that any updates you make don't impact your development tools' versions. This can be more difficult than it sounds, but if you manage it you should be able to play well with other members of your team. Don't get too excited though...
What happens when we need to work on a legacy project which is only compatible with an old version of PHP? On some operating systems we can install multiple versions of PHP side-by-side, but making sure a specific project uses a specific version of PHP can be very tedious and fragile. Things get especially complicated when you end up using different versions of PHP for web requests vs command line operations! Results can be unexpected and infuriating. 😡
Who should use this solution?
Only masochists need apply, especially if you're a Windows user. Although initial setup can be simple on some systems, this solution suffers when it comes to long-term maintenance, teamwork and advanced use cases.
If you do go down this route, use it as an opportunity to learn what each of the different tools is doing, how they talk to each other and what the differences are between their versions. Once you're familiar with all of the components, burn it all down and choose something else from this list. 🔥
Ratings
Initial setup: ⭐⭐⭐
Easy to understand: ⭐⭐⭐⭐
Working in a team: ⭐
Local software matches production: ⭐
Switching versions: ⭐
Flexibility for advanced use cases: ⭐⭐
Getting started
Install Apache, MySQL and PHP on OSx Mojave
Install Apache, MySQL and PHP on Windows
XAMPP / MAMP
Rather than install and manage all of our stack manually we can use packaged GUIs to do it on our behalf. The primary benefit of this is that we can be fairly sure that the software they install will be organised in such as way that they will work immediately, so we don't have to worry about configuring them or plumbing them together ourselves.
These applications also provide convenient (if not fool-proof) methods for updating the individual components and uninstalling them if anything goes wrong.
There are several candidates for providing this functionality, but the primary contenders are MAMP on macOS and XAMPP on Windows. Linux users are less likely to want to go down this route, but they can also use XAMPP if they like or some linux distros have preconfigured LAMP stacks available as virtual packages available via tasksel.
This ease of installation can be a blessing because we don't need to necessarily understand how all of the underlying configuration is taking place, but it can also be a curse when things go wrong - we have much less knowledge to help us fix any problems we encounter later and it can be a struggle to make use of their components via mechanisms other than the GUI. 😓
Beyond the immediate benefit of an easy installation, these preconfigured packages also allow teams to get in sync a lot quicker. By installing the same version of the application they can be pretty sure that they'll all be running very similar versions of the underlying components and that they'll be configured and wired up in the same way. Config options that are presented to the user via the different GUIs are also easily documented and synchronised between developers working on a project.
However, there are still some challenges that remain... ☠
Switching versions of installed software (such as PHP) can still be difficult and often requires manual intervention. This can make it tedious to switch between new and legacy projects. See examples of some workarounds for MAMP here.
Similarly your OS configuration will be shared across all of your projects. This can be a significant problem if projects require OS level packages (E.G. ImageMagick) at different versions. Your only choice is to uninstall and reinstall those packages every time you want to move between projects. Not the friendliest workflow.
More advanced configurations (E.G. using additional external components such as Redis or ElasticSearch) can usually be achieved by installing other dependencies manually. It's important to note that every time you install an additional component these will be bringing their own sets of packages and dependencies along with them - all of which will be adding bloat to your development machine. Over time this can lead to poor performance in general and an increased likelihood of conflicts and errors, simply because there's a lot more stuff installed. 🐢
Who should use this solution?
Anyone who's working on projects that have few unique dependencies and don't often need to switch back and forth between new and legacy projects can benefit from the ease of configuration offered by this setup.
Over time things can become bloated and you might need to do a full system purge because of all the individual dependencies you've installed.
Keeping in sync with team mates is much easier as long as you ensure you have the same versions of the MAMP/XAMPP installed and configured similarly.
However, if you want to keep your OS pristine, with as little bloat as possible, keep reading to find out how to completely separate your development machine from your project dependencies.
Ratings
Initial setup: ⭐⭐⭐⭐⭐
Easy to understand: ⭐⭐⭐⭐
Working in a team: ⭐⭐⭐
Local software matches production: ⭐
Switching versions: ⭐⭐
Flexibility for advanced use cases: ⭐⭐
Getting started
Installing Craft CMS v3 with MAMP Pro [Video]
Installing CraftCMS on Windows Using Xampp [video]
Valet
Valet is a local development solution offered by the creators of the Laravel PHP framework. It is installed directly on your system, like MAMP and XAMPP, but takes a different approach to those all-in-one packages.
Firstly, it's a command line application and doesn't have a GUI to interact with. That's not a big deal though because it's also really simple.
Secondly, unlike X/MAMP which handle your entire stack, Valet primarily manages routing the requests from your web browser to your local projects, replacing Apache in the traditional stack.
If you'd like to, you are able to install and manage PHP and MySQL yourself, while Valet takes care of making sure each of your projects has its own local domain name and that those domains have valid SSL certificates set up.
Alternatively you can ask Valet to manage your PHP installation and version switching for you. Be aware that this isn't fool-proof though. There are some GitHub issues for Valet which describe situations in which PHP versions used for web requests and on the command line become confused over time.
Because of its limited scope, Valet is very slim, requiring very little memory and CPU to run which is great. However, it's only available for macOS because of it's integration with the OS to install SSL certificates and manage domain routing.
So far, so good, but Valet does suffer from some of the same issues that we've mentioned with previous solutions though. It is still relying on installing all of your stack directly on your development machine so managing colliding versions and dependencies remains an ongoing challenge and can lead to bloat over time.
Who should use this solution?
If you're a macOS user and you're happy using command line programs every now and then, Valet is a great option to provide a quick start for developers who work on multiple projects simultaneously.
Its light-weight nature means that it rarely runs into issues and is unlikely to break anything else installed on your development machine.
Ratings
Initial setup: ⭐⭐⭐⭐
Easy to understand: ⭐⭐⭐
Working in a team: ⭐⭐
Local software matches production: ⭐
Switching versions: ⭐⭐
Flexibility for advanced use cases: ⭐⭐
Getting started
Running Craft CMS 3 on Laravel Valet
VirtualBox / VMWare
All of our solutions so far have required us to install software directly on our development machine. We've also noted that this can cause problems with incompatibilities between dependencies and a gradual bloating of our development environment. So let's explore a local development option that solves this for us: Virtual Machines.
VMs are essentially computer systems within computer systems. They can remain completely independent of the system on which they run whilst still being able to use the raw resources of the host system.
We can use this compartmentalisation to our advantage during local development. Our VM can run any (compatible) operating system into which you can install any of that OS's software all without bloating the host. Because of this we are able to configure our virtual machine as closely as possible to our production environment without worrying about messing up our preferred development environment. Most developers will use a Linux Distro (often Ubuntu) as the OS of their VM and then manually install a LAMP stack within it.
VirtualBox and VMWare are the two primary candidates which help to organise the creation and lifecycle of your VMs. They provide a GUI via which you can build, launch and suspend as many different development systems as you require. They're relatively intuitive and will get you up and running with a new VM in a few minutes, but that's as far as they'll go. You'll end up with a completely fresh system which you'll then need to configure yourself manually by setting up appropriate networking, routing requests from your host, installing Apache, PHP and MySQL, or anything else you might need!
Compared to our previously discussed options, using a VM sounds like a more complicated, but overall pretty good idea. It can get us much closer to a development environment which is similar to our production environment and we can guarantee our precious host system is protected from all the things we'll need to install. But it doesn't come without its downsides...
Because a VM is running a completely independent system, it requires the resources of an complete additional system. You can expect a VM running Linux to use several hundred MB of RAM just to get started, and consume GBs of disk space. This can make running multiple VMs side-by-side difficult on resource constrained systems.
Due to resource limitations most developers will opt to create a single VM to house all of their active development projects. So, although we've managed to move all of our project dependencies away from our host OS, they're still all lumped together under one OS. And we already know that when we lump multiple projects and their dependencies together, we'll likely hit problems with software versions when we can least afford it. However, with VMs we do always have the option of deleting the entire VM and re-building it from scratch without impacting anything outside the VM - a very useful feature if you like to experiment with things that often break.
Who should use this solution?
Developers familiar with the command line and provisioning a simple Linux LAMP stack should be fine with this solution, but there's still a lot of manual work needed to get set up. It's likely Vagrant or Homestead (coming up next) will get you off the ground quicker unless you need a particularly well-customised setup.
If you're not as confident with these tools, but you'd like to keep your host OS as pristine as possible, this solution is worth considering, but again, Vagrant or Homestead will smooth your entry.
Ratings
Initial setup: ⭐⭐
Easy to understand: ⭐⭐⭐
Working in a team: ⭐⭐⭐
Local software matches production: ⭐⭐⭐
Switching versions: ⭐⭐⭐
Flexibility for advanced use cases: ⭐⭐⭐⭐
Getting started
Setting Up a PHP Development Environment
Vagrant
The most difficult part of setting up a VM for local Craft CMS development is getting it provisioned in the first place. Tweaking networking, getting your project files inserted into the VM's filesystem and installing all of the right software with the right versions. That's the problem that Vagrant solves.
You'll still need to install a VM manager such as VirtualBox or VMWare, but Vagrant will take care of the lifecycle of your VMs: creation, suspension and irradiation. It does this by allowing you to configure a set of parameters for your VM and provide a set of initialisation scripts which, when combined, allow Vagrant to take you from zero to fully functioning development VM within a matter of minutes.
As well as saving a lot of time and potential for human error - this method of VM provisioning is great when working as part of a team. If all team members are using the same configuration and scripts to provision their Vagrant VMs, they'll all end up with essentially identical development environments.
Some of the same caveats apply to Vagrant as with using plain VMs though. You're still creating a single VM to use with multiple projects so over time it'll get messy with specific project dependencies. If this does happen you do have the option to simply vagrant destroy and recreate it from scratch - as long as your provisioning scripts are up to scratch it only take a few minutes.
Who should use this solution?
Developers who want to get started with VMs but only want to put in the effort to get things set up once, then have the option to burn it all down and start again easily.
Vagrant also offers big benefits to teams by codifying the development environment as a set of configuration and provisioning scripts.
Because the scripts are completely custom, you'll still need to figure out what to install and how, which can take a little trial and error, but is only required once.
Ratings
Initial setup: ⭐⭐⭐
Easy to understand: ⭐⭐⭐
Working in a team: ⭐⭐⭐⭐
Local software matches production: ⭐⭐⭐
Switching versions: ⭐⭐⭐
Flexibility for advanced use cases: ⭐⭐⭐⭐
Getting started
https://github.com/neonhomer/vagrant-craft-3
Homestead
Homestead is a preconfigured Vagrant environment offered by the folks who made the Laravel PHP Framework. The technology being used is exactly the same as a normal Vagrant stack - they've just written the configuration and provisioning scripts for you so that you can get up and running within a few minutes!
As well as installing all of the required software for you, they've also made configuring the local domains for your different apps easy by including them in the setup scripts
For LAMP stack projects, this is the quickest and easiest way to get up and running with VM based local development.
Homestead also includes a built in method of running multiple versions of PHP side-by-side so that you can define which version of PHP each of your projects should use without having to adjust any configuration within the VM. That's pretty fancy!
The main negative for Homestead is that it is very prescriptive - it has to make a lot of assumptions in order for it to be able to do all of the nice things that it does. If you need to step outside of these assumptions you can (it's just a VM after all), but you risk things not work as seamlessly as they should. If you do have issues, fixing them can be a pain because you might end up having to venture into the layer of 'magic' that Homestead relies upon.
However, as with all the VM based local development environments that we're discussed, you always have the ability to destroy the entire thing and start again which only takes a few minutes.
Who should use this solution?
Developers who will be working predominantly on LAMP stack projects who don't care about how things are working as long as they work.
If you'll be venturing outside of PHP, or you need to work with arbitrary additional technologies, Vagrant might be a better option.
Ratings
Initial setup: ⭐⭐⭐⭐⭐
Easy to understand: ⭐⭐⭐
Working in a team: ⭐⭐⭐⭐
Local software matches production: ⭐⭐⭐
Switching versions: ⭐⭐⭐⭐
Flexibility for advanced use cases: ⭐⭐
Getting started
Local Development with Vagrant / Homestead
Setting Up Craft CMS 3 Local Development with Laravel Homestead
Docker
So far we've covered local stack installations and VM based solutions and we've found that each have their pros and cons.
Docker promises to offer a solution which eliminates the cons of both.
It does this by creating 'containers' which contain your Craft CMS project along with all of its dependencies, but completely isolated from your host software and filesystem. All without needing a full VM in which to run.
There are plenty of articles around which do their best to explain what docker is an how it works (it's complicated), but what we're interested in is how it makes to your local development easier...
Getting Docker installed is pretty easy, but getting your project up and running can be hard. There's a lot of new things to understand in order to become proficient and that can be a real drain on time and motivation when getting started, but once you're familiar with the new concepts things get a lot easier.
The compartmentalisation that Docker offers is second-to-none. Not only are your projects and their dependencies completely isolated from your host, they're also isolated from each other. This means that each project can have its own unique set of dependencies without ever having to worry about collisions or incompatibilities. You can also tailor these components to exactly match your production environment if you like.
Setting up Docker containers for your Craft projects is all done via scripts which you can store as part of your project's repo. These scripts are all that's required for another developer to get up and running with an identical environment. This makes teamwork a breeze - your teammates only have to install Docker, clone your project repo and run a single command to boot it up.
Running all of these projects fully isolated with their own dependencies must consume a lot of resources right? Well, actually no. Most containers will only consume a little more memory than the primary application within them. In the case of Craft projects that's likely to be Nginx and PHP-FPM and MySQL. In our day-to-day experience these will consume around 150MB memory whilst idling and very little CPU.
Finally it's worth mentioning that there's a Docker container for pretty much everything these days. Want to use Postgres? Don't install it! Just drop a Postgres container into your configuration. Want to test against a multi-node Elastic Search cluster? Don't install anything! Just drop it into your Docker configuration.
With the exception of the learning curve there's not a lot to dislike about using Docker as your local development environment, but it's worth mentioning a few Craft specific gotchas that you need to be aware of:
- In order to edit your project files while your project is running they need to exist on both your host's and the Docker container's filesystems. This is achieved using 'mounts' which have different performance penalties on different platforms. On macOS you might experience very slow page loads if your 'vendor' folder is mounted, however there are solutions.
- In order to get traffic into your containers they need to bind to ports on your machine (normally ports 80 and 443). If you try to start two project simultaneously that both try to bind to the same port, one of them will fail. You'll need to either bind each to a different port, or add a reverse proxy to distribute traffic.
Who should use this solution?
Developers who need to venture outside of the traditional LAMP stack and need to test complex architectures locally, or want to match their local development environment as closely as possible to production.
Anyone who wants to learn about Docker from the ground up - it is becoming more and more important for DevOps and hosting as well as local development.
At Servd, this is our current preference.
Ratings
Initial setup: ⭐⭐
Easy to understand: ⭐
Working in a team: ⭐⭐⭐⭐
Local software matches production: ⭐⭐⭐⭐⭐
Switching versions: ⭐⭐⭐⭐⭐
Flexibility for advanced use cases: ⭐⭐⭐⭐⭐
Getting started
A Craft CMS Development Workflow With Docker
Craft CMS in Docker Source Repo
DDEV
What Homestead does for VMs, DDEV does for Docker. By applying constraints and assumptions on the shape and requirements of your projects DDEV provides a PHP, docker-based development environment without having to manually configure everything.
This clearly saves a lot of time which would otherwise be spent on Docker's learning curve and can be a great stepping stone into that world.
DDEV is also cross-platform which can be a great benefit for teams which are spread across multiple operating systems.
If you need to set up more complex testing environments DDEV is extensible and users have shared configurations for several common additional services that you might like to add to your stack. However these are all defined and integrated using standard Docker configuration files, so you might end up needing to learn some fundamentals Docker anyway.
As is always the case with abstractions, the DDEV layer sitting above Docker adds additional complexity to the system overall which might introduce unexpected errors that are difficult to solve.
Who should use this solution?
Craft Developers who want to get started with Docker but don't want to immediately invest in its learning curve or need to get up and running quickly.
Ratings
Initial setup: ⭐⭐⭐⭐
Easy to understand: ⭐⭐
Working in a team: ⭐⭐⭐⭐⭐
Local software matches production: ⭐⭐⭐
Switching versions: ⭐⭐⭐⭐
Flexibility for advanced use cases: ⭐⭐⭐
Getting started
And the winner is...?
As it turns out, there is no clear cut winner. Instead there's a balancing act you need to play between several factors. None of the solutions we've looked at excel in every single category.
Our opinion is that you should use the solution that you feel comfortable using to create the most value. However we'd encourage you to explore the options, especially as web development best practices tend to move quite quickly.
So, what development environment are you using for your Craft CMS projects? Did anything in this article change your mind?
Once you've settled on a local development setup that works for you, you'll need somewhere to deploy your Craft CMS projects which is just as efficient.
Servd makes Craft CMS hosting simple to setup and maintain so you can focus on building awesome websites, rather than figuring out why live ones keep breaking.
