We use cookies to make your viewing experience better. By accepting you consent, you agree to our Cookie policy

Improve your Craft CMS skills

Is It Possible To Run Craft CMS Locally?

10 min read
Shape April 2022 HR 28

Running Craft CMS locally is key for developers. But is it actually possible to set up a performant local Craft environment? With the right local web stack, database configuration, and automation, developers can replicate production locally for much faster builds. This guide covers step-by-step how to get Craft CMS running smoothly on your local machine.

Yes, it is possible to run Craft CMS locally for development by setting up a local web server like MAMP or XAMPP, configuring a MySQL database, installing dependencies via Composer, and accessing the site through a virtual host. This allows developers to build Craft sites and test changes prior to deploying to production.

Setting up a Local Environment for Craft CMS

Choosing a Local Web Server

When setting up Craft CMS for local development, the first step is choosing a local web server solution that can run PHP and MySQL. Popular options on Windows include WAMP, XAMPP and Laragon.

For Mac users, MAMP is a common choice that bundles Apache, MySQL and PHP in one installer. There's also Laravel Valet which offers a simplified development environment using Nginx.

On Linux, it's fairly straightforward to install PHP, MySQL and a web server like Apache or Nginx from the package manager. Docker can also be used on Linux, Windows and Mac to spin up isolated containers running the required services.

The advantage of integrated packages like XAMPP, WAMP and MAMP is that they handle the configuration of PHP, MySQL and the web server for you. Laragon also offers additional tools like Git, Node.js and Redis out of the box. With Docker, you can precisely mimic your production environment locally.

Ultimately the ideal local dev environment will depend on your operating system and specific needs. The key is choosing a solution that runs PHP 7.0+ and MySQL 5.5+ to meet Craft's requirements.

Configuring the Craft CMS Database

Once you have a local web server up and running, the next step is configuring MySQL and setting up a database for Craft CMS.

If using XAMPP/WAMP/MAMP, MySQL will already be installed and running. You may need to create a database and user account manually though. With Laragon and Valet, databases can be created through the control panel.

The Craft database can be created through any MySQL GUI tool like PHPMyAdmin, or directly via the MySQL console/command line. Make sure to use a descriptive name like craftcms.

Next, import the Craft database schema to initialize all the core tables. This is either contained in craft/storage/db.sql, or can be downloaded from a fresh Craft release.

With the database ready, update Craft's .env file with the database credentials. Define the DB_SERVER, DB_USER, DB_PASSWORD, DB_DATABASE and DB_TABLE_PREFIX values. The prefix helps when sharing a database between multiple installs.

Proper database configuration ensures Craft can connect and leverage MySQL for storing all its data, assets, entries and custom tables.

Installing Composer Dependencies

Now that the local server and database is prepared, the final step is using Composer to pull in Craft's dependencies and manage plugins.

Composer is the package manager for PHP that handles dependency resolution, autoloading, and versioning. It streamlines installing Craft CMS and all its PHP packages.

After Composer is installed globally, run composer install from the Craft project directory. This will read composer.json and download the correct versions of Craft, Twig, Yii and other libraries.

Composer can also initialize Git repositories to track changes. The composer.lock file locks dependencies to specific versions for consistency across environments.

Plugins and modules can be required in composer.json or installed via composer require author/plugin-name. Composer enables easily managing all of Craft's dependencies.

With all dependencies installed through Composer, the local Craft CMS environment should now be fully configured and ready for theme development, plugin testing, and site building.

Composer, a local web server, and MySQL provide the foundation.

Craft CMS Setup and Configuration

Craft CMS Folder Structure

When installing Craft CMS, it follows a specific folder structure to organize all the core files, templates, modules and web root. Understanding this structure helps when building out a Craft website.

The craft folder contains all the Craft source code, config files and utilities for managing the system. This includes things like app, config, modules, templates, translations and vendor folders.

The modules folder houses any custom modules that extend Craft's functionality. And the templates folder contains all the Twig templates that make up the front-end design.

The webroot folder represents the document root that the web server points to. This contains the main index.php file along with assets, resources and the front-end templates rendered from Twig.

An additional Storage folder outside of webroot stores things like compiled templates, asset transforms, and any uploaded files. The separation of webroot and storage enhances security.

Within the config folder, Craft's system configuration files like general.php and .env define everything from site name to database credentials.

So in summary, Craft CMS separates source code, modules, templates and configuration from the webroot for optimal organization. Understanding this structure helps when developing.

Craft CMS Configuration

Craft CMS has several configuration options that can be defined for setting up and customizing a site. The main ways to configure Craft include .env variables, config files, and overrides.

The .env file located in the config folder sets many foundational config values like database credentials, site name, environment type, and security keys. This is vital to get correct.

Individual configuration files like general.php and db.php in config/app allow configuring things like caching, logging, email, routes and more.

Local configuration overrides can also customize config values only when running Craft locally. This prevents accidental commits of local-only config.

Things like the site name, timezone, caching settings, volumes and more can be configured through these various options. They allow the CMS to be tailored for specific environments.

Craft also makes most configuration available through the friendly control panel UI. But it's useful to understand how to leverage .env, config files and overrides to configure Craft.

