From 940f5c2d62a6b25bc90618adb07f8a417d952c13 Mon Sep 17 00:00:00 2001 From: MWDelaney Date: Tue, 14 May 2024 13:25:18 -0400 Subject: [PATCH 01/20] Improve Sage installation approachability --- sage/installation.md | 98 ++++++++++++++++++++++++++++++++------------ 1 file changed, 72 insertions(+), 26 deletions(-) diff --git a/sage/installation.md b/sage/installation.md index 4c004544..9df8d02d 100644 --- a/sage/installation.md +++ b/sage/installation.md @@ -1,5 +1,5 @@ --- -date_modified: 2023-01-27 13:17 +date_modified: 2024-04-14 12:23 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,114 @@ authors: - Log1x - QWp6t - TangRufus + - MWDelaney --- -# Installation - ## 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 ::: 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): +### Node.js -```shell -# Install the latest Node.js LTS release -$ volta install node +Sage requires 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/). + +To install Node.js and Yarn with Volta, run the following command: -# Globally install Yarn -$ npm install --global yarn +```shell +volta install node && npm install --global yarn ``` -## Installing Acorn +### Composer -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. +Sage requires Composer to manage PHP dependencies. If your platform supports [Homebrew](https://brew.sh/), you can install Composer with: -See the [Acorn installation](/acorn/docs/installation/) docs for additional details. +```shell +brew install composer +``` -## Installing Sage with Composer +Otherwise, [see Composer's documentation](https://getcomposer.org/download/) for installation instructions. -Install Sage using Composer from your WordPress themes directory (replace `your-theme-name` below with the name of your theme): +## Installing Sage + +### 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 +composer create-project roots/sage your-theme-name ``` To install the latest development version of Sage, add `dev-main` to the end of the command: ```shell -$ composer create-project roots/sage your-theme-name dev-main +composer create-project roots/sage your-theme-name dev-main ``` -## Build assets +### 2. Install Acorn + +::: note This step is required +Sage requires the [Acorn](https://roots.io/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. +::: + +To install Acorn as part of Sage (this is the most common use case for theme development), run the following command from your Sage-based theme's directory: -You must build theme assets in order to access your site. Failing to build the assets will result in the error: +```shell +composer require roots/acorn +``` + +See the [Acorn installation](/acorn/docs/installation/) docs for additional details. + +### 3. Edit `bud.config.js` + +Modify the `bud.config.js` file in the theme directory to match your theme's directory name and local development URL, if applicable. + +```javascript +// bud.config.js + +/** + * Around line 26, update the following path + * to match your theme's directory name: +*/ + +app.setPublicPath('/app/themes/sage/public/'); + +/** + * Around line 37, pdate the following URL + * to match your local development URL: +*/ +.setProxyUrl('http://example.test') +``` + +### 4. Build assets + +From your theme directory, run: + +```shell +yarn && yarn build +``` + +::: 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 +::: + +## 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 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. From 2d909b7ad1872326dab867ca34ab4d690a6ac6cb Mon Sep 17 00:00:00 2001 From: MWDelaney Date: Tue, 14 May 2024 14:29:47 -0400 Subject: [PATCH 02/20] =?UTF-8?q?=F0=9F=93=9D=20Remove=20Acorn=20instructi?= =?UTF-8?q?ons?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- sage/installation.md | 50 ++++++++++++++++++-------------------------- 1 file changed, 20 insertions(+), 30 deletions(-) diff --git a/sage/installation.md b/sage/installation.md index 9df8d02d..97630375 100644 --- a/sage/installation.md +++ b/sage/installation.md @@ -14,16 +14,7 @@ authors: - MWDelaney --- -## What is Sage? - -Sage is a [WordPress starter theme](https://roots.io/sage/). - -## Why use Sage? - -- 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). +# Installing Sage ## System Requirements @@ -51,7 +42,7 @@ brew install composer Otherwise, [see Composer's documentation](https://getcomposer.org/download/) for installation instructions. -## Installing Sage +## Create a new theme with Sage ### 1. Create a new Sage-based WordPress theme with Composer @@ -68,30 +59,16 @@ To install the latest development version of Sage, add `dev-main` to the end of composer create-project roots/sage your-theme-name dev-main ``` -### 2. Install Acorn - -::: note This step is required -Sage requires the [Acorn](https://roots.io/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. -::: - -To install Acorn as part of Sage (this is the most common use case for theme development), run the following command from your Sage-based theme's directory: - -```shell -composer require roots/acorn -``` - -See the [Acorn installation](/acorn/docs/installation/) docs for additional details. +### 2. Edit `bud.config.js` to match your environment -### 3. Edit `bud.config.js` - -Modify the `bud.config.js` file in the theme directory to match your theme's directory name and local development URL, if applicable. +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. ```javascript // bud.config.js /** * Around line 26, update the following path - * to match your theme's directory name: + * to match your theme's directory: */ app.setPublicPath('/app/themes/sage/public/'); @@ -103,9 +80,9 @@ app.setPublicPath('/app/themes/sage/public/'); .setProxyUrl('http://example.test') ``` -### 4. Build assets +### 3. Build assets -From your theme directory, run: +From your new Sage-based theme's directory, run: ```shell yarn && yarn build @@ -119,6 +96,19 @@ The manifest [/path/to/sage/public/manifest.json] cannot be found. ::: +That's it! You're ready to activate your theme in WordPress and start developing! + ## What Next? From here you might want to [explore the structure of your new Sage 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. + +## What is Sage? + +Sage is a [WordPress starter theme](https://roots.io/sage/). + +## Why use Sage? + +- 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). From aa3083f385a3407cb988c6f3647419129a2ba061 Mon Sep 17 00:00:00 2001 From: MWDelaney Date: Tue, 14 May 2024 16:22:01 -0400 Subject: [PATCH 03/20] =?UTF-8?q?=F0=9F=93=9D=20Remove=20environment=20set?= =?UTF-8?q?up=20instructions,=20to=20be=20re-introduced=20in=20another=20?= =?UTF-8?q?=20uide=20or=20page?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- sage/installation.md | 23 ++++------------------- 1 file changed, 4 insertions(+), 19 deletions(-) diff --git a/sage/installation.md b/sage/installation.md index 97630375..5986a68c 100644 --- a/sage/installation.md +++ b/sage/installation.md @@ -18,29 +18,14 @@ authors: ## 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 run from a [WSL environment](https://docs.microsoft.com/en-us/windows/wsl/). ::: -### Node.js - -Sage requires 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/). - -To install Node.js and Yarn with Volta, run the following command: - -```shell -volta install node && npm install --global yarn -``` - -### Composer - -Sage requires Composer to manage PHP dependencies. If your platform supports [Homebrew](https://brew.sh/), you can install Composer with: - -```shell -brew install composer -``` - -Otherwise, [see Composer's documentation](https://getcomposer.org/download/) for installation instructions. + ## Create a new theme with Sage From f99443227e373c5b470a1e97be7e5a74bb0e8658 Mon Sep 17 00:00:00 2001 From: MWDelaney Date: Tue, 14 May 2024 17:32:48 -0400 Subject: [PATCH 04/20] =?UTF-8?q?=F0=9F=93=9D=20Trellis=20installation=20g?= =?UTF-8?q?uide?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- sage/installation.md | 10 +-- trellis/installation.md | 168 +++++++++++----------------------------- 2 files changed, 46 insertions(+), 132 deletions(-) diff --git a/sage/installation.md b/sage/installation.md index 5986a68c..e899eb6e 100644 --- a/sage/installation.md +++ b/sage/installation.md @@ -38,12 +38,6 @@ Create a new WordPress theme using Sage with Composer from your WordPress themes composer create-project roots/sage your-theme-name ``` -To install the latest development version of Sage, add `dev-main` to the end of the command: - -```shell -composer create-project roots/sage your-theme-name dev-main -``` - ### 2. Edit `bud.config.js` to match your environment 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. @@ -65,7 +59,7 @@ app.setPublicPath('/app/themes/sage/public/'); .setProxyUrl('http://example.test') ``` -### 3. Build assets +### 3. Build the theme assets From your new Sage-based theme's directory, run: @@ -85,7 +79,7 @@ That's it! You're ready to activate your theme in WordPress and start developing ## What Next? -From here you might want to [explore the structure of your new Sage 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. +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. ## What is Sage? diff --git a/trellis/installation.md b/trellis/installation.md index b9397c06..53bbc0fb 100644 --- a/trellis/installation.md +++ b/trellis/installation.md @@ -14,160 +14,80 @@ authors: # Installation -## What is Trellis? -[Trellis](https://roots.io/trellis/) is a tool to create WordPress web servers and deploy WordPress sites. +## System requirements -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. +* [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) -### 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. +## Install Trellis CLI -
-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 -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. - -#### 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 -WordPress servers. - -Thanks to Ansible's YAML based configuration, Trellis is "infrastructure as -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!). +```shell +brew install roots/tap/trellis-cli +``` -#### 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. +## Create a new project with Trellis -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. +Choose a descriptive project name (and use it in place of the default example.com). We recommend the domain of the site for uniqueness. -#### 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. +```shell +trellis new example.com +``` -#### 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. +After you've created a project, the folder structure for a Trellis project will look like this: -#### 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/). +```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) +``` -#### 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. +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` -### Software installed -Trellis provisions a base Ubuntu 22.04 server by installing and configuring the following software: +## Start your development environment -* PHP 8.0+ -* 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/)) -* Let's Encrypt for free SSL certificates -* Composer -* WP-CLI -* sSMTP (mail delivery) -* Memcached -* Fail2ban and ferm +```shell +trellis up +``` -In addition to configuring common services like ntp, sshd, etc. +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`. -## Requirements +See [Local Development](/trellis/docs/local-development-environment/) for more information. -Trellis relies on a few other software tools. Make sure all dependencies have been installed before moving on: +## What's Next? -- [Python 3](./python.md) -- [trellis-cli](https://github.com/roots/trellis-cli) +### Encrypt your vault files -### Local development requirements -If you want to use Trellis' built-in Vagrant integration, you'll need the -following as well: +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. -- [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) +::: note Shut down your development environment -::: 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)).** +Before you encrypt your vault files, make sure to shut down your development environment with `trellis down`. ::: -## Install trellis-cli - -Install [trellis-cli](https://github.com/roots/trellis-cli) via [Homebrew](https://brew.sh/): - ```shell -$ brew install roots/tap/trellis-cli +trellis vault encrypt ``` -## Create a project +### Provision your `production` server -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. +Before deploying to production, you'll need to provision your server. Check out [Provisioning](/trellis/docs/remote-server-setup//) for details. ```shell -$ trellis new example.com +trellis provision production ``` -Or to explicitly set the site name and host, use the following: +### Deploy to `production` -```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: +When you're ready to deploy your site to production, check out the [Deployments](/trellis/docs/deployments) for details. ```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) +trellis deploy production example.com ``` - -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 From cdddbb5c61935b9cbbc67bd1c3e373d1e8e2a1cc Mon Sep 17 00:00:00 2001 From: MWDelaney Date: Tue, 14 May 2024 17:34:57 -0400 Subject: [PATCH 05/20] =?UTF-8?q?=F0=9F=92=A1=20Credit?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- trellis/installation.md | 1 + 1 file changed, 1 insertion(+) diff --git a/trellis/installation.md b/trellis/installation.md index 53bbc0fb..ef84fa51 100644 --- a/trellis/installation.md +++ b/trellis/installation.md @@ -10,6 +10,7 @@ authors: - nikitasol - swalkinshaw - TangRufus + - MWDelaney --- # Installation From 258bd4687b3e0a3fa56c0c80312dad7bb7de50ae Mon Sep 17 00:00:00 2001 From: MWDelaney Date: Tue, 14 May 2024 17:44:34 -0400 Subject: [PATCH 06/20] =?UTF-8?q?=F0=9F=93=9D=20Revise=20Bedrock=20install?= =?UTF-8?q?ation=20for=20accessability?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- bedrock/installation.md | 35 +++++++++-------- trellis/installation.md | 87 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 105 insertions(+), 17 deletions(-) diff --git a/bedrock/installation.md b/bedrock/installation.md index c22ea935..acdcfa8d 100644 --- a/bedrock/installation.md +++ b/bedrock/installation.md @@ -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/trellis/installation.md b/trellis/installation.md index ef84fa51..ea33a67e 100644 --- a/trellis/installation.md +++ b/trellis/installation.md @@ -92,3 +92,90 @@ When you're ready to deploy your site to production, check out the [Deployments] ```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 +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. + +#### 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 +WordPress servers. + +Thanks to Ansible's YAML based configuration, Trellis is "infrastructure as +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!). + +#### 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. + +#### 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. + +#### 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. + +#### 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/). + +#### 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. + +
+ +### Trellis servers are production-ready + +Trellis provisions a base Ubuntu 22.04 server by installing and configuring the following software: + +* PHP 8.0+ +* 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/)) +* Let's Encrypt for free SSL certificates +* Composer +* WP-CLI +* sSMTP (mail delivery) +* Memcached +* Fail2ban and ferm + +In addition to configuring common services like ntp, sshd, etc. From c7a7ea4afe6e0aedcf964b85968205381820e265 Mon Sep 17 00:00:00 2001 From: MWDelaney Date: Wed, 15 May 2024 15:00:36 -0400 Subject: [PATCH 07/20] =?UTF-8?q?=F0=9F=93=9D=20Re-focus=20on=20provisioni?= =?UTF-8?q?ng=20rather=20than=20deployment?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refocused document on provisioning, moving technical details and deployment information out of the way and focusing on the task of provisoining. --- trellis/remote-server-setup.md | 75 ++++++++++------------------------ 1 file changed, 21 insertions(+), 54 deletions(-) diff --git a/trellis/remote-server-setup.md b/trellis/remote-server-setup.md index 0181c707..8fe78e9f 100644 --- a/trellis/remote-server-setup.md +++ b/trellis/remote-server-setup.md @@ -14,66 +14,38 @@ authors: # 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. +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. -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: +Trellis also deploys your WordPress site to your `staging` and `production` servers with zero downtime. -- [Provision](#provision) -- [Deploy](#deploy) +## (Remote) system requirements -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. - -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 -``` - -## 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). +### Provision your server -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: +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 +## What's Next? -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. +[Deploy your site](/trellis/docs/deployments/) to your server! -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: +## The technical details -```shell -$ trellis deploy -``` - -## 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. From cd4d36187c42e4c2206ab16e6f9683dbff955c03 Mon Sep 17 00:00:00 2001 From: MWDelaney Date: Wed, 15 May 2024 15:01:47 -0400 Subject: [PATCH 08/20] =?UTF-8?q?=F0=9F=92=A1=20Credit?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- trellis/deployments.md | 9 +++++++++ trellis/remote-server-setup.md | 1 + 2 files changed, 10 insertions(+) diff --git a/trellis/deployments.md b/trellis/deployments.md index 36c9e8bb..e0728d82 100644 --- a/trellis/deployments.md +++ b/trellis/deployments.md @@ -16,6 +16,11 @@ authors: Trellis offers zero-downtime WordPress deployment out of the box with little configuration needed. +::: 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. +::: + ## Configuration 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). @@ -189,3 +194,7 @@ By default Trellis stores 5 previous releases, not including the current release ## Deploying to other hosts Trellis can deploy to other hosts that support SSH, Composer, and WP-CLI, along with updating the web root path. + +## Resources + +- [Using Trellis to Provision and Deploy to DigitalOcean Droplets](https://roots.io/trellis/docs/deploy-to-digitalocean/) diff --git a/trellis/remote-server-setup.md b/trellis/remote-server-setup.md index 8fe78e9f..eea11f78 100644 --- a/trellis/remote-server-setup.md +++ b/trellis/remote-server-setup.md @@ -10,6 +10,7 @@ authors: - MWDelaney - nicbovee - swalkinshaw + - MWDelaney --- # Remote Server Setup From 134ac6441ef7154cb69efe01e70a34f487fd1598 Mon Sep 17 00:00:00 2001 From: MWDelaney Date: Wed, 15 May 2024 15:47:21 -0400 Subject: [PATCH 09/20] =?UTF-8?q?=F0=9F=93=9D=20Refocus=20deployment=20doc?= =?UTF-8?q?=20on=20deployment?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Moved the deployment-focused content to the top, moved optional configuration and details further down --- trellis/deployments.md | 68 ++++++++++++++++------------------ trellis/remote-server-setup.md | 1 - 2 files changed, 31 insertions(+), 38 deletions(-) diff --git a/trellis/deployments.md b/trellis/deployments.md index e0728d82..d20c5c63 100644 --- a/trellis/deployments.md +++ b/trellis/deployments.md @@ -14,11 +14,11 @@ 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. +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 @@ -27,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. @@ -171,30 +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. - -## Resources - -- [Using Trellis to Provision and Deploy to DigitalOcean Droplets](https://roots.io/trellis/docs/deploy-to-digitalocean/) diff --git a/trellis/remote-server-setup.md b/trellis/remote-server-setup.md index eea11f78..7c568767 100644 --- a/trellis/remote-server-setup.md +++ b/trellis/remote-server-setup.md @@ -44,7 +44,6 @@ Modify your project's `group_vars//wordpress_sites.yml` file to mat Run the following command from your local machine: - ```shell trellis provision ``` From c4e528b83b1a9b1bb65fcde91b3cde6cacc13528 Mon Sep 17 00:00:00 2001 From: MWDelaney Date: Wed, 15 May 2024 16:01:13 -0400 Subject: [PATCH 10/20] =?UTF-8?q?=F0=9F=93=9D=20Update=20vault=20doc=20to?= =?UTF-8?q?=20focus=20on=20vault=20tasks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move simple instructions for common vault tasks to the top of the page; move complicated Ansible Vault information lower --- trellis/installation.md | 13 +++----- trellis/vault.md | 66 +++++++++++++++++++++++++++-------------- 2 files changed, 48 insertions(+), 31 deletions(-) diff --git a/trellis/installation.md b/trellis/installation.md index ea33a67e..4bafdc43 100644 --- a/trellis/installation.md +++ b/trellis/installation.md @@ -64,18 +64,13 @@ See [Local Development](/trellis/docs/local-development-environment/) for more i ## What's Next? -### 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. +### Configure your environments -::: note Shut down your development environment +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. -Before you encrypt your vault files, make sure to shut down your development environment with `trellis down`. -::: +### Encrypt your vault files -```shell -trellis vault encrypt -``` +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 diff --git a/trellis/vault.md b/trellis/vault.md index cfa93b73..446640ff 100644 --- a/trellis/vault.md +++ b/trellis/vault.md @@ -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 From 2e2c3199502e8a05d447fc8ec50d81d304985ed8 Mon Sep 17 00:00:00 2001 From: MWDelaney Date: Thu, 16 May 2024 13:25:45 -0400 Subject: [PATCH 11/20] =?UTF-8?q?=F0=9F=93=9D=20Re-arrange=20Sage=20deploy?= =?UTF-8?q?ment=20docs=20to=20focus=20on=20the=20"how"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- sage/deployment.md | 37 ++++++++++++++++++++++++++++--------- 1 file changed, 28 insertions(+), 9 deletions(-) diff --git a/sage/deployment.md b/sage/deployment.md index 3597a7f9..b0d20e3c 100644 --- a/sage/deployment.md +++ b/sage/deployment.md @@ -1,25 +1,19 @@ --- date_modified: 2024-01-18 13:30 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,31 @@ Generate production ready assets with `yarn build`. - Tokenizer PHP Extension - XML PHP Extension +## Deploying Sage + +::: 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? From a683b13c945916036eae59e16fe11f16eaab5eaf Mon Sep 17 00:00:00 2001 From: MWDelaney Date: Thu, 16 May 2024 13:26:34 -0400 Subject: [PATCH 12/20] =?UTF-8?q?=F0=9F=93=9D=20Better=20wording?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- sage/deployment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sage/deployment.md b/sage/deployment.md index b0d20e3c..235137e3 100644 --- a/sage/deployment.md +++ b/sage/deployment.md @@ -25,7 +25,7 @@ authors: - Tokenizer PHP Extension - XML PHP Extension -## Deploying Sage +## 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. From 05cdd65b72b1840e94e20f7657c30692de49bcf8 Mon Sep 17 00:00:00 2001 From: MWDelaney Date: Thu, 16 May 2024 13:27:18 -0400 Subject: [PATCH 13/20] =?UTF-8?q?=F0=9F=93=9D=20Fix=20markdown=20language?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- sage/structure.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/sage/structure.md b/sage/structure.md index 3866d172..a48a6348 100644 --- a/sage/structure.md +++ b/sage/structure.md @@ -18,7 +18,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 +74,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. - From 41e8fa74e73a97455d76c21dfdf9cffc9b95a74d Mon Sep 17 00:00:00 2001 From: MWDelaney Date: Fri, 17 May 2024 14:03:58 -0400 Subject: [PATCH 14/20] =?UTF-8?q?=E2=9A=B0=EF=B8=8F=20Remove=20unnecessary?= =?UTF-8?q?=20details?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- sage/tailwind-css.md | 71 -------------------------------------------- 1 file changed, 71 deletions(-) diff --git a/sage/tailwind-css.md b/sage/tailwind-css.md index df954a2c..aa6b991c 100644 --- a/sage/tailwind-css.md +++ b/sage/tailwind-css.md @@ -38,74 +38,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. From e01495f9ee427fa19b316c385a2b865acab512fc Mon Sep 17 00:00:00 2001 From: MWDelaney Date: Wed, 22 May 2024 11:17:44 -0400 Subject: [PATCH 15/20] =?UTF-8?q?=F0=9F=93=9D=20Add=20credit,=20update=20d?= =?UTF-8?q?ates?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- bedrock/installation.md | 2 +- sage/deployment.md | 2 +- sage/installation.md | 2 +- sage/structure.md | 3 ++- sage/tailwind-css.md | 3 ++- trellis/deployments.md | 2 +- trellis/installation.md | 2 +- trellis/remote-server-setup.md | 2 +- trellis/vault.md | 2 +- 9 files changed, 11 insertions(+), 9 deletions(-) diff --git a/bedrock/installation.md b/bedrock/installation.md index acdcfa8d..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 diff --git a/sage/deployment.md b/sage/deployment.md index 235137e3..6e823cb1 100644 --- a/sage/deployment.md +++ b/sage/deployment.md @@ -1,5 +1,5 @@ --- -date_modified: 2024-01-18 13:30 +date_modified: 2024-05-22 11:15 date_published: 2015-09-01 19:29 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 diff --git a/sage/installation.md b/sage/installation.md index e899eb6e..1c71d614 100644 --- a/sage/installation.md +++ b/sage/installation.md @@ -1,5 +1,5 @@ --- -date_modified: 2024-04-14 12:23 +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 diff --git a/sage/structure.md b/sage/structure.md index a48a6348..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 diff --git a/sage/tailwind-css.md b/sage/tailwind-css.md index aa6b991c..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 diff --git a/trellis/deployments.md b/trellis/deployments.md index d20c5c63..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 diff --git a/trellis/installation.md b/trellis/installation.md index 4bafdc43..2f01cd68 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 diff --git a/trellis/remote-server-setup.md b/trellis/remote-server-setup.md index 7c568767..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 diff --git a/trellis/vault.md b/trellis/vault.md index 446640ff..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 From 42bf735893b9a7327385f67fbe05721139bf5d32 Mon Sep 17 00:00:00 2001 From: MWDelaney Date: Wed, 22 May 2024 11:50:08 -0400 Subject: [PATCH 16/20] =?UTF-8?q?=F0=9F=90=9B=20Close=20warning=20fence?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- sage/deployment.md | 1 + 1 file changed, 1 insertion(+) diff --git a/sage/deployment.md b/sage/deployment.md index 6e823cb1..f713c060 100644 --- a/sage/deployment.md +++ b/sage/deployment.md @@ -29,6 +29,7 @@ authors: ::: 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 From db4272b32df73efef554f9edffc4e84cdf79120e Mon Sep 17 00:00:00 2001 From: MWDelaney Date: Wed, 22 May 2024 12:05:14 -0400 Subject: [PATCH 17/20] =?UTF-8?q?=F0=9F=90=9B=20Re-arrange=20installation?= =?UTF-8?q?=20pages?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- sage/installation.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/sage/installation.md b/sage/installation.md index 1c71d614..fb9308b7 100644 --- a/sage/installation.md +++ b/sage/installation.md @@ -16,10 +16,21 @@ authors: # Installing Sage +## What is Sage? + +Sage is a [WordPress starter theme](https://roots.io/sage/). + +## Why use Sage? + +- 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). + ## System Requirements -* [Node.js](https://nodejs.org/) -* [Composer](https://getcomposer.org/download/) +- [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 run from a [WSL environment](https://docs.microsoft.com/en-us/windows/wsl/). @@ -80,14 +91,3 @@ That's it! You're ready to activate your theme in WordPress and start developing ## What Next? 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. - -## What is Sage? - -Sage is a [WordPress starter theme](https://roots.io/sage/). - -## Why use Sage? - -- 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). From 55ad413334b75a341f5baf25d014818480cda874 Mon Sep 17 00:00:00 2001 From: MWDelaney Date: Thu, 30 May 2024 16:55:46 -0400 Subject: [PATCH 18/20] =?UTF-8?q?=F0=9F=93=9D=20Add=20details=20for=20Wind?= =?UTF-8?q?ows/WSL=20users?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- trellis/installation.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/trellis/installation.md b/trellis/installation.md index 2f01cd68..6ea4580a 100644 --- a/trellis/installation.md +++ b/trellis/installation.md @@ -22,6 +22,18 @@ authors: * [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 WSL2 +* 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 From 60b208f8f723f5bf979c3d799c271b8c5b364acc Mon Sep 17 00:00:00 2001 From: MWDelaney Date: Thu, 30 May 2024 16:58:35 -0400 Subject: [PATCH 19/20] =?UTF-8?q?=F0=9F=93=9D=20Include=20paths?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- trellis/installation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/trellis/installation.md b/trellis/installation.md index 6ea4580a..67da65f7 100644 --- a/trellis/installation.md +++ b/trellis/installation.md @@ -24,9 +24,9 @@ authors: ### Additional requirements for Windows users * [WSL2](https://docs.microsoft.com/en-us/windows/wsl/install) -* Vagrant must be installed in WSL2 +* Vagrant must be installed in WSL * VirtualBox must be installed in Windows -* The following must be set in your WSL `.bashrc` or `.zshrc` file: +* 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` From 32fbaa160fbb14cca4d0da08502d1b01cb712956 Mon Sep 17 00:00:00 2001 From: MWDelaney Date: Thu, 30 May 2024 16:59:22 -0400 Subject: [PATCH 20/20] =?UTF-8?q?=F0=9F=93=9D=20Fix=20quotes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- trellis/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/trellis/installation.md b/trellis/installation.md index 67da65f7..54475289 100644 --- a/trellis/installation.md +++ b/trellis/installation.md @@ -27,7 +27,7 @@ authors: * 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` + * `VAGRANT_WSL_ENABLE_WINDOWS_ACCESS = 1` * `export PATH=“$PATH:/mnt/c/Program Files/Oracle/VirtualBox` ::: warning Windows users