Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

📝 Update Trellis documenttion to focus on approachability #514

Merged
merged 5 commits into from
Jun 4, 2024
Merged

📝 Update Trellis documenttion to focus on approachability #514

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ed8910b
📝 Update Trellis documenttion to focus on approachability
MWDelaney Jun 4, 2024
6a812f2
Update deployments.md
retlehs Jun 4, 2024
4e4bb60
Update installation.md
retlehs Jun 4, 2024
e6785b3
Update remote-server-setup.md
retlehs Jun 4, 2024
9ac0351
Update vault.md
retlehs Jun 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 34 additions & 78 deletions trellis/deployments.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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/<environment>` 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: `[email protected]: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: `[email protected]: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: [email protected]:example/example.com.git
+ repo: [email protected]:org/repo-name.git
- branch: master
+ branch: main
```

Those variables should be added to the corresponding site in `group_vars/<environment>/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 <environment>
trellis deploy <environment>
```

::: 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 <environment>
```

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 <environment>
```

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

Expand Down Expand Up @@ -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, <code>deploy-hooks/sites/{{ site }}-build-after.yml</code>, 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` -&gt; SSH via Ansible -&gt; `remote server` -&gt; Git clone -&gt; `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: [email protected]: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 <environment>
```

## Rollbacks


Run the following from any directory within your project:

```shell
$ trellis rollback <environment>
```

You may manually specify a different release using `--release=12345678901234` as such:

```shell
$ trellis rollback --release=12345678901234 <environment>
```

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.
144 changes: 83 additions & 61 deletions trellis/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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.

<details>
<summary>Trellis features</summary>

#### 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
Expand All @@ -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.

</details>

### 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/))
Expand All @@ -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/):
<details>
<summary>Additional requirements for Windows users</summary>

```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
</details>

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:
Expand All @@ -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
```
Loading