Serving Craft CMS Locally

When running Craft CMS locally for development and testing purposes, the CMS needs to be accessible through a local virtual host and document root.

Within the web server configuration like Apache or Nginx, setup a local domain like craft.test that points to the webroot folder of your Craft install.

This allows accessing the CMS frontend at a URL like http://craft.test instead of through a filesystem path. It mimics how the site runs on actual domains.

For additional convenience, consider using tools like Laragon, Valet or MAMP Pro that automatically handle virtual hosts and default to http://projectname.test URLs for all projects.

To access the Craft control panel, visit the /admin path off the local domain. So for example http://craft.test/admin with the right credentials.

Setting the document root and local virtual host enables properly accessing and testing Craft CMS locally during theme and plugin development, before pushing live.

Craft CMS Local Development Workflows

Version Control with Git

Git is a vital tool for version controlling Craft CMS projects during local development. It allows tracking changes to files, collaborating on code, and deploying site updates.

With a local Craft project initialized as a Git repository, all updates to templates, modules, config files and more can be committed. This captures the change history and progression of the project.

Developers can create feature branches to isolate new work, eventually merging it back into main/master when complete. Git enables working on enhancements and improvements without impacting the stable main branch.

Once local development on new features is done, the commits can be pushed to a central repository like GitHub for collaboration, testing and deployment.

GitHub integration allows developers to do pull requests, code reviews, and discuss changes before merging into the definitive repository. This improves team workflows.

Version control with Git fundamentally improves Craft CMS development, helping track changes, enable collaboration, and streamline deployment of site updates.

Debugging Issues

While building a Craft CMS site locally, developers inevitably run into bugs, errors and unexpected issues that require debugging. Common problems include:

  • File permission errors preventing Craft from accessing logs, caches or compiled templates.

  • Database connectivity issues due to incorrect credentials or MySQL service failures.

  • Missing PHP extensions leading to 500 errors when running certain plugins/modules.

  • Frontend rendering issues from bugs in new custom Twig code or plugins.

Debugging follows a methodical process - replicating the issue, isolating variables, reviewing Craft logs, and enabling dev mode for more verbose logging.

For database and SQL issues, tools like PHPMyAdmin provide visibility into queries and syntax errors. Checking the Craft debug toolbar helps spot problems.

Enabling Twig debugging in Craft settings is useful for pinpointing template errors. Frontend JS errors appear right in the browser console.

Patience and a systematic approach is key for diagnosing and debugging local Craft problems. The exact issue is usually revealed after some sleuthing.

Automation with Task Runners

Automating common development workflows is key for streamlined Craft CMS projects. Task runners like Gulp, Grunt and Webpack execute repetitive processes.

For front-end asset processing, Gulp can automatically compile Sass into CSS, transform images, bundle and minify JavaScript, and more.

These tasks can run on file changes to immediately update assets during development. Optimization steps are automated.

Webpack bundles modules and dependencies, allowing using NPM packages and modern JavaScript in Craft sites. The bundles integrate cleanly into Twig templates.

For backend processes, task runners can watch for Twig changes and instantly recompile templates. Git commits and deployments can also be automated.

Task runners integrate into version control workflows, running builds and tests before merging feature branches. This filters out errors.

By leveraging task runners like Gulp and Webpack, Craft CMS projects can automate mundane tasks and streamline development. The entire workflow becomes more productive.

Launching Live from Local Craft CMS

Once a Craft CMS site has been fully built and tested locally, the time comes to launch it live to a production environment. This involves several steps to ensure a smooth transition:

First, thoroughly test the site locally across different browsers and devices. Catch any bugs beforehand, since fixing issues is harder post-launch. Enable Craft's dev mode during testing for more verbose logging.

With Git, push the code changes from local development to the production server. For additional safety, consider tagging a release before deploying live. This allows easing back if something breaks.

On the production server, run composer install to sync any new plugins, modules or dependencies. Migrate the production database schema using ./craft migrate/all.

Update environment variables like database credentials in .env to match production. Clear all caches in the Craft CP to purge any outdated frontend artifacts.

Optionally place the site in maintenance mode, swapping the homepage for a simple "Under maintenance" message during the launch. This avoids exposing partial updates.

Point the live domain DNS to the new production server hosting Craft CMS. With DNS propagated, the site should now be publicly accessible.

With the production environment fully prepped, take the site live by disabling maintenance mode. Monitor the launch for any hiccups like CSS/JS conflicts.

Post-launch, re-index the search in Craft, run any new migrations, and re-save entries to trigger asset transforms. Re-test forms and front-end flows.

A clean Git tag and composer.lock ensures the same code runs on production as built locally. Migrations and environment configs avoids database snags.

Careful testing and planning allows smoothly launching a locally developed Craft CMS site live. Slow rollouts with maintenance modes further de-risk transitions to production.

Shape April 2022 HR 202
Andy Golpys
- Author

Andy has scaled multiple businesses and is a big believer in Craft CMS as a tool that benefits both Designer, Developer and Client. 

Show us some love
Email Us
We usually reply within 72 hours
Agency Directory
Submit your agency
Affiliate Partners
Let's chat