How to use Docker for Easy Perch CMS Development

Web Design Dev Ops All


Docker is great! It allows you to build and share consistent environments across different machines running different operating systems without having to take into account any specific environment quirks. If you have Docker installed and an application is packaged into a Docker container then you can be sure it will work on your machine too! Neat.

But how does this apply to a Perch developer I hear you ask? Well, I have built a Docker Compose project that allows you to use the full power of Docker when starting your next Perch Project. No more LAMP, MAMP or Vagrant required. I'll walk you through the 3 simple steps I use when creating a new Perch CMS development environment on my local machine.

The Quick and Dirty

For the initial setup it is best to just dive straight in. You can clone the project repository from Github and follow the detailed guide. It all boils down to these 3 simple steps:

1) Clone the Perch Docker Compose repository from the latest release and Install a new Perch CMS folder in the /src/my_project/ directory

2) Update the Docker Compose .env file and your /etc/hosts file

3) Deploy the Docker containers

Simple! Please follow the guide for detailed instructions on how to install Docker and setup your Perch Docker Compose project. 

Example Workflow with Perch Docker Compose

Once you have completed the initial set up and have Docker and Docker Compose installed on your machine then starting a new Perch CMS project will take just minutes. To demonstrate this I am going walk through how I utilise Docker to setup a local Perch development for a new client - "".

1) Install the files

Either git clone the Perch Docker Compose repository or download the zip file to a new directory in your workspace:

mkdir exampledomain
git clone --branch v1.0.0 exampledomain

Next, create a new directory inside the /exampledomain/src/ directory to contain your project files:

cd ~/exampledomain/src/
mkdir exampledomain

Now, download a fresh copy of Perch Runway and add the Perch directory into exampledomain/src/exampledomain/ directory.

At this point it is best to create a brand new git repository to contain your Perch website code. This enables you to manage the files within the /src/exampledomain directory as a seperate git repository, isolated from the Perch Docker Compose project. Your final repository structure should look like this:

2) Update Configuration files

Copy the contents of the env.example file into a new file called .env and update the values for your new project. For example:

Finally, update your /etc/hosts file to point localhost at the new domain name:

3) Run Docker Compose

Open a  terminal window in the root of the project and run docker-compose up --build -d

This will build and run 4 docker containers. One for MySQL, Perch, NGinx and phpMyAdmin.

That's it!

Your new Perch project is up and running! You can view the site by navigating to http://exampledomain.local/perch/ or view phpMyAdmin at http://exampledomain.local:8080

Finally, enter the database connection settings from the .env file to finish the Perch CMS setup. The name of the database server should be "database". 


Hopefully this example has demonstrated how you can streamline your Perch CMS workflow into 3 simple steps with Docker Compose. If you found this helpful you might also enjoy my blog post detailing how to Automatically Push Changes To Your Live Site With GitHub Actions.

Found a bug or having trouble with the setup? Please raise a Gthub Issue and I will try to help ASAP.


← Back to Blog

Writing blog posts is thirsty work! If you found this helpful feel free to buy me a beer...