• Sage

Automate Sage 9 Deployment with DeployBot

DeployBot makes it easy to streamline your release process by automating Sage’s deployment from your Git repository to your web host.

Once configured, changes pushed to your theme’s Git repository will be deployed to your web host automatically, and your theme’s assets and Composer dependencies will be updated as needed.

HT to this gist by William Donahoe for inspiration and to Roots team member Julien Melissas for his help refining the process.

1. Connect a repository

In order to deploy your theme, DeployBot needs access to its Git repository. DeployBot currently supports repositories on GitHub and Bitbucket, as well as self-hosted repositories.

In DeployBot, go to Repositories and click "Connect a repository." Choose your repository type, connect your GitHub/Bitbucket account (if needed), and select your theme’s repository.

The repository you select should only include your theme, not WordPress itself, plugins, or anything else.

2. Create a container

A container is a temporary server environment used as a processing area between your repository and your web host to run any build steps that you don’t want to run on your host. In this case, you’re using to prepare your theme assets.

Sage 9 DeployBot container configuration
Container settings

  1. Click Settings → Containers and then click "Create a container"
  2. Name your container (e.g., "My Theme")
  3. Choose the appropriate existing container as your starting point (currently, Ubuntu 16.04)
  4. Enter the following in the Build commands field:
    curl -sL https://deb.nodesource.com/setup_8.x | bash -
    apt-get install -y nodejs
    npm install --global npm@latest yarn webpack
    

3. Create an environment

An environment specifies a) the servers to which you will be deploying b) what branch of your repository will be used for the deployment and c) what extra triggers will be run when your deploy happens.

  1. Select your repository in the Repositories menu, then click "Create environment & server"
  2. Enter a name for the environment (e.g., "Staging")
  3. Choose Automatic under Deployment Mode
  4. Choose the branch of your repository to deploy from
  5. Click "Save"

Automatic deployment means that whenever you push changes to the specified branch of your repository, DeployBot will automatically deploy those changes to the web server. Be careful with this when deploying to a production environment!

A common pattern is to have a branch on your repository that isn’t used for active development, but instead represents the state of your application in staging or production. When you want to deploy a set of changes to your staging or production environment, merge them from a development, feature, or release branch into your staging or production branch.

4. Choose a deployment option and set up your server

The deployment option is the method DeployBot will use to deploy your them to your web server. When you finish creating your first environment, DeployBot will automatically prompt you to choose a deployment method and then configure your server.

If you don’t see this screen automatically, navigate to Repositories → (your repository) → (your environment) and click "Add a server."

Sage 9 DeployBot server configuration
Server settings

  1. Select the "SFTP" deployment option
  2. Enter a name for your server (e.g., "Staging Server")
  3. Enter your SFTP host name or IP address and port number
  4. Enter the path to your theme folder on the server
  5. Enter your SFTP username and password
  6. In the Compile, compress, or minimize your code section:
    • Select the container your created
    • Enter yarn build:production in the code field.
  7. In the Exclude certain paths from being uploaded section, add the following to the text area:
    .cache-loader
    .git
    node_modules
    /resources/assets
    .editorconfig
    .eslintrc.js
    .gitignore
    CHANGELOG.md
    CODE_OF_CONDUCT.md
    LICENSE.md
    package.json
    phpcs.xml
    README.md
    yarn.lock
    
  8. In the Run shell commands after deployment section, enter composer install --no-dev in the code field.
  9. In the Advanced options section:
    • Check the "Use parallel uploading" box
    • Enter yarn in the "Cached build commands" code field
  10. Click "Save"

Running yarn build:production during this process means that your theme will be deployed with the final, production-ready assets included.

The "Exclude certain paths from being uploaded" option prevents unnecessary files from being copied to your server (particularly the node_modules folder and the unprocessed versions of your assets, which can get quite large).

Running composer install --no-dev on your web server installs the dependencies that Sage needs to work (but not the dependencies only needed for development). If your web server doesn’t support Composer (e.g., WP Engine):

  1. Move composer install --no-dev to the "Cached build commands" field
  2. Update your container’s build commands to:
    add-apt-repository ppa:ondrej/php
    curl -sL https://deb.nodesource.com/setup_8.x | bash -
    apt-get install -y php7.2 php7.2-common php7.2-mbstring php7.2-xml gcc g++ make nodejs zip unzip php7.2-zip composer
    a2enmod php7.2
    npm install --global npm@latest yarn webpack
    

Parallel uploading speeds up deploys by transferring multiple files simultaneously in different SFTP connections.

Adding yarn to your cached build means that it will only run to install dependencies when your package.json file has changed, instead of during every deployment.

You’re done! Test your deployment.

To run your deployment for the first time, go to your repository page in DeployBot and click the "Deploy" button to the right of your environment. Enter a message to describe the deployment, and click "Start deployment."

Your first deploy may some time; deploys will be faster on secondary runs, as some container and dependency setup steps won’t need to run for every deployment and DeployBot only copies over the files that have changed.

Since you selected automatic deployment, you can also trigger a deploy by pushing a new commit to the repository branch you selected.


Please note that using SFTP to deploy your theme may result in downtime while the files are being uploaded. This is true of any deployment method that updates in-use files in their live location, rather than uploading a new release behind the scenes and then switching the live site to use that new release once the deployment has successfully completed.

This might occur, for example, if File A in your theme expects File B to exist, but File B is uploaded after File A. In that case, your site could go down (or otherwise work incorrectly) for the time between when File A is uploaded and File B is uploaded. While this will likely be minimal, you should find a different deployment method (e.g., deploying with Trellis) for sites where this risk is unacceptable.

Start the discussion on Roots Discourse

Join over 5,800 subscribers on our newsletter to get the latest Roots updates, along with occasional tips on building better WordPress sites.

Looking for WordPress plugin recommendations, the newest modern WordPress projects, and general web development tips and articles?

“Easily the best WordPress email I get.” Colin OBrien

Follow us on Twitter @rootswp

Ready to checkout?