Login
  • Updated

Automatically Deploying Your WordPress Site with CircleCI

By integrating with CircleCI, you can easily deploy your WordPress site whenever new changes occur, all while maintaining your existing CircleCI workflows.

In this article, we'll show you how to deploy your WordPress site to Pagely by utilizing the Pagely Deployment CircleCI orb.

Initial Setup

Before continuing, there are a few things you'll want to check over.

Always Test In Staging First

Any time changes are made, especially when it comes to automation, you'll want to make sure things are working well in a staging environment before deploying them to production. The same goes for the process outlined in this article. If not, a misconfiguration could result in data loss!

Setting Up Your Git Repository

Although this isn't directly related to CircleCI, it's still important to make sure that the files that exist in your deployment workflow step accurately match what's in your production site.

Since the deployment will overwrite everything in your deployment destination with whatever is in the source location, any uncommitted changes on the destination may (and usually will) be lost.

For more information on how your source should be set up, see our article on setting up git repositories for automatic deployments.

Creating a New Integration in Atomic

To streamline the process of creating credentials for interacting with CircleCI and other 3rd-party services, Pagely includes an easy-to-use interface for creating integrations.

Before continuing to the next section, you'll need to have created an integration inside Atomic. To learn more, see our article on creating a new integration in Atomic.

Setting Up Required Environment Variables

To use Pagely's WordPress deployment CircleCI orb, there are a few environment variables you'll need to set up before a deployment can run. Here's how to set them up:

  1. Start by logging into your CircleCI account and accessing the project that you want to deploy from.
  2. On the top-right of the screen, click on the Project Settings button to access the settings area.

    Screenshot: CircleCI deployment click project settings button
  3. On the left side menu of your project settings, click on Environment Variables, then click on the Add Environment Variable button to add a new variable.

    Screenshot: CircleCI project settings add environment variable
  4. Since these variables are going to be read by the deployment orb, you'll need to name them accordingly. Let's start by adding the integration ID.

    Inside the Name field, set your variable's name to PAGELY_INTEGRATION_ID.

    Screenshot: CircleCI environment variables name field
  5. For the Value field, you'll enter your Integration ID from the integration you created inside Atomic.

    Screenshot: CircleCI environment variables value field
  6. With your field values now in place, click the Add Environment Variable button to add the variable.

    Screenshot: CircleCI add environment variable button
  7. Next, you'll need to add another variable. Follow the same process, but this time, name it PAGELY_INTEGRATION_SECRET and use your Integration Secret from Atomic as the value.

    Screenshot: CircleCI add environment variable integration secret fields

That's all the variables we need for the deployment. In the next section, we'll go over how to configure your pipeline.

Configuring Your CircleCI Pipeline

Now that your environment variables are in place, it's time to take a look at your CircleCI pipeline configuration.

CircleCI pipelines are located within .circleci/config.yml at the root of your repository. If you don't already have one, go ahead and create it now.

For more information on creating CircleCI configurations, see the CircleCI configuration documentation.

Here's what our example config.yml file looks like:

version: 2.1
orbs:
  pagely-deploy: pagely/orb-deploy@1.0.0
jobs:
  build:
    machine:
      image: ubuntu-2004:202010-01
    steps:
      - checkout
      - persist_to_workspace:
          root: /home/circleci/project
          paths:
            - .
workflows:
  deploy:
    jobs:
      - build
      - pagely-deploy/deploy:
          app_id: '12345'
          deploy_dest: /httpdocs
          requires:
            - build

If you don't already have an existing configuration, feel free to copy this entire example and tweak it to match your settings.

Let's take a look at what's going on inside the example.

Orb Configuration

orbs:
  pagely-deploy: pagely/orb-deploy@1.0.0

The first setting within our example is the orbs section. This is where we are defining the Pagely deployment orb for later use inside the workflow.

Job Configuration

jobs:
  build:
    machine:
      image: ubuntu-2004:202010-01
      steps:
        - checkout
        - persist_to_workspace:
            root: /home/circleci/project
            paths:
              - .

Inside this section, we're defining a job step that will run inside the workflow. This defines the virtual machine that it will be running on, as well as the steps that the job will take.

The first step is the checkout step, which is exactly what you would expect - it pulls down the repository.

The second step is an important one - it allows the checked out code to persist within the workspace for the next job. Since the orb is running after this step, we need the data to be persistent. Otherwise, the orb wouldn't have any files to process!

Workflow Configuration

workflows:
  deploy:
    jobs:
      - build
      - pagely-deploy/deploy:
          app_id: '12345'
          deploy_dest: /httpdocs
          requires:
            - build

The workflows section is the part that does the work. Inside our example, we have a single workflow named deploy. That workflow runs two jobs - build and the deployment orb.

As we mentioned in the previous section, the first job performs a checkout of the repository, then persists the data inside the workspace for future jobs.

The second job is the Pagely deployment CircleCI orb. Internally, it runs a Docker container that handles all of the heavy lifting required to sync the working directory with the destination. Inside it, we've defined a couple of parameters that we'll go over now.

app_id

This parameter is your Pagely app ID. When setting up your deployment, you'll need to change this to match the app ID of your destination.

To find your app ID, just log into Atomic and check your app's details page.

deploy_dest

This parameter defines where the files will be deployed to. In our example above, we've defined this as /httpdocs, which would deploy to the WordPress site's root.

If you're deploying only a specific plugin or theme, you'll want to change this to match your plugin/theme's directory. For example, if you were deploying a theme named my_example_theme, then you would set the destination path to /httpdocs/wp-content/themes/my_example_theme.

For more information on deployment destinations, take a look at our deployment Docker image reference.

requires

This parameter is a simple, but important one. By setting this parameter, we're telling the workflow that it needs to complete the build step before this step can begin. Without it, there is a risk of data loss, since the checkout may not be complete before the deployment takes place.

Finishing Up

After your configuration is built, all you need to do is commit the file. With the configuration in place, any commits will trigger a deployment, making sure your files are always up to date.

As with any major change, you'll want to check over your site to ensure that everything went smoothly. When you're ready to set up your production site for automatic deployments, all you'll need to do is adjust the app ID to match the new destination.

Related articles