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.
- Click Settings → Containers and then click "Create a container"
- Name your container (e.g., "My Theme")
- Choose the appropriate existing container as your starting point (currently, Ubuntu 16.04)
- 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.
- Select your repository in the Repositories menu, then click "Create environment & server"
- Enter a name for the environment (e.g., "Staging")
- Choose Automatic under Deployment Mode
- Choose the branch of your repository to deploy from
- 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
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."
- Select the "SFTP" deployment option
- Enter a name for your server (e.g., "Staging Server")
- Enter your SFTP host name or IP address and port number
- Enter the path to your theme folder on the server
- Enter your SFTP username and password
- In the Compile, compress, or minimize your code section:
- Select the container your created
yarn build:productionin the code field.
- 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
- In the Run shell commands after deployment section, enter
composer install --no-devin the code field.
- In the Advanced options section:
- Check the "Use parallel uploading" box
yarnin the "Cached build commands" code field
- Click "Save"
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).
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):
composer install --no-devto the "Cached build commands" field
- 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.
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.