diff --git a/bedrock/installation.md b/bedrock/installation.md index c22ea935..a9e8e823 100644 --- a/bedrock/installation.md +++ b/bedrock/installation.md @@ -1,5 +1,5 @@ --- -date_modified: 2023-01-27 13:17 +date_modified: 2024-05-22 11:15 date_published: 2015-10-15 12:29 description: Installing Bedrock requires PHP 8.0+ and Composer. After setting environment variables and the document root you can access your WordPress installation. title: Installing Bedrock @@ -7,24 +7,12 @@ authors: - ben - Log1x - swalkinshaw + - MWDelaney --- # Installation -## What is Bedrock? - -Bedrock is a [WordPress boilerplate](https://roots.io/bedrock/). - -### Why use Bedrock? - -- Better folder structure -- Dependency management with [Composer](https://getcomposer.org) -- Easy WordPress configuration with environment specific files -- Environment variables with [Dotenv](https://github.com/vlucas/phpdotenv) -- Autoloader for mu-plugins (use regular plugins as mu-plugins) -- Enhanced security (separated web root and secure passwords with [wp-password-bcrypt](https://github.com/roots/wp-password-bcrypt)) - -## Requirements +## System requirements - PHP >= 8.0 - [Composer](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-macos) @@ -34,10 +22,10 @@ Bedrock is a [WordPress boilerplate](https://roots.io/bedrock/). Create a new Bedrock project: ```shell -$ composer create-project roots/bedrock +composer create-project roots/bedrock ``` -## Getting Started +## Create your `.env` file - Create a `.env` file with the following environment variables (see `.env.example` as an example): - Database variables @@ -61,5 +49,18 @@ $ composer create-project roots/bedrock Bedrock is multisite network compatible, but needs the [roots/multisite-url-fixer](https://github.com/roots/multisite-url-fixer) mu-plugin on subdomain installs to make sure admin URLs function properly. This plugin is not _needed_ on subdirectory installs but will work well with them. From your Bedrock directory: ```shell -$ composer require roots/multisite-url-fixer +composer require roots/multisite-url-fixer ``` + +## What is Bedrock? + +Bedrock is a [WordPress boilerplate](https://roots.io/bedrock/). + +### Why use Bedrock? + +- Better folder structure +- Dependency management with [Composer](https://getcomposer.org) +- Easy WordPress configuration with environment specific files +- Environment variables with [Dotenv](https://github.com/vlucas/phpdotenv) +- Autoloader for mu-plugins (use regular plugins as mu-plugins) +- Enhanced security (separated web root and secure passwords with [wp-password-bcrypt](https://github.com/roots/wp-password-bcrypt)) diff --git a/sage/deployment.md b/sage/deployment.md index 3597a7f9..f713c060 100644 --- a/sage/deployment.md +++ b/sage/deployment.md @@ -1,25 +1,19 @@ --- -date_modified: 2024-01-18 13:30 +date_modified: 2024-05-22 11:15 date_published: 2015-09-01 19:29 -description: To deploy a Sage theme you'll need to run `composer install` on the remote server, and copy over theme assets built with `yarn build`. +description: Compile your assets, install your dependencies, and copy your Sage-based theme to your server. Remember that PHP versions must match between environments. title: Deploying Sage authors: - alwaysblank - ben - kero - Log1x + - MWDelaney --- # Deployment -To deploy a Sage theme you'll need to make sure two things are covered: - -1. Run `composer install` from the theme directory on the remote server if you have Acorn installed in your theme directory -2. Copy over built theme assets (the `public/` folder) - -Generate production ready assets with `yarn build`. - -## Server requirements +## (Remote) system requirements - WordPress >= 5.9 - PHP >= 8.1 @@ -31,6 +25,32 @@ Generate production ready assets with `yarn build`. - Tokenizer PHP Extension - XML PHP Extension +## Deploying a Sage-based WordPress theme + +::: warning PHP versions must match +Make sure the PHP version of your development environment matches the PHP version of your production environment, or your composer dependencies may not work correctly. +::: + +### 1. Build Assets + +Compile your CSS, Javascript, image, and font assets for production: + +```shell +yarn build +``` + +### 2. Install Composer dependencies + +Install Composer dependencies: + +```shell +composer install +``` + +### 3. Copy files to your server + +Copy all files and folders in your theme except the `node_modules` directory to your server. + ## Server configuration ::: tip Using Trellis or Radicle? diff --git a/sage/installation.md b/sage/installation.md index 4c004544..fb9308b7 100644 --- a/sage/installation.md +++ b/sage/installation.md @@ -1,5 +1,5 @@ --- -date_modified: 2023-01-27 13:17 +date_modified: 2024-05-22 11:15 date_published: 2015-08-29 18:09 description: Install Sage 10, a WordPress starter theme, by running `composer create-project roots/sage`. title: Installing Sage @@ -11,68 +11,83 @@ authors: - Log1x - QWp6t - TangRufus + - MWDelaney --- -# Installation +# Installing Sage ## What is Sage? Sage is a [WordPress starter theme](https://roots.io/sage/). -### Why use Sage? +## Why use Sage? -- Harness the power of [Laravel](https://laravel.com) and its available packages thanks to [Acorn](https://github.com/roots/acorn). - Clean, efficient theme templating utilizing [Laravel Blade](https://laravel.com/docs/master/blade). - Lightning fast frontend development workflow powered by [Bud](https://bud.js.org/). - Out of the box support for [Tailwind CSS](https://tailwindcss.com/). +- Harness the power of [Laravel](https://laravel.com) and its available packages thanks to [Acorn](https://github.com/roots/acorn). -## Getting Started +## System Requirements + +- [Node.js](https://nodejs.org/) +- [Composer](https://getcomposer.org/download/) ::: warning Windows users -WSL is required in order to use Sage. Build commands must be ran from a [WSL environment](https://docs.microsoft.com/en-us/windows/wsl/). +WSL is required in order to use Sage. Build commands must be run from a [WSL environment](https://docs.microsoft.com/en-us/windows/wsl/). ::: -Sage relies on Node.js based tools to manage dependencies and build assets. We recommend using [Volta](https://github.com/volta-cli/volta) to install and manage Node.js. We also recommend using [Yarn](https://yarnpkg.com/). [After installing Volta](https://docs.volta.sh/guide/getting-started): + -```shell -# Install the latest Node.js LTS release -$ volta install node +## Create a new theme with Sage -# Globally install Yarn -$ npm install --global yarn +### 1. Create a new Sage-based WordPress theme with Composer + +Create a new WordPress theme using Sage with Composer from your WordPress themes directory (replace `your-theme-name` below with the name of your theme): + +```shell +# From your WordPress themes directory, run: +composer create-project roots/sage your-theme-name ``` -## Installing Acorn +### 2. Edit `bud.config.js` to match your environment -Sage requires Acorn but doesn't ship with it included. This is to give you the flexibility to include it in a way that works best for your environment. There's a few different ways to install Acorn. +Modify the `bud.config.js` file in your new Sage-based theme's directory to match the theme's directory name and local development URL, if applicable. -See the [Acorn installation](/acorn/docs/installation/) docs for additional details. +```javascript +// bud.config.js -## Installing Sage with Composer +/** + * Around line 26, update the following path + * to match your theme's directory: +*/ -Install Sage using Composer from your WordPress themes directory (replace `your-theme-name` below with the name of your theme): +app.setPublicPath('/app/themes/sage/public/'); -```shell -# From your WordPress themes directory, run: -$ composer create-project roots/sage your-theme-name +/** + * Around line 37, pdate the following URL + * to match your local development URL: +*/ +.setProxyUrl('http://example.test') ``` -To install the latest development version of Sage, add `dev-main` to the end of the command: +### 3. Build the theme assets + +From your new Sage-based theme's directory, run: ```shell -$ composer create-project roots/sage your-theme-name dev-main +yarn && yarn build ``` -## Build assets - -You must build theme assets in order to access your site. Failing to build the assets will result in the error: +::: warning You must build theme assets in order to access your site. Failing to build the assets will result in the error: ```plaintext The manifest [/path/to/sage/public/manifest.json] cannot be found. ``` -### Running the first build +::: + +That's it! You're ready to activate your theme in WordPress and start developing! + +## What Next? -- Run `yarn` from the theme directory to install dependencies -- Update `bud.config.js` with your local dev URL -- `yarn build` — Compile assets +From here you might want to [explore the structure of your new Sage-based theme](/sage/docs/theme-structure/), or [learn how to use Blade templates](/sage/docs/blade-templates/), or how to [compile assets](/sage/docs/compiling-assets/). These documents are meant to be referenced as you work with Sage, so feel free to jump around as needed. diff --git a/sage/structure.md b/sage/structure.md index 3866d172..c4d92973 100644 --- a/sage/structure.md +++ b/sage/structure.md @@ -1,5 +1,5 @@ --- -date_modified: 2023-01-27 13:17 +date_modified: 2024-05-22 11:15 date_published: 2021-10-21 13:21 description: The default Sage structure is intended to provide a sane starting point for both small and large WordPress sites alike. title: Theme Structure @@ -8,6 +8,7 @@ authors: - ben - jure - Log1x + - MWDelaney --- # Theme Structure @@ -18,7 +19,7 @@ The default Sage structure is intended to provide a sane starting point for both Where a file or class is located is ultimately decided by you. As long as Composer can autoload the class or you have modified the necessary paths in your [configuration](configuration.md), things should work as expected. -```php +```shell themes/your-theme-name/ # → Root of your Sage based theme ├── app/ # → Theme PHP │ ├── Providers/ # → Service providers @@ -74,4 +75,3 @@ The `resources` directory contains your Blade views as well as the un-compiled a ### The `vendor/` directory The `vendor` directory contains your [Composer](https://getcomposer.org/) dependencies and autoloader. This directory is automatically generated and should not be modified. - diff --git a/sage/tailwind-css.md b/sage/tailwind-css.md index df954a2c..8d701421 100644 --- a/sage/tailwind-css.md +++ b/sage/tailwind-css.md @@ -1,10 +1,11 @@ --- -date_modified: 2023-03-13 11:00 +date_modified: 2024-05-22 11:15 date_published: 2023-03-13 11:00 description: Sage includes Tailwind CSS support, including generating the Tailwind color palette, font families, and sizes for `theme.json` which is used by the block editor. title: Tailwind CSS authors: - ben + - MWDelaney --- # Tailwind CSS @@ -38,74 +39,3 @@ Tailwind’s [default color palette](https://tailwindcss.com/docs/customizing-co In addition to including Tailwind’s color palette for the WordPress editor, Sage will also configure the editor with Tailwind’s font families and font sizes. Be sure to take a look at [Bud’s documentation on this feature](https://bud.js.org/extensions/sage/theme.json/) for further information. - -## Using Tailwind's colors from the block editor on the front-end - -While Sage makes Tailwind's colors available in the block editor, it doesn't include an approach out of the box for dealing with the front-end styling for the editor classes. - -You will need to decide how you want to handle the front-end styling for those classes. For example, you might want to add the following to one of your stylesheets: - -```css -.has-amber-50-background-color { - @apply bg-amber-50; -} -``` - -This CSS would allow Tailwind's `amber-50` background color to work when used from the block editor. - -### Automating the front-end classes from the editor - -If you wanted to automate adding all of the colors, you could use the following example Tailwind plugin: - -```javascript -// Add to the top of your tailwind.config.cjs file -const plugin = require('tailwindcss/plugin'); - -// Add the following within your tailwind.config.cjs plugins array: -plugins: [ - plugin(function ({addUtilities, theme, variants}) { - const colors = theme('colors'); - - const colorUtilities = Object.keys(colors).reduce((acc, color) => { - if (typeof colors[color] === 'string') { - acc[`.has-${color}`] = { - 'color': colors[color], - }; - acc[`.has-${color}-background-color`] = { - 'background-color': colors[color], - }; - } else { - Object.keys(colors[color]).forEach((shade) => { - acc[`.has-${color}-${shade}-background-color`] = { - 'background-color': colors[color][shade], - }; - }); - } - - return acc; - }, {}); - - addUtilities(colorUtilities, variants('backgroundColor')); - }), -], -``` - -The biggest issue with this approach is that Tailwind has no insight into which classes have been used from the WordPress editor. If you wanted to allow all of the Tailwind CSS colors to be added to your generated CSS for use in the editor, you could use the [`safelist` option](https://tailwindcss.com/docs/content-configuration#safelisting-classes): - -```javascript -content: ['./index.php', './app/**/*.php', './resources/**/*.{php,vue,js}'], -// Allow all classes that start with has- -safelist: [ - { - pattern: /^has-/, - } -], -``` - -::: warning Note -Beware of how large your stylesheets will get if you are using all of the Tailwind CSS colors along with this approach -::: - -The ideal setup is to remove _all_ classes that you aren't using from Tailwind, and only configure Tailwind with the classes that are required for your project. - -In the future, we might add a more streamlined approach to doing this to Bud's `theme.json` generator. For now, deciding how you want the front-end CSS to work for Tailwind generated classes is up to you. diff --git a/trellis/deployments.md b/trellis/deployments.md index 36c9e8bb..f6338fa7 100644 --- a/trellis/deployments.md +++ b/trellis/deployments.md @@ -1,5 +1,5 @@ --- -date_modified: 2023-01-27 13:17 +date_modified: 2024-05-22 11:15 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,7 +14,12 @@ 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. + +::: note Trellis deploys from Git + +Trellis deploys your site from a Git repository. Make sure the `repo` and `branch` keys are set correctly in your `group_vars//wordpress_sites.yml` file and that your project is commited to the repository. [Read more about WordPress Sites](/trellis/docs/wordpress-sites/). +::: ## Configuration @@ -22,30 +27,49 @@ First, you need to have at least one [WordPress site](wordpress-sites.md) config 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`) +- `repo` - git URL of your Bedrock-based WordPress project (in SSH format: `git@github.com:roots/example.com.git`) +- `branch` - the git branch to deploy (default: `master`) Those variables should be added to the corresponding site in `group_vars//wordpress_sites.yml` as detailed in the [docs](wordpress-sites.md). -At this point, you should also generate your salts and keys and save them to your `vault.yml` file. - ## 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. ::: +## Rollbacks + +Run the following from any directory within your project: + +```shell +trellis rollback +``` + +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. + +## Resources + +- [Using Trellis to Provision and Deploy to DigitalOcean Droplets](https://roots.io/trellis/docs/deploy-to-digitalocean/) + +## What's Next? + +Keep reading to learn about [hooks](#hooks) and how to customize your deploys. + ## Default flow 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. @@ -166,26 +190,5 @@ Deploy command: Run the following from any directory within your project: ```shell -$ trellis deploy +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..54475289 100644 --- a/trellis/installation.md +++ b/trellis/installation.md @@ -1,5 +1,5 @@ --- -date_modified: 2023-01-27 13:17 +date_modified: 2024-05-22 11:15 date_published: 2015-10-15 12:20 description: Trellis installation and new project instructions. title: Installing Trellis @@ -10,36 +10,124 @@ authors: - nikitasol - swalkinshaw - TangRufus + - MWDelaney --- # Installation +## System requirements + +* [Vagrant](https://www.vagrantup.com/downloads.html) +* A 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) + +### Additional requirements for Windows users +* [WSL2](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 `~/.bashrc` or `~/.zshrc` file: + * `VAGRANT_WSL_ENABLE_WINDOWS_ACCESS = 1` + * `export PATH=“$PATH:/mnt/c/Program Files/Oracle/VirtualBox` + +::: 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 + +```shell +brew install roots/tap/trellis-cli +``` + +## 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 example.com +``` + +After you've created a project, the folder structure for a Trellis project will look like this: + +```shell +example.com/ # → Root folder for the project +├── trellis/ # → Your server configuration (a customized install of Trellis) +└── site/ # → A Bedrock-based WordPress site + └── web/ + ├── app/ # → WordPress content directory (themes, plugins, etc.) + └── wp/ # → WordPress core (don't touch! - managed by Composer) +``` + +Check out the following files to review the basic site configuration: + +* `trellis/group_vars/development/wordpress_sites.yml` +* `trellis/group_vars/production/wordpress_sites.yml` + +## 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 developmentsite at the URL you chose when you ran `trellis new`. + +See [Local Development](/trellis/docs/local-development-environment/) for more information. + +## What's Next? + +### 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 + +You probably want to encrypt your vault files, which hold automatically-generated passwords and other sensitive information. Check out the [Vault](/trellis/docs/vault/) documentation for more information. + +### Provision your `production` server + +Before deploying to production, you'll need to provision your server. Check out [Provisioning](/trellis/docs/remote-server-setup//) for details. + +```shell +trellis provision production +``` + +### Deploy to `production` + +When you're ready to deploy your site to production, check out the [Deployments](/trellis/docs/deployments) for details. + +```shell +trellis deploy production example.com +``` + ## 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,44 +138,40 @@ 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+ @@ -102,72 +186,3 @@ Trellis provisions a base Ubuntu 22.04 server by installing and configuring the * Fail2ban and ferm 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) - -### 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) >= 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)).** -::: - -## Install trellis-cli - -Install [trellis-cli](https://github.com/roots/trellis-cli) via [Homebrew](https://brew.sh/): - -```shell -$ brew install roots/tap/trellis-cli -``` - -## 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. - -```shell -$ trellis new example.com -``` - -Or to explicitly set the site name and host, use the following: - -```shell -$ trellis new --name example.com --host www.example.com ~/path/to/my/project -``` - -After you've created a project, the folder structure for a Trellis project will look like this: - -```shell -example.com/ # → Root folder for the project -├── trellis/ # → Your server configuration (a customized install of Trellis) -└── site/ # → A Bedrock-based WordPress site - └── web/ - ├── app/ # → WordPress content directory (themes, plugins, etc.) - └── 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 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: - -* 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 diff --git a/trellis/remote-server-setup.md b/trellis/remote-server-setup.md index 0181c707..93d54eaa 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-05-22 11:15 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,70 +10,42 @@ 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 +Trellis sets up and configures (or "provisions") remote Ubuntu servers (like [DigitalOcean](https://digitalocean.com) droplets) to host your `staging` and `production` environments. It does this using [Ansible](https://www.ansible.com/) playbooks to maintain [parity between your development and production environments](https://roots.io/twelve-factor-10-dev-prod-parity/). Trellis handles everything from installing packages to configuring Nginx and PHP and creating databases. -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 also deploys your WordPress site to your `staging` and `production` servers with zero downtime. -If you're using trellis-cli, just re-run the following command to ensure your -project is initialized and the dependencies are installed: +## (Remote) system requirements -```shell -$ trellis init -``` - -## 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. +* A server running a bare/stock version of Ubuntu 22.04 LTS. ::: 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. +Trellis **cannot be used** on a shared host. Trellis requires a dedicated server if you want to use it for provisioning and deployments. ::: -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). +* SSH access to your Ubuntu server -Once you have a Ubuntu server up and running, you can provision it. +::: note We recommend using SSH keys +We *highly* suggest using SSH keys so you don't have to specify a password every time you interact with your remote server(s). Many hosts like DigitalOcean offer to automatically add your SSH key when creating a server so take advantage of that. Or follow a guide like [this one](https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2). -## 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. -Trellis has two main [playbooks](https://docs.ansible.com/ansible/latest/user_guide/playbooks_intro.html): `dev.yml` and `server.yml`. As mentioned in local development, Vagrant automatically runs the `dev.yml` playbook for us. - -For remote servers, you provision a server via the `server.yml` playbook. This leaves you with a server *prepared* to run a WordPress site, but without the actual codebase yet. - -Before provisioning your server, there's a little more configuration to do. -First determine the _environment_ you want to configure; after development, -you'll likely be creating a `production` or `staging` environment. +### Configure your environment -### Configuration +Modify your project's `group_vars//wordpress_sites.yml` file to match your site's details following the [WordPress Sites](/trellis/docs/wordpress-sites/) documentation. -1. Copy your `wordpress_sites` from your working development site in `group_vars/development/wordpress_sites.yml` to `group_vars//wordpress_sites.yml`. -2. Modify your site and add the necessary settings for [remote servers](wordpress-sites.md#remote-servers) since they have a few more settings than local development. Also see the [Passwords docs](passwords.md). -3. Add your server hostname to `hosts/` (replacing `your_server_hostname`). -4. Specify public SSH keys for `users` in `group_vars/all/users.yml`. See the [SSH Keys docs](ssh-keys.md). -5. Consider setting `sshd_permit_root_login: false` in `group_vars/all/security.yml`. See the [Security docs](security.md). - -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: +### Provision your server +Run the following command from your local machine: ```shell -$ trellis provision +trellis provision ``` ### Re-provisioning @@ -83,7 +55,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 +63,16 @@ 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. +## What's Next? -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. +[Deploy your site](/trellis/docs/deployments/) to your server! -Run the following from any directory within your project: -```shell -$ trellis deploy -``` +## The technical details -## Resources +Trellis has two main [playbooks](https://docs.ansible.com/ansible/latest/user_guide/playbooks_intro.html): `dev.yml` and `server.yml`. As mentioned in local development, Vagrant automatically runs the `dev.yml` playbook for us. -- [Using Trellis to Provision and Deploy to DigitalOcean Droplets](https://roots.io/trellis/docs/deploy-to-digitalocean/) +For remote servers, you provision a server via the `server.yml` playbook. This leaves you with a server *prepared* to run a WordPress site, but without the actual codebase yet. diff --git a/trellis/vault.md b/trellis/vault.md index cfa93b73..729c45f7 100644 --- a/trellis/vault.md +++ b/trellis/vault.md @@ -1,5 +1,5 @@ --- -date_modified: 2023-01-27 17:40 +date_modified: 2024-05-22 11:15 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. title: Vault @@ -15,7 +15,49 @@ 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. + +## Encrypt your vault files + +```shell +trellis vault encrypt +``` + +::: Warning Don't forget your vault password +Trellis automatically generates a vault password for you. You can find it in `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 view +``` + +## 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. + +- `trellis vault encrypt ` +- `trellis vault view ` +- `trellis vault edit ` +- `trellis vault decrypt ` -- Avoid using the `decrypt` command. If your intention is to view or edit an encrypted file, use the `view` or `edit` commands instead. Any time you decrypt a file, you risk forgetting to re-encrypt the file before committing changes to your repo. + +Run `trellis vault` to see usage details. + +## Further reading To briefly demonstrate what vault does, consider this example `vault.yml` file. @@ -42,26 +84,6 @@ $ANSIBLE_VAULT;1.1;AES256 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: - - -```shell -$ trellis vault encrypt -``` - -## 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. - -- `trellis vault encrypt ` -- `trellis vault view ` -- `trellis vault edit ` -- `trellis vault decrypt ` -- Avoid using the `decrypt` command. If your intention is to view or edit an encrypted file, use the `view` or `edit` commands instead. Any time you decrypt a file, you risk forgetting to re-encrypt the file before committing changes to your repo. - -Run `trellis vault` to see usage details. - ## Working with vault variables Here are a few tips for working with [variables and vault](http://docs.ansible.com/ansible/playbooks_best_practices.html#variables-and-vaults) in Trellis. @@ -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