[Deprecated] Use ItinerisLtd/tiller-circleci-orb instead.

---

Tiller CircleCI

Deploy Trellis, Bedrock and Sage via CircleCI.

• Requirements
• What's in the Box?
• File Structures
  • Official
  • Typist Tech
• SSH Key
  • GitHub
  • CircleCI
  • Trellis
• Ensure Trellis Deploys the Correct Commit
• Ansible Vault Password
• Caching
  • Ansible Galaxy Roles
• Security
  • SSH Keys
  • Log Level
  • Every Software can be Hacked
• FAQ
  • Is it a must to merge Trellis pull request #997?
  • What is in the itinerisltd/tiller docker image?
  • Is it a must to use all Trellis, Bedrock and Sage?
  • Is it a must to use CircleCI?
  • Is it a must to use GitHub?
  • It looks awesome. Where can I find some more goodies like this?
  • This package isn't on wp.org. Where can I give a ⭐⭐⭐⭐⭐ review?
• Support
  • Why don't you hire me?
  • Want to help in other way? Want to be a sponsor?
• Author Information
• Feedback

Requirements

• Trellis with pull request #997 merged
• CircleCI
• (Optional) Bedrock 31c638f or later
• (Optional) Sage 9.0.1 or later

What's in the Box?

.circleci/config.yml examples of running Trellis deploys to production whenever master branch is pushed.

File Structures

Tiller CircleCI comes with 2 different config.yml examples. They are expecting different Trellis and Bedrock structures.

Official

Use config.yml if your directory structure follow the official documents:

example.com/      # → Root folder for the project
├── .git/         # → Only one git repo
├── trellis/      # → Your clone of roots/trellis, directory name must be `trellis`
└── site/         # → A Bedrock-based WordPress site, directory name doesn't matter

To install config.yml:

1. Set up SSH keys, Ansible Vault password and commit Trellis changes described in the following sections
2. Copy, review, change and commit config.yml to .circleci/config.yml

Typist Tech

At Typist Tech, I use a opinionated project structure:

• separate Trellis and Bedrock as 2 different git repo
• name the Bedrock-based WordPress site directory more creatively, i.e: bedrock

example.com/      # → Root folder for the project
├── bedrock/      # → A Bedrock-based WordPress site, directory name doesn't matter
│   └── .git/     # Bedrock git repo
└── trellis/      # → Clone of roots/trellis, directory name must be `trellis`
    └── .git/     # Trellis git repo

See: roots/trellis#883 (comment)

To install config.typisttech.yml:

1. Set up SSH keys, Ansible Vault password and commit Trellis changes described in the following sections
2. Push the Trellis repo
3. Copy, review, change and commit config.typisttech.yml to <bedrock>/.circleci/config.yml

---

SSH Key

You need a robot user for deployment. In this example, we will use a GitHub machine user account as our robot. For simplicity, this robot uses the same SSH key pair to access both GitHub private repos and the web server.

GitHub

1. Sign up a machine user(e.g: mybot) on GitHub
2. Grant mybot read access to all necessary private repos

CircleCI

On CircleCI's web console:

1. Link your project repo
2. Go to Settings » Checkout SSH Keys
3. Delete the deploy key
4. Create a user key (as mybot)

Learn more about deploy keys and user keys on CircleCI Checkout SSH Keys settings page.

Trellis

1. Add the SSH key to web server

    # group_vars/<env>/users.yml
    users:
      - name: "{{ web_user }}"
        groups:
          - "{{ web_group }}"
        keys:
          - https://github.com/human.keys
   +      - https://github.com/mybot.keys
      - name: "{{ admin_user }}"
        groups:
          - sudo
        keys:
          - https://github.com/human.keys

2. Re-provision $ ansible-playbook server.yml -e env=<env> --tags users

Ensure Trellis Deploys the Correct Commit

Normally, Trellis always deploy the latest commit of the branch. We need a change in group_vars/<env>/wordpress_sites.yml:

 # group_vars/<env>/wordpress_sites.yml
 wordpress_sites:
   example.com:
-    branch: master
+    branch: "{{ site_version | default('master') }}"

Ansible Vault Password

Unlike other environment variables, Ansible Vault password should never be stored as plaintext. Therefore, you should add VAULT_PASS via CircleCI web console instead of commit it to .circleci/config.yml.

The examples assume you have defined vault_password_file = .vault_pass in ansible.cfg as the official document suggested.

 # ansible.cfg
 [defaults]
+vault_password_file = .vault_pass

To use another vault password filename:

 - run:
     name: Set Ansible Vault Pass
-     command: echo $VAULT_PASS > .vault_pass
+     command: echo $VAULT_PASS > .my_vault_password_file
     working_directory: trellis

Using Ansible Vault to encrypt sensitive data is strongly recommended. In case you have a very strong reason not to use Ansible Vault, remove the step:

-- run:
-    name: Set Ansible Vault Pass
-    command: echo $VAULT_PASS > .vault_pass
-    working_directory: trellis

Caching

By default, yarn packages, Ansible Galaxy roles and Trellis' temporary build directory are cached. It speeds up the build significantly. This is optional and you can customize the cache behaviour.

Ansible Galaxy Roles

Due to the way $ ansible-galaxy install works, you can't cache trellis/vendor when installing a role from its git/hg repo branch:

# Good: Install from Ansible Galaxy
- src: TypistTech.trellis-cloudflare-origin-ca
  version: 0.6.0

# Good: Install from Ansible Galaxy
# Defaults to latest tag when no version specified
- src: TypistTech.trellis-cloudflare-origin-ca

# Good: Not install from version control
- src: TypistTech.trellis-cloudflare-origin-ca
  version: 0.6.0

# Good: Tag name is *linked* to a specific commit hash
- src: https://github.com/TypistTech/trellis-cloudflare-origin-ca
  version: 0.6.0

# Good: Commit hash
- src: https://github.com/TypistTech/trellis-cloudflare-origin-ca
  version: 58785793908f67480cae3729ec5900739e0d5c66

# Bad: Branch name
- src: https://github.com/TypistTech/trellis-cloudflare-origin-ca
  version: master

# Bad: Defaults to `master` branch when no version specified
- src: https://github.com/TypistTech/trellis-cloudflare-origin-ca

If you must install a role from its git/hg repo branch:

-- restore_cache:
-    key: v1-ansible-galaxy-{{ checksum "trellis/galaxy.yml" }}
 # ...
-- save_cache:
-    key: v1-ansible-galaxy-{{ checksum "trellis/galaxy.yml" }}
-    paths:
-     - trellis/vendor

Security

SSH Keys

• Grant the machine user read access to necessary private repo only
• Do not grant the machine user any write or admin access to any repo
• Add the machine user key to web_user only
• Do not add the machine user key to admin_user

Log Level

Note that the use of the no_log attribute does not prevent data from being shown when debugging Ansible itself via the ANSIBLE_DEBUG environment variable.

--- Ansible Docs

By default, verbose level is set to maximum. Sensitive data might be logged.

To disable verbose mode:

 - run:
     name: Install Ansible Galaxy Roles
-    command: ansible-galaxy install -r galaxy.yml -vvvv
+    command: ansible-galaxy install -r galaxy.yml
    working_directory: trellis
 - deploy:
-    command: ansible-playbook deploy.yml -e env=$SITE_ENV -e site=$SITE_KEY -e site_version=$CIRCLE_SHA1 -vvvv
+    command: ansible-playbook deploy.yml -e env=$SITE_ENV -e site=$SITE_KEY -e site_version=$CIRCLE_SHA1
     working_directory: trellis

Every Software can be Hacked

If you discover any security related issues, please email tiller-circleci@typist.tech instead of using the issue tracker.

FAQ

Is it a must to merge Trellis pull request #997?

Yes and no.

It is required for compiling Sage assets. If you don't use Sage:

• you can omit pull request #997
• you might have to checkout bedrock source code by yourself

What is in the itinerisltd/tiller docker image?

It is maintained by the Tiller project. Read its readme to learn more.

Is it a must to use all Trellis, Bedrock and Sage?

No, you don't need all of them. Only Trellis is required.

Is it a must to use CircleCI?

No. The original Tiller project uses AWS CodeBuild. You can tweak it to run on different CI providers.

Is it a must to use GitHub?

No. GitHub is just an example.

It looks awesome. Where can I find some more goodies like this?

• Articles on Typist Tech's blog
• Tang Rufus' WordPress plugins on wp.org
• More projects on Typist Tech's GitHub profile
• Stay tuned on Typist Tech's newsletter
• Follow Tang Rufus' Twitter account
• Hire Tang Rufus to build your next awesome site

This package isn't on wp.org. Where can I give a ⭐⭐⭐⭐⭐ review?

Thanks!

Consider writing a blog post, submitting pull requests, donating or hiring me instead.

Support

Love Tiller CircleCI? Help me maintain it, a donation here can help with it.

Why don't you hire me?

Ready to take freelance WordPress jobs. Contact me via the contact form here or, via email info@typist.tech

Want to help in other way? Want to be a sponsor?

Contact: Tang Rufus

Author Information

Tiller CircleCI is a Typist Tech project created by Tang Rufus.

Special thanks to Itineris Limited who hired me to create the original Tiller project.

Special thanks to the Roots team whose Trellis make this project possible.

Full list of contributors can be found here.

Feedback

Please provide feedback! We want to make this library useful in as many projects as possible. Please submit an issue and point out what you do and don't like, or fork the project and make suggestions. No issue is too small.