Trellis-CLI - Modern WordPress LEMP Stack Practices

Trellis-CLI is a command-line interface (CLI) to create or manage Trellis, Wordpress deployment, projects via the trellis command. Trellis is a tool that helps you create and manage WordPress LEMP stack using modern server development practices.

How To Install Trellis-CLI

Here are some of the most common methods to install Trellis in different operating systems:

Homebrew (macOS and Linux)

If you have Homebrew package manager installed on your macOS or Linux system, you can use the below command:

brew install roots/tap/trellis-cli

This will download and install the latest stable version of Trellis and make it available in $PATH.

Installation Script

Trellis project also provide a direct installation script. This method works on any system that has curl and bash installed.

Run the following command in your terminal:

curl -sL https://roots.io/trellis/cli/get | sudo bash

This will download the latest release of Trellis-CLI, unpack it, and move it to /usr/local/bin/trellis by default. You can also specify a different installation directory by using the -b flag, like this:

curl -sL https://roots.io/trellis/cli/get | sudo bash -s -- -b /path/to/my/bin

Manual Install

If you prefer to manually download and install Trellis-CLI from the official binaries provided for your system, you can follow these steps:

1. Download the latest release for your processor architecture.
2. Unpack with tar -zxvf trellis_1.21.0_Linux_x86_64.tar.gz command.
3. Find the trellis binary in the unpacked directory, and move it to its desired destination (eg: mv trellis_1.21.0_Darwin_x86_64/trellis /usr/local/bin/trellis)
4. Make sure the above path is in your $PATH variable.

$ trellis --help
Usage: trellis [--version] [--help] <command> [<args>]

Available commands are:
    alias            Generate WP CLI aliases for remote environments
    check            Checks if the required and optional Trellis dependencies are installed
    db               Commands for database management
    deploy           Deploys a site to the specified environment
    dotenv           Template .env files to local system
    down             Stops the Vagrant machine by running 'vagrant halt'
    droplet          Commands for DigitalOcean Droplets
    exec             Exec runs a command in the Trellis virtualenv
    galaxy           Commands for Ansible Galaxy
    info             Displays information about this Trellis project
    init             Initializes an existing Trellis project
    key              Commands for managing SSH keys
    logs             Tails the Nginx log files for an environment
    new              Creates a new Trellis project
    open             Opens user-defined URLs (and more) which can act as shortcuts/bookmarks specific to your Trellis projects.
    provision        Provisions the specified environment
    rollback         Rollback the last deploy of the site on the specified environment
    shell-init       Prints a script which can be eval'd to set up Trellis' virtualenv integration in various shells.
    ssh              Connects to host via SSH
    up               Starts and provisions the Vagrant environment by running 'vagrant up'
    valet            Commands for Laravel Valet
    vault            Commands for Ansible Vault
    xdebug-tunnel    Commands for Xdebug tunnel

Experimental commands:
    vm    Commands for managing development virtual machines

Initializing a new Trellis project

After you have installed Trellis-CLI, you can use it to create a new Trellis project with single command:

trellis new my-site.com

This will ask a few questions and set-up a virtual environment. It will create a new directory called my-site.com with the following structure:

my-site.com/      # - Root folder for the project
|-- trellis/         # - Your clone of Trellis repository
|-- site/            # - A Bedrock-based WordPress site
    |-- config/
        |-- environments/    
    |-- web/
        |-- app/     # - WordPress content directory (themes, plugins, etc.)

The directory trellis contains all the configuration files and scripts for managing your WordPress deployments and workflow. The directory site contains a Bedrock-based WordPress site that follows modern development practices.

Creating a local development environment using Vagrant

Trellis provides a consistent development environment using Vagrant, a tool that allows you to create and manage virtual machines with a simple configuration file.

Make sure vagrant is installed and available in $PATH variable. Trellis integrates Vagrant with Ansible provisioning.

Trellis-CLI makes it easy to start and stop your Vagrant machine with one command:

trellis up

This will create and boot a virtual machine that runs Ubuntu 20.04 LTS with all the necessary software to run your WordPress site, such as Nginx, PHP, MySQL, Fast-CGI, etc.

You can access the site from browser, or use wp-cli to manage your site from the command line. Furthermore, You can get a shell to the vm with these command:

trellis vm shell

# or

trellis ssh

To stop and free up resources your Vagrant machine, you can use the following command:

trellis down

You can use trellis vm command to pause the machine, or trellis destroy to delete it completely.

Deploying your site to a production server on DigitalOcean

When you are ready to deploy your site to a production server, Trellis-CLI can help you create and provision a server on DigitalOcean with one command:

trellis droplet create my-site.com production

You are required to have a DigitalOcean account and an API token to use this command.

Once your droplet is created and provisioned, you can deploy your site to it with another command:

trellis deploy production my-site.com

This will sync your local files to the remote server, run composer install to install the dependencies, and update the database if needed. You can access your site at the IP provided from your browser.

Encrypting sensitive files using Vault

Trellis uses Ansible as its configuration management tool. Ansible allows you to store your configuration variables in YAML files that are easy to read and write. However, some of these variables may contain sensitive information, such as passwords, keys, tokens, etc.

To protect these variables from being exposed, Trellis uses Ansible Vault to encrypt them. Ansible Vault is a feature of Ansible that allows you to encrypt and decrypt files using a password which is stored in .vault_pass file. Trellis-CLI makes it easy to work with Ansible Vault files using one command:

trellis vault edit group_vars/production/vault.yml

This will prompt you for the vault password (which you can set in trellis/group_vars/all/vault.yml), decrypt the file temporarily, open it in your default editor, and re-encrypt it when you save and close it.

    decrypt    Decrypts files with Ansible Vault
    edit       Edit an encrypted file in place
    encrypt    Encrypts files with Ansible Vault
    view       Open, decrypt and view existing vaulted files

You can also use trellis vault encrypt or trellis vault decrypt to encrypt or decrypt files without opening them.

Summary

In this article, You learned how to use Trellis-CLI to manage Trellis projects. Trellis-CLI is a powerful tool to simplify and enhance your WordPress development workflow.

Command	Description
trellis new	Creates a new Trellis project with a Bedrock-based WordPress site
trellis up	Starts and provisions the Vagrant development environment
trellis down	Stops the Vagrant development environment
trellis deploy	Deploys your site to a specified environment
trellis droplet create	Creates and provisions a DigitalOcean droplet for your site
trellis vault edit	Edits an encrypted file using Ansible Vault
trellis info	Displays information about your Trellis project and environments
trellis rollback	Rolls back the last deploy of your site to a previous release
trellis ssh	Connects to a remote server via SSH
trellis console	Opens a WP-CLI shell on a remote server