diff --git a/trellis/deployments.md b/trellis/deployments.md index 36c9e8bb..98097ab8 100644 --- a/trellis/deployments.md +++ b/trellis/deployments.md @@ -1,5 +1,5 @@ --- -date_modified: 2023-01-27 13:17 +date_modified: 2024-06-04 16:30 date_published: 2015-09-07 20:44 description: Trellis offers zero-downtime WordPress deployment out of the box with little configuration needed. Hooks let you customize what happens at each step of the atomic deploy process. title: Deployments @@ -14,41 +14,58 @@ authors: # Deployments -Trellis offers zero-downtime WordPress deployment out of the box with little configuration needed. +Trellis allows zero-downtime WordPress deployment out of the box with a little configuration. Hooks let you customize what happens at each step of the deploy process. -## Configuration +Trellis deploys your site from a Git repository. In your `wordpress_sites.yml` file, found in the `group_vars/` directory, make sure the `repo` and `branch` keys are set correctly: -First, you need to have at least one [WordPress site](wordpress-sites.md) configured and your remote server provisioned and working according to the [remote server setup](remote-server-setup.md). +- `repo` - Git URL of your Bedrock-based WordPress project (in SSH format: `git@github.com:org/repo-name.git`) +- `branch` - Git branch to deploy (default: `master`) -For deploys, there's a couple more settings needed: - -- `repo` (required) - git URL of your Bedrock-based WordPress project (in SSH format: `git@github.com:roots/bedrock.git`) -- `repo_subtree_path` (optional) - relative path to your Bedrock/WP directory in your repo if its not the root (like `site` in [roots-example-project](https://github.com/roots/roots-example-project.com)) -- `branch` (optional) - the git branch to deploy (default: `master`) +```diff +wordpress_sites: + example.com: + ... +- repo: git@github.com:example/example.com.git ++ repo: git@github.com:org/repo-name.git +- branch: master ++ branch: main +``` -Those variables should be added to the corresponding site in `group_vars//wordpress_sites.yml` as detailed in the [docs](wordpress-sites.md). +[Read more about WordPress Sites in Trellis](/trellis/docs/wordpress-sites/) -At this point, you should also generate your salts and keys and save them to your `vault.yml` file. +::: tip +Using DigitalOcean? Read our guide on [deploying Trellis to DigitalOcean](https://roots.io/trellis/docs/deploy-to-digitalocean/) +::: ## Deploying -Deploy with a single command: - Run the following from any directory within your project: ```shell -$ trellis deploy +trellis deploy ``` ::: warning Note -**Trellis does not automatically install WordPress on remote servers**. +**Trellis does not automatically "install" WordPress on remote servers**. It's normal and expected to see the WordPress install screen the first time you deploy. It's up to you to either import an existing database or install a fresh site. ::: -## Default flow +## Rollbacks + +Run the following from any directory within your project: + +```shell +trellis rollback +``` + +Manually specify a different release using `--release=12345678901234` as such: -By default, Trellis deploys are configured for Bedrock-based sites and take care of everything needed. The hooks below are for more advanced customization purposes. +```shell +trellis rollback --release=12345678901234 +``` + +By default Trellis stores five previous releases, not including the current release. See `deploy_keep_releases` in [Options - Remote Servers](wordpress-sites.md) to change this setting. ## Hooks @@ -128,64 +145,3 @@ deploy_build_after: The second example above demonstrates overriding the `deploy_build_after` hook that Trellis already uses by default. The first include file in this hook's list is `roles/deploy/hooks/build-after.yml`, which is the task file Trellis usually executes. If you omit a hook's default file when overriding an existing hook variable, the default file's tasks will no longer execute. The second include file in the `deploy_build_after` example above, `deploy-hooks/build-after.yml`, is an example of adding a custom task file that would run on every deploy, regardless the site being deployed. The third include file, deploy-hooks/sites/{{ site }}-build-after.yml, demonstrates how you could use a `{{ site }}` variable to include a file based on the name of the site being deployed, e.g., `example.com-build-after.yml`. - -### SSH keys - -Before you can deploy a site to a remote server, your SSH keys need to be working. Trellis takes advantage of SSH forwarding so your remote server does not need to generate an SSH key and add it to GitHub/Bitbucket. - -The chain works like this: `local machine` -> SSH via Ansible -> `remote server` -> Git clone -> `remote Git repository` - -See the [SSH Keys docs](ssh-keys.md) on how to get your SSH key added to the `web` user which is the user Trellis deploys with. - -### Example - -Here's an example of all the configuration needed to deploy a site and what the commands would look like. - -Configuration: - -```yaml -# group_vars/production/wordpress_sites.yml - -wordpress_sites: - mysite.com: - site_hosts: - - canonical: mysite.com - local_path: ../site - repo: git@github.com:me/mysite.git - repo_subtree_path: site - multisite: - enabled: false - ssl: - enabled: false - cache: - enabled: false -``` - -Deploy command: - -Run the following from any directory within your project: - -```shell -$ trellis deploy -``` - -## Rollbacks - - -Run the following from any directory within your project: - -```shell -$ trellis rollback -``` - -You may manually specify a different release using `--release=12345678901234` as such: - -```shell -$ trellis rollback --release=12345678901234 -``` - -By default Trellis stores 5 previous releases, not including the current release. See `deploy_keep_releases` in [Options - Remote Servers](wordpress-sites.md) to change this setting. - -## Deploying to other hosts - -Trellis can deploy to other hosts that support SSH, Composer, and WP-CLI, along with updating the web root path. diff --git a/trellis/installation.md b/trellis/installation.md index b9397c06..8e5a6eba 100644 --- a/trellis/installation.md +++ b/trellis/installation.md @@ -1,5 +1,5 @@ --- -date_modified: 2023-01-27 13:17 +date_modified: 2024-06-04 17:00 date_published: 2015-10-15 12:20 description: Trellis installation and new project instructions. title: Installing Trellis @@ -10,36 +10,39 @@ authors: - nikitasol - swalkinshaw - TangRufus + - MWDelaney --- # Installation ## What is Trellis? + [Trellis](https://roots.io/trellis/) is a tool to create WordPress web servers and deploy WordPress sites. Trellis lets you create and manage servers that are production ready, performance optimized and based on best practices that are continuously improved. Trellis is self-hosting done right since you benefit from the community and experience of Roots. ### Why use Trellis? + You’ll get a complete WordPress server [running all the software](#software-installed) you need configured according to the best practices that are fully customizable.
Trellis features #### Ansible + Trellis is powered by [Ansible](https://docs.ansible.com/ansible/latest/index.html) for configuration management. You don’t have to use brittle and confusing Bash scripts or worry about commands you found to copy and paste. You get the benefit of Ansible [documentation](https://docs.ansible.com/ansible/latest/user_guide/index.html), its extensive library of [modules and plugins](https://docs.ansible.com/ansible/latest/collections/all_plugins.html), and the community ecosystem of [Galaxy roles](https://galaxy.ansible.com/). #### Local development -Trellis comes with [Vagrant](https://www.vagrantup.com/) support for local -development environments that run on isolated virtual machines. This means you -don't have to worry about polluting your local OS with software that might break + +Trellis comes with [Vagrant](https://www.vagrantup.com/) support for local development environments that run on isolated virtual machines. This means you don't have to worry about polluting your local OS with software that might break or conflict with other tools you use. -However, using Vagrant is optional and you're free to use other local dev tools -as well, or even none at all. +However, using Vagrant is optional and you're free to use other local dev tools as well, or even none at all. #### Customizable + While Trellis gives you everything for a standard WordPress server out of the box, it's completely customizable as well. This is what makes Trellis different from managed hosting or even tools like SpinupWP that automatically setup @@ -50,47 +53,43 @@ code" so you can easily see exactly what Trellis installs on your server and customize if you want. #### Portable without vendor-lock in -Trellis servers can be run on _any_ hosting platform; traditional dedicated -server hosting or cloud platforms. All Trellis needs is a server running a plain -Ubuntu operating system. -This means you can easily migrate hosting providers making your infrastructure -much more flexible and portable. You can even "disconnect" your server from -Trellis if you want and just manage your server manually. Trellis isn't required -to keep your server running (but we do recommend it!). +Trellis servers can be run on _any_ hosting platform; traditional dedicated server hosting or cloud platforms. All Trellis needs is a server running a plain Ubuntu operating system. + +This means you can easily migrate hosting providers making your infrastructure much more flexible and portable. You can even "disconnect" your server from Trellis if you want and just manage your server manually. Trellis isn't required to keep your server running (but we do recommend it!). #### Cost effective + Managed WP hosting can make your life easier, but it can also be extremely expensive and is often overkill for simpler WordPress sites. -Trellis lets you run performant sites on extremely cheap servers ($5-10/month) -and even supports running multiple sites on a single server for more efficiency. +Trellis lets you run performant sites on extremely cheap servers ($5-10/month) and even supports running multiple sites on a single server for more efficiency. #### Community backed -Since Trellis is open-source, we get the leverage of Roots and our community to -continuously improve the defaults over time. We are constantly learning better -settings and defaults for WordPress servers, and then we apply them to Trellis. + +Since Trellis is open-source, we get the leverage of Roots and our community to continuously improve the defaults over time. We are constantly learning better settings and defaults for WordPress servers, and then we apply them to Trellis. #### Development and production parity -Unlike many other solutions for WordPress server hosting, Trellis aims to have -[parity between your development and production environments](https://roots.io/twelve-factor-10-dev-prod-parity/). Trellis comes setup to run locally with Vagrant so you can test your WordPress sites with full confidence that they'll work once you deploy to production. + +Unlike many other solutions for WordPress server hosting, Trellis aims to have [parity between your development and production environments](https://roots.io/twelve-factor-10-dev-prod-parity/). Trellis comes setup to run locally with Vagrant so you can test your WordPress sites with full confidence that they'll work once you deploy to production. #### CLI -Trellis has its own [CLI](cli.md) that makes managing your local and remote servers much -easier. It also enables powerful CI/CD workflows like our [setup-trellis-cli](https://github.com/roots/setup-trellis-cli/) -[GitHub action that can be used for continuous deploys](/trellis/docs/deploy-with-github-actions/). + +Trellis has its own [CLI](cli.md) that makes managing your local and remote servers much easier. It also enables powerful CI/CD workflows like our [setup-trellis-cli](https://github.com/roots/setup-trellis-cli/) [GitHub action that can be used for continuous deploys](/trellis/docs/deploy-with-github-actions/). #### Zero-downtime deploys + Trellis has atomic, zero-downtime deploys built-in that are completely configurable with a powerful hook system. You can deploy and rollback releases with a single command thanks to trellis-cli too.
-### Software installed +### Trellis servers are production-ready + Trellis provisions a base Ubuntu 22.04 server by installing and configuring the following software: -* PHP 8.0+ +* PHP 8.1+ * Nginx (including HTTP2/ and optional FastCGI micro-caching) * MariaDB (a drop-in MySQL replacement) * SSL support (scores an A+ on the [Qualys SSL Server Test](https://www.ssllabs.com/ssltest/)) @@ -103,47 +102,46 @@ Trellis provisions a base Ubuntu 22.04 server by installing and configuring the In addition to configuring common services like ntp, sshd, etc. -## Requirements - -Trellis relies on a few other software tools. Make sure all dependencies have been installed before moving on: - -- [Python 3](./python.md) -- [trellis-cli](https://github.com/roots/trellis-cli) +## System requirements -### Local development requirements -If you want to use Trellis' built-in Vagrant integration, you'll need the -following as well: +* [Vagrant](https://www.vagrantup.com/downloads.html) +* [Vagrant provider](https://developer.hashicorp.com/vagrant/docs/providers) + * [VirtualBox](https://www.virtualbox.org/wiki/Downloads) + * [Parallels](https://www.parallels.com/products/desktop/download/) (for Apple Silicon M1, M2, M3, etc. Macs) -- [Vagrant](https://www.vagrantup.com/downloads.html) >= 2.1.0 -- a Vagrant [provider](https://www.vagrantup.com/docs/providers): - - x86 (Intel based Macs, Linux, Windows PCs): [VirtualBox](https://www.virtualbox.org/wiki/Downloads) >= 4.3.10 - - Apple Silicon (M1 based Macs): See our [Parallels page](vagrant.md#parallels-apple-silicon-m1-macs) - -::: warning Note for Windows users -**All commands must be run from WSL ([Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10)).** +::: tip macOS users +Want to skip the Vagrant and Vagrant provider requirements? [**Try Lima as an alternative**](/introducing-lima-to-trellis-for-faster-local-development/) ::: -## Install trellis-cli +::: warning Windows users +WSL is required in order to use Trellis. All Trellis commands must be run from a [WSL environment](https://docs.microsoft.com/en-us/windows/wsl/). +::: -Install [trellis-cli](https://github.com/roots/trellis-cli) via [Homebrew](https://brew.sh/): +
+Additional requirements for Windows users -```shell -$ brew install roots/tap/trellis-cli -``` +* [WSL 2](https://docs.microsoft.com/en-us/windows/wsl/install) +* Vagrant must be installed in WSL +* VirtualBox must be installed in Windows +* The following must be set in your WSL shell configuration file (`~/.bashrc`): + * `VAGRANT_WSL_ENABLE_WINDOWS_ACCESS = 1` + * `export PATH="$PATH:/mnt/c/Program Files/Oracle/VirtualBox"` +* All Trellis commands must be run WSL -## Create a project +
-To create a new project, first, pick a descriptive name (and use it in place of the default `example.com`). -We recommend the domain of the site for convenience. +## Install Trellis CLI ```shell -$ trellis new example.com +brew install roots/tap/trellis-cli ``` -Or to explicitly set the site name and host, use the following: +## Create a new project with Trellis + +Choose a descriptive project name (and use it in place of the default example.com). We recommend the domain of the site for uniqueness. ```shell -$ trellis new --name example.com --host www.example.com ~/path/to/my/project +trellis new example.com ``` After you've created a project, the folder structure for a Trellis project will look like this: @@ -157,17 +155,41 @@ example.com/ # → Root folder for the project └── wp/ # → WordPress core (don't touch! - managed by Composer) ``` -Assuming you used the CLI, you'll also have your first WordPress site automatically configured based on the -project folder (or name and host provided). +Check out the following files to review the basic site configuration: -Check out the following files to see the basic site configuration: * `trellis/group_vars/development/wordpress_sites.yml` * `trellis/group_vars/production/wordpress_sites.yml` -## What's next? -Now that you have a project created and the basics configured, you can explore the following steps: +## Start your development environment + +```shell +trellis up +``` + +This command will start the Vagrant environment and provision the server. Once it's done, you can visit your development site at the URL you chose when you ran `trellis new`. + +[Read more about Local Development](/trellis/docs/local-development/) + +## Configure your environments + +Trellis pre-configures most of your site's settings, but you'll need to fill in a few gaps in the [WordPress Sites](/trellis/docs/wordpress-sites/) configuration. + +## Encrypt your vault files -* Review your [sites and learn how to customize them](./wordpress-sites.md) -* Run your [local development server with Vagrant](./local-development.md) -* [Provision](./remote-server-setup.md) and [deploy](./deployments.md) a remote staging or production server -* Run `trellis --help` to explore all the commands available in the CLI +You probably want to encrypt your vault files, which hold automatically-generated passwords and other sensitive information. [Read more about Vault](/trellis/docs/vault/) + +## Provision your production server + +Before deploying to production, you'll need to provision your server. [Read more about provisioning](/trellis/docs/remote-server-setup/) + +```shell +trellis provision production +``` + +## Deploy to production + +Ready to deploy your site to production? [Read more about deployments](/trellis/docs/deployments/) + +```shell +trellis deploy production example.com +``` diff --git a/trellis/remote-server-setup.md b/trellis/remote-server-setup.md index 0181c707..a6b90e46 100644 --- a/trellis/remote-server-setup.md +++ b/trellis/remote-server-setup.md @@ -1,5 +1,5 @@ --- -date_modified: 2023-01-27 13:17 +date_modified: 2024-06-04 17:00 date_published: 2015-10-15 12:27 description: Using Trellis on a remote server requires a server running a bare/stock version of Ubuntu 22.04 LTS. You can't run Trellis on a shared host. title: Remote Server Setup @@ -10,45 +10,29 @@ authors: - MWDelaney - nicbovee - swalkinshaw + - MWDelaney --- # Remote Server Setup -Setting up remote servers (usually staging or production environments) is similar to the [local development setup](local-development.md) with a few additional requirements and steps. - -In development, Trellis handles everything for you. It automatically creates a server (Vagrant virtual machine), provisions it, installs WordPress, and syncs your local files to the VM. -For remote servers, the workflow is a little different with two new separate concepts: - -- [Provision](#provision) -- [Deploy](#deploy) - -Before getting to those, there's some additional requirements as well. - -## Dependencies - -The Trellis [installation instructions](installation.md) are optimized for a quick start using Vagrant. For deploying and provisioning remote servers, we need to ensure all of Trellis' dependencies (mainly Ansible) are installed on your local/host machine. +Trellis can be used for setting up remote servers (offered by VPS/cloud service providers such as [DigitalOcean](/trellis/docs/deploy-to-digitalocean/)) to host your staging and production environments. -If you're using trellis-cli, just re-run the following command to ensure your -project is initialized and the dependencies are installed: - -```shell -$ trellis init -``` +::: warning +**Trellis cannot provision shared or managed hosts.** Trellis requires a bare server if you want to use it for provisioning. +::: ## Server requirements -1. You need a server running a bare/stock version of Ubuntu 22.04 LTS. If you're using a host such as DigitalOcean that lets you pick an OS to start with, then select the Ubuntu 22.04 option. +* Ubuntu 22.04 LTS +* SSH access to the server -::: warning Shared hosts -Trellis **cannot be used** on a shared host. Trellis requires a dedicated server if -you want to use it for provisioning and deployments. -::: +You need a server running a bare/stock version of Ubuntu 22.04 LTS. If you're using a host such as DigitalOcean that lets you pick an OS to start with, then select the Ubuntu 22.04 option. -2. You need to be able to connect to your Ubuntu server from your local computer via SSH. We *highly* suggest doing this via SSH keys so you don't have to specify a password every time. Many hosts like DigitalOcean offer to automatically add your SSH key when creating a server so take advantage of that. Or follow a guide such as [this one](https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2). +You need to be able to connect to your Ubuntu server from your local computer via SSH. We *highly* suggest doing this via SSH keys so you don't have to specify a password every time. Many hosts offer to automatically add your SSH key when creating a server, so take advantage of that. Once you have a Ubuntu server up and running, you can provision it. -## Provision +## Provisioning Provisioning a server means to set it up with the necessary software and configuration to run a WordPress site. For Trellis this means things like: installing MariaDB, installing Nginx, configuring Nginx, creating a database, etc. @@ -71,9 +55,8 @@ you'll likely be creating a `production` or `staging` environment. Now you're ready to provision your server. Ansible connects to the remote server via SSH so run the following command from your local machine: - ```shell -$ trellis provision +trellis provision ``` ### Re-provisioning @@ -83,7 +66,7 @@ Re-provisioning is always assumed to be a safe operation. When you make changes Run the following from any directory within your project: ```shell -$ trellis provision +trellis provision ``` You can also provision with specific tags to only run the relevant roles: @@ -91,21 +74,5 @@ You can also provision with specific tags to only run the relevant roles: Run the following from any directory within your project: ```shell -$ trellis provision --tags users +trellis provision --tags users ``` - -## Deploy - -In development it's easy to get your site/codebase onto the VM through synced folders. However for remote servers, we need to deploy first. - -Deploys are done in Trellis by running the `deploy.yml` playbook. This gets your codebase onto the server by cloning it from a Git repository. It also takes cares of things like: running Composer, creating config files, reloading Nginx, etc. - -Run the following from any directory within your project: - -```shell -$ trellis deploy -``` - -## Resources - -- [Using Trellis to Provision and Deploy to DigitalOcean Droplets](https://roots.io/trellis/docs/deploy-to-digitalocean/) diff --git a/trellis/vault.md b/trellis/vault.md index cfa93b73..2198048a 100644 --- a/trellis/vault.md +++ b/trellis/vault.md @@ -1,7 +1,7 @@ --- -date_modified: 2023-01-27 17:40 +date_modified: 2024-06-04 17:00 date_published: 2015-11-01 14:32 -description: Steps to enable and use Ansible Vault with a Trellis project. Trellis uses a vault.yml file for variables with sensitive data such as passwords. +description: Steps to enable and use Ansible Vault with a Trellis project. Trellis uses a `vault.yml` file for variables with sensitive data such as passwords. title: Vault authors: - ben @@ -15,7 +15,10 @@ authors: # Vault -Some Ansible variables contain sensitive data such as passwords. Trellis keeps these variable definitions in separate files named `vault.yml`. We strongly recommend that you encrypt these `vault.yml` files using [Ansible Vault](https://docs.ansible.com/ansible/latest/user_guide/vault.html#vault) to avoid exposing sensitive data in your project repo. Your Trellis commands will be exactly the same as before enabling vault, not requiring any extra flags. +Some project variables contain sensitive data like passwords. Trellis keeps these variable definitions in separate files named `vault.yml`. We strongly recommend that you encrypt these `vault.yml` files using to avoid exposing sensitive data in your project repository. + +
+vault.yml example To briefly demonstrate what vault does, consider this example `vault.yml` file. @@ -36,22 +39,41 @@ $ANSIBLE_VAULT;1.1;AES256 6237663637353638653266616562616535623465636265316231613331 etc. ``` -## Steps to enable Ansible Vault +
+ +## Encrypt your vault files + +```shell +trellis vault encrypt +``` ::: danger If you have unencrypted `vault.yml` files in your project's git history (e.g., passwords in plain text), you will most likely want to change the variable values in your `vault.yml` files before encrypting them and committing them to your repo. ::: -### Encrypt files -`trellis-cli` automatically generates your vault files and a vault password, but does not encrypt your vaults. To encrypt vaults created by `trellis-cli` run the following from any directory within your project: +::: warning Don't forget your vault password +Trellis automatically generates a vault password for you at `trellis/.vault_pass`. This file **will not** be added to your Git repository. +::: + +Your Trellis commands will be exactly the same as before enabling vault, not requiring any extra flags. +## View an encrypted vault file + +You can view a vault file in your terminal with the following command: ```shell -$ trellis vault encrypt +trellis vault view ``` -## Other vault commands +## Edit an encrypted vault file +You can edit a vault file in your terminal with the following command: + +```shell +trellis vault edit group_vars//vault.yml +``` + +## Other vault commands `trellis-cli` provides a few basic commands that mirror with the official [Ansible Vault](https://docs.ansible.com/ansible/latest/user_guide/vault.html) ones. @@ -74,7 +96,7 @@ Here are a few tips for working with [variables and vault](http://docs.ansible.c ## Sharing a project with vault-encrypted files -Your repo with vault-encrypted files is secure from anyone being able to see or use the sensitive data in the `vault.yml` files. To grant a colleague access to the data, you will need to give your colleague your vault password to use in repeating the two password steps in the [Steps to Enable Ansible Vault](vault.md#steps-to-enable-ansible-vault) above. It is still recommended to always keep your project in a private repo. +Your repo with vault-encrypted files is secure from anyone being able to see or use the sensitive data in the `vault.yml` files. To grant a colleague access to the data, you will need to give your colleague your vault password to use in repeating the two password steps in the [Steps to Enable Ansible Vault](#encrypt-your-vault-files) above. It is still recommended to always keep your project in a private repo. ## Disabling Ansible Vault @@ -84,14 +106,14 @@ It is not recommended to disable Ansible Vault but you can disable it at any tim Without your password, either entered as a string or stored in your `vault_password_file` file (usually `.vault_pass` and configured in the `ansible.cfg` file), you will not be able to access the encrypted files. The `vault_password_file` should not ever be publicly accessible, or committed to version control. It's a good practice to backup this file on another physical or virtual drive, ideally also encrypted. -## Access Recovery +## Access recovery Should you lose access to your vault password, you you can either spin up a new server, or recreate or regenerate the `group_vars/(environment)/vault.yml` files and, on the servers, manually update the following to match new vault strings: ### admin root (sudo) password -``` -$ sudo passwd admin +```shell +sudo passwd admin ``` ### root mysql password @@ -103,6 +125,7 @@ flush privileges; ``` ### WordPress database passwords + ```sql UPDATE mysql.user SET Password=PASSWORD('password_in_vault_file') WHERE USER='example_com' AND Host='localhost';