diff --git a/.platform/applications.yaml b/.platform/applications.yaml index e2ed5db6ae..a8d17facbc 100644 --- a/.platform/applications.yaml +++ b/.platform/applications.yaml @@ -132,6 +132,10 @@ \.txt$: headers: Content-Type: "text/plain; charset=UTF-8" + '^/favicon.ico$': + allow: true + passthru: '/images/favicon.ico' + disk: 1024 diff --git a/sites/upsun/src/get-started/stacks/wordpress/bedrock.md b/sites/upsun/src/get-started/stacks/wordpress/bedrock.md index ead3691ed1..13a7733d36 100644 --- a/sites/upsun/src/get-started/stacks/wordpress/bedrock.md +++ b/sites/upsun/src/get-started/stacks/wordpress/bedrock.md @@ -47,7 +47,7 @@ applications: "/": root: "web" # The front-controller script to send non-static requests to. - passthru: "/index.php" + passthru: "/wp/index.php" # Wordpress has multiple roots (wp-admin) so the following is required index: - "index.php" @@ -131,7 +131,7 @@ application can receive requests. Such tasks include: - Running any due cron jobs To perform these tasks, we'll utilize the [deploy hook](/learn/overview/build-deploy.md#deploy-steps). Locate the -`deploy:` section (below the `build:` section). Update the `deploy:` section as follows: +`deploy:` section (below the `build:` section). Update the `deploy:` and `post_deploy` sections as follows: ```yaml {configFile="app"} applications: @@ -147,6 +147,7 @@ applications: wp cache flush # Runs the WordPress database update procedure wp core update-db + post_deploy: # Runs all due cron events wp cron event run --due-now ``` @@ -215,7 +216,12 @@ To configure the remaining environment variables that WordPress needs to run smo 2. Add the following at the end of the file: ```bash {location=".environment"} - export WP_HOME=$(echo $PLATFORM_ROUTES | base64 --decode | jq -r 'to_entries[] | select(.value.primary == true) | .key') + # Routes, URLS, and primary domain + export SITE_ROUTES=$(echo $PLATFORM_ROUTES | base64 --decode) + export UPSTREAM_URLS=$(echo $SITE_ROUTES | jq -r --arg app "${PLATFORM_APPLICATION_NAME}" 'map_values(select(.type == "upstream" and .upstream == $app )) | keys') + export DOMAIN_CURRENT_SITE=$(echo $SITE_ROUTES | jq -r --arg app "${PLATFORM_APPLICATION_NAME}" 'map_values(select(.primary == true and .type == "upstream" and .upstream == $app )) | keys | .[0] | if (.[-1:] == "/") then (.[0:-1]) else . end') + + export WP_HOME="${DOMAIN_CURRENT_SITE}" export WP_SITEURL="${WP_HOME}/wp" export WP_DEBUG_LOG=/var/log/app.log # Uncomment this line if you would like development versions of WordPress on non-production environments. @@ -239,6 +245,33 @@ You can now commit all the changes made to `.upsun/config.yaml` and `.environmen upsun push -y ``` +## 9. Routinely run WP Cron (optional) +If your site does not receive enough traffic to ensure [WP Cron jobs](https://developer.wordpress.org/plugins/cron/) run +in a timely manner, or your site uses caching heavily such that WP Cron isn't being triggered, you might consider adding +a [cron job](/create-apps/app-reference/single-runtime-image.html#crons) to your project's configuration to have WP CLI +run those scheduled tasks on a routine basis. To do so, locate the `crons:` section that is commented out, and update it +as follows: + +```yaml {configFile="app"} + applications: + myapp: + source: + root: "/" + type: 'php:8.3' + + crons: + wp-cron: + spec: '*/15 * * * *' + commands: + start: wp cron event run --due-now + shutdown_timeout: 600 +``` +The above example will trigger the wp-cli every 15th minute to run WP Cron tasks that are due. Feel free to adjust based +on your individual requirements. + +{{< note theme="info">}} +When uncommenting, pay attention to the indentation and make sure that the `crons` key aligns with other sibling keys (e.g. `hooks`, `dependencies`, etc.) +{{< /note >}} ## Further resources - [All example files (`.environment`, `.upsun/config.yaml`)](https://github.com/upsun/snippets/tree/main/examples/wordpress-bedrock) diff --git a/sites/upsun/src/get-started/stacks/wordpress/composer.md b/sites/upsun/src/get-started/stacks/wordpress/composer.md index 93230f66ab..af21586dcf 100644 --- a/sites/upsun/src/get-started/stacks/wordpress/composer.md +++ b/sites/upsun/src/get-started/stacks/wordpress/composer.md @@ -34,12 +34,14 @@ The instructions on this page were designed based on the following assumptions: To ensure you have all the required files and directories in your project, follow these steps: -1. Copy the following files from the [WordPress Composer template](https://github.com/platformsh-templates/wordpress-composer/) +1. Copy the following files from the [WordPress Composer Example Snippets](https://github.com/upsun/snippets/tree/main/examples/wordpress-composer) and add them to the root of your project: - - The [composer.json](https://raw.githubusercontent.com/platformsh-templates/wordpress-composer/61da65da21039b280b588642cd329a2eb253e472/composer.json) file declares project dependencies and specifies project settings and metadata for [Composer](https://getcomposer.org/) to use - - The [wp-cli.yml](https://github.com/platformsh-templates/wordpress-composer/blob/61da65da21039b280b588642cd329a2eb253e472/wp-cli.yml) file contains the configuration values, related to your site, for the [WordPress CLI](https://wp-cli.org/) to use - - The [wp-config.php](https://github.com/platformsh-templates/wordpress-composer/blob/61da65da21039b280b588642cd329a2eb253e472/wp-config.php) file contains your site's base configuration details, such as database connection information + - The [composer.json](https://raw.githubusercontent.com/upsun/snippets/refs/heads/main/examples/wordpress-composer/composer.json) file declares project dependencies and specifies project settings and metadata for [Composer](https://getcomposer.org/) to use + - The [wp-cli.yml](https://raw.githubusercontent.com/upsun/snippets/refs/heads/main/examples/wordpress-composer/wp-cli.yml) file contains the configuration values, related to your site, for the [WordPress CLI](https://wp-cli.org/) to use + - The [.environment](https://raw.githubusercontent.com/upsun/snippets/refs/heads/main/examples/wordpress-composer/.environment) file maps and creates environment variables to be used in `wp-config.php` + - The [wp-config.php](https://raw.githubusercontent.com/upsun/snippets/refs/heads/main/examples/wordpress-composer/wp-config.php) file contains your site's base configuration details, such as database connection information + 2. Optional: To support non-public plugins, add a `plugins` directory to your project. To ensure Git tracks empty folders, add a `plugins/.gitkeep` file as well. @@ -48,16 +50,13 @@ To ensure Git tracks empty folders, add a `plugins/.gitkeep` file as well. ```bash {location="Terminal"} git add . - git commit -m "Add files and directory" - git push + git commit -m "Adds initial WordPress and Upsun configuration files" ``` -Now that you have pushed all the necessary files and directories to Upsun, -make the following changes to your `./.upsun/config.yaml` file. - ## 2. Configure your root location - -Locate the `web:locations` section and update the root (`/`) location as follows: +Now that we have added the initial set of files to our repository, we need to make some additional modifications to the +Upsun configuration, so Upsun knows how to handle certain requests. Locate the `web:locations` section in the +`.upsun/config.yaml` file and update the root (`/`) location as follows: ```yaml {configFile="app"} applications: @@ -136,7 +135,7 @@ To set one up, follow these steps: source: root: "/" type: 'php:8.3' - ... + mounts: "wordpress/wp-content/uploads": source: storage @@ -148,7 +147,30 @@ To set one up, follow these steps: mount location accordingly. {{< /note >}} -## 4. Install dependencies during the build hook +## 4. Install the WP-CLI +To ensure we are able to perform tasks later in the deployment stage (e.g. updating the database, flushing cache, etc.) +we need to make sure the [wp-cli](https://wp-cli.org/) utility is a dependency of the application container. While still +in the `.upsun/config.yaml` file, locate the `dependencies.php` section, and add the following: + +```yaml {configFile="app"} +applications: + myapp: + source: + root: "/" + type: 'php:8.3' + + dependencies: + php: + composer/composer: "^2" + wp-cli/wp-cli-bundle: "^2.4" +``` + +{{< note >}} +It is possible the `dependencies` section is commented out. When uncommenting, pay attention to the indentation and that +the `dependencies` key aligns with other sibling keys (e.g. `build`, `hooks`, etc.) +{{< /note >}} + +## 5. Install dependencies during the build hook To ensure your Composer dependencies are installed during the [build stage](/learn/overview/build-deploy.md#the-build), locate the `build:` section (below the `hooks:` section).
@@ -186,7 +208,7 @@ Such tasks include: To launch these tasks during the deploy hook, locate the `deploy:` section (below the `build:` section).
-Update the `deploy:` section as follows: +Update the `deploy:` and `post_deploy` sections as follows: ```yaml {configFile="app"} applications: @@ -202,6 +224,8 @@ applications: wp cache flush # Runs the WordPress database update procedure wp core update-db + post_deploy: | + set -eu # Runs all due cron events wp cron event run --due-now ``` @@ -235,31 +259,73 @@ routes: Matching the application name `myapp` with the `upstream` definition `myapp:http` is the most important setting to ensure at this stage. If these strings aren't the same, the WordPress deployment will not succeed. -## 7. Update your MariaDB service relationship +## 7. Update the `.environment` file -You need to update the name used to represent the [relationship](/create-apps/app-reference/single-runtime-image.md#relationships) between your app and your MariaDB service. -To do so, locate the `relationships:` top-level property. -Update the relationship for the database service as follows: +We need to add a few environment variables that will be used inside the `wp-config.php` file we added previously. +Open the `.environment` file. Just after the other database-related variables, add a blank line or two and add the +following: + +```bash {location=".environment"} +# Routes, URLS, and primary domain +export SITE_ROUTES=$(echo $PLATFORM_ROUTES | base64 --decode) +export UPSTREAM_URLS=$(echo $SITE_ROUTES | jq -r --arg app "${PLATFORM_APPLICATION_NAME}" 'map_values(select(.type == "upstream" and .upstream == $app )) | keys') +export DOMAIN_CURRENT_SITE=$(echo $SITE_ROUTES | jq -r --arg app "${PLATFORM_APPLICATION_NAME}" 'map_values(select(.primary == true and .type == "upstream" and .upstream == $app )) | keys | .[0] | if (.[-1:] == "/") then (.[0:-1]) else . end') +``` + + +## 9. Commit and push + +You can now commit all the changes made to `.upsun/config.yaml` and `.environment` and push to {{% vendor/name %}}. + + ```bash {location="Terminal"} + git add . + git commit -m "Add changes to complete my upsun configuration" + {{% vendor/cli %}} push + ``` +## 10. Install WordPress + +Once {{% vendor/name %}} has completed building and deploying your project, it will provide the list of routes assigned +to your project. You can now visit your site and complete the WordPress installation as you normally would. + +## 11. Routinely run WP Cron (optional) +If your site does not receive enough traffic to ensure [WP Cron jobs](https://developer.wordpress.org/plugins/cron/) run +in a timely manner, or your site uses caching heavily such that WP Cron isn't being triggered, you might consider adding +a [cron job](/create-apps/app-reference/single-runtime-image.html#crons) to your project's configuration to have WP CLI +run those scheduled tasks on a routine basis. To do so, locate the `crons:` section that is commented out, and update it +as follows: ```yaml {configFile="app"} -applications: + applications: myapp: source: root: "/" type: 'php:8.3' - # ... - relationships: - database: "mariadb:mysql" + + crons: + wp-cron: + spec: '*/15 * * * *' + commands: + start: wp cron event run --due-now + shutdown_timeout: 600 ``` +The above example will trigger the wp-cli every 15th minute to run WP Cron tasks that are due. Feel free to adjust based +on your individual requirements. -You can now commit all the changes made to `.upsun/config.yaml` and push to {{% vendor/name %}}. - - ```bash {location="Terminal"} - git add . - git commit -m "Add changes to complete my {{% vendor/name %}} configuration" - git push - ``` - +{{< note theme="info">}} +When uncommenting, pay attention to the indentation and that the `crons` key aligns with other sibling keys (e.g. `hooks`, `dependencies`, etc.) +{{< /note >}} ## Further resources diff --git a/sites/upsun/src/get-started/stacks/wordpress/multisite.md b/sites/upsun/src/get-started/stacks/wordpress/multisite.md new file mode 100644 index 0000000000..11a9c23c23 --- /dev/null +++ b/sites/upsun/src/get-started/stacks/wordpress/multisite.md @@ -0,0 +1,369 @@ +--- +title: Deploy WordPress Multisite on {{% vendor/name %}} +sidebarTitle: "WordPress Multisite" +weight: 1 +description: | + Complete the last required steps to successfully deploy a WordPress Multisite on Upsun. +--- + +{{< note theme="info" >}} + +Before you start, check out the [{{% vendor/name %}} demo app](https://console.upsun.com/projects/create-project) +and the main [Getting started guide](/get-started/here/_index.md). +These resources provide all the core concepts and common commands you need to know before using the following materials. + +{{< /note >}} + +You will need to make a few changes to your {{% vendor/name %}} configuration for WordPress Multisite to successfully +deploy and operate. + +Please note that these changes must only be made **after completing the +[Getting started guide](/get-started/here/_index.md)**. You should also already have a working WordPress site (see +**Assumptions** for the WordPress guides your WordPress site should be based on). + +{{% guides/requirements name="WordPress" %}} + +{{< note theme="info" title="Assumptions" >}} + +There are many ways you can set up a +[WordPress Multisite](https://developer.wordpress.org/advanced-administration/multisite/) +or {{% vendor/name %}} project. The instructions on this page are based on the following assumptions: + +- You selected **PHP** as your runtime, and **MariaDB** as a service during the Getting Started guide. It's also assumed +that while using the Getting Started guide you named the project `myapp`, which you will notice is the top-level key in +all configuration below. +- Your database relationship name is `mariadb` (the default) +- You have a working WordPress site based on either the [WordPress Composer](/get-started/stacks/wordpress/composer.html), +[Bedrock](https://docs.upsun.com/get-started/stacks/wordpress/bedrock.html), or +[WordPress Vanilla](/get-started/stacks/wordpress/vanilla.html) guides. +- WordPress is installed in the web/public root of the site and not in a subdirectory of its own (or in the default of +`wp` if you set up a Bedrock-based site) +- You know if you are creating a +[subdirectory-based multisite or a sub/multi-domain based multisite](https://developer.wordpress.org/advanced-administration/multisite/prepare-network/#types-of-multisite-network). +{{< /note >}} + +## 1. Add rewrite rules to your root location + +If you are setting up a subdirectory-based multisite, or you followed the Bedrock guide, the following rewrite rules are +**required**. If you followed the Composer based or Vanilla guides and are unsure, or if you think you might convert to +a subdirectory-based multisite later, you can add these rules to a sub/multi-domain multisite without any negative +effects. + +Locate the `web:locations` section in your `.upsun/config.yaml` file and update the rules section for your root (`/`) +location as follows: + +{{< codetabs >}} + ++++ +title=Vanilla, Composer +highlight=yaml ++++ + +applications: + myapp: + + web: + locations: + "/": + + rules: + ^/license\.text$: + allow: false + ^/readme\.html$: + allow: false + '^/([_0-9a-zA-Z-]+/)?wp-(?[a-z\-]+).php$': + allow: true + scripts: true + passthru: '/wp-$wproot.php' + # Allows directory-based multisites to still access the wp-admin and wp-include locations + '^/([_0-9a-zA-Z-]+/)?(?wp-(admin|includes).*)': + allow: true + scripts: true + passthru: '/$adminrewrite' + '^/([_0-9a-zA-Z-]+)/wp-content/(?.*)': + allow: true + scripts: false + passthru: '/wp-content/$content' + expires: 1w + +<---> + ++++ +title=Bedrock +highlight=yaml ++++ + +applications: + myapp: + + web: + locations: + "/": + + rules: + ^/license\.text$: + allow: false + ^/readme\.html$: + allow: false + '^/(?!wp/)([_0-9a-zA-Z-]+/)?wp-(?[a-z\-]+).php$': + allow: true + scripts: true + passthru: '/wp/wp-$wproot.php' + # Allows directory-based multisites to still access the wp-admin and wp-include locations + '^/(?!wp/)([_0-9a-zA-Z-]+/)?(?wp-(admin|includes).*)': + allow: true + scripts: true + passthru: '/wp/$adminrewrite' + '^/([_0-9a-zA-Z-]+)/wp-content/(?.*)': + allow: true + scripts: false + passthru: '/wp-content/$content' + expires: 1w + +{{< /codetabs >}} + + +{{< note theme="info" >}} +If you followed the Bedrock guide and decided to change the default name of the directory where WordPress is installed +(`wp`), then you will need to update both the rules and `passthru` keys accordingly. +{{< /note >}} + +## 2. Update the database during the deploy hook + +The domain(s) of your multisite are stored in the database itself. This creates a challenge in a system like Upsun where +you often create [preview environments](/glossary.html#preview-environment) dynamically during development. To ensure +the database for your preview environments is updated with the correct domains, we have created a +[wp-cli package](https://github.com/upsun/wp-ms-dbu) to automate the process of updating the database with the preview +environment's unique domain name. + +To install the wp-cli package, locate the `build:` section and update it as follows: + +```yaml {configFile="app"} +applications: + myapp: + + hooks: + build: | + set -eux + composer install --prefer-dist --optimize-autoloader --apcu-autoloader --no-progress --no-ansi --no-interaction + wp package install upsun/wp-ms-dbu + wp package update upsun/wp-ms-dbu +``` + +{{< note theme="info">}} +If you created your site based on the WordPress Vanilla guide, only add the lines above that start with `wp package` +(i.e. skip the `composer install` line). +{{< /note >}} + +To instruct the package to update your database with the relevant domains for the preview environment, locate the +`deploy` section and update it as follows: + +```yaml {configFile="app"} +applications: + myapp: + + hooks: + deploy: | + set -eu + # we need the main production url + PRODURL=$(echo $PLATFORM_ROUTES | base64 --decode | jq -r --arg app "${PLATFORM_APPLICATION_NAME}" '[.[] | select(.primary == true and .type == "upstream" and .upstream == $app )] | first | .production_url') + if [ 'production' != "${PLATFORM_ENVIRONMENT_TYPE}" ] && wp site list --format=count --url="${PRODURL}" >/dev/null 2>&1; then + echo "Updating the database..."; + wp ms-dbu update --url="${PRODURL}" + else + echo "Database appears to already be updated. Skipping."; + fi + # Flushes the object cache + wp cache flush + # Runs the WordPress database update procedure + wp core update-db +``` + + +## 3. `wp-config.php` / `config/application.php` + +Once our multisite has been set up, we need to expose additional pieces of information inside our `wp-config.php` (or +`./config/application.php` for Bedrock) file. In your wp-config.php/application.php file, right above the section +outlined below: + +{{< codetabs >}} + ++++ +title=wp-config.php (Vanilla, Composer) +highlight=php ++++ +/** Absolute path to the WordPress directory. */ +if ( ! defined( 'ABSPATH' ) ) { + define( 'ABSPATH', dirname( __FILE__ ) . '/' ); +} +<---> ++++ +title=config/application.php (Bedrock) +highlight=php ++++ +/** +* Bootstrap WordPress + */ + if (!defined('ABSPATH')) { + define('ABSPATH', $webroot_dir . '/wp/'); + } +{{< /codetabs >}} + + +add the following: + +{{< codetabs >}} ++++ +title=wp-config.php (Vanilla, Composer) +highlight=php ++++ +/** + * Multisite support + */ +define('WP_ALLOW_MULTISITE', true); //enables the Network setup panel in Tools +define('MULTISITE', false); //instructs WordPress to run in multisite mode + +if( MULTISITE && WP_ALLOW_MULTISITE) { + define('SUBDOMAIN_INSTALL', false); // does the instance contain subdirectory sites (false) or subdomain/multiple domain sites (true) + define('DOMAIN_CURRENT_SITE', parse_url(filter_var(getenv('DOMAIN_CURRENT_SITE'),FILTER_VALIDATE_URL),PHP_URL_HOST)); + define('PATH_CURRENT_SITE', '/'); //path to the WordPress site if it isn't the root of the site (e.g. https://foo.com/blog/) + define('SITE_ID_CURRENT_SITE', 1); //main/primary site ID + define('BLOG_ID_CURRENT_SITE', 1); //main/primary/parent blog ID + + /** + * we have a sub/multidomain multisite, and the site currently being requested is not the default domain, so we'll + * need to set COOKIE_DOMAIN to the domain being requested + */ + if (SUBDOMAIN_INSTALL && $site_host !== DOMAIN_CURRENT_SITE) { + define('COOKIE_DOMAIN',$site_host); + } +} + +<---> ++++ +title=config/application.php (Bedrock) +highlight=php ++++ +/** +* Multisite support +*/ +define('WP_ALLOW_MULTISITE', true); //enables the Network setup panel in Tools +define('MULTISITE', false); //instructs WordPress to run in multisite mode + +if( MULTISITE && WP_ALLOW_MULTISITE) { + define('SUBDOMAIN_INSTALL', false); // does the instance contain subdirectory sites (false) or subdomain/multiple domain sites (true) + define('DOMAIN_CURRENT_SITE', parse_url(filter_var(getenv('DOMAIN_CURRENT_SITE'),FILTER_VALIDATE_URL),PHP_URL_HOST)); + define('PATH_CURRENT_SITE', '/'); //path to the WordPress site if it isn't the root of the site (e.g. https://foo.com/blog/) + define('SITE_ID_CURRENT_SITE', 1); //main/primary site ID + define('BLOG_ID_CURRENT_SITE', 1); //main/primary/parent blog ID + + if (SUBDOMAIN_INSTALL && getenv('PLATFORM_RELATIONSHIPS')) { + $site_host = $_SERVER['HTTP_HOST']) ?? ""; + //we're not running locally so we need to make sure $site_host is set to something appropriate + try { + $validURLs = json_decode(getenv('UPSTREAM_URLS'), true, 512, JSON_THROW_ON_ERROR); + } catch (\JsonException $exception) { + $validURLs = []; + error_log($exception->getMessage()); + } + + //if site_host isnt a valid domain we're expecting, then set it to the default domain + if(!in_array($site_host, array_map(static function (string $url) { + return parse_url($url, PHP_URL_HOST); + }, $validURLs), true)) { + $site_host = parse_url(filter_var(getenv('DOMAIN_CURRENT_SITE'),FILTER_VALIDATE_URL),PHP_URL_HOST); + } + /** + * we have a sub/multidomain multisite, and the site currently being requested is not the default domain, so we'll + * need to set COOKIE_DOMAIN to the domain being requested + */ + if ($site_host !== DOMAIN_CURRENT_SITE) { + define('COOKIE_DOMAIN',$site_host); + } + } + +} +{{< /codetabs >}} + +`SUBDOMAIN_INSTALL` should be set to `true` if your multisite is a sub/multi-domain site, or `false` if you will be +setting up a subdirectory-based multisite. Note that `MULTISITE` is currently set to `false`; we will update this once +the database has finished being set up for the multisite. + +## 4. Commit and push +You can now commit all the changes made above `.upsun/config.yaml` and push to {{% vendor/name %}}. + + ```bash {location="Terminal"} + git add wp-config.php .environment .upsun/config.yaml + git commit -m "Add changes to begin setup of my {{% vendor/name %}} WordPress multisite" + {{% vendor/cli %}} push -y + ``` + + + +## 5. Network (Multisite) Setup +Adding `define('WP_ALLOW_MULTISITE', true);` will enable the **Network Setup** item in your **Tools menu**. Use that +menu item to go to the **Create a Network of WordPress Sites** screen. Follow the instructions on this screen and click +the **Install** button. You can ignore the instructions on the resulting screen. + +{{< note >}} +Alternatively, you can access a terminal session in the app container (`{{% vendor/cli %}} ssh`), and use +`wp core multisite-convert` to install the multisite. +{{< /note >}} + +## 6. Final change to `wp-config.php` / application.php +Return to your wp-config.php / application.php file and change + +```php +define('MULTISITE', false); +``` +to +```php +define('MULTISITE', true); +``` + +Add and commit the changes, then push to {{% vendor/name %}}: + +```shell {location="Terminal"} +git add wp-config.php +git commit -m "set WordPress to run in multisite mode." +{{% vendor/cli %}} push -y +``` + +Once the site has finished deploying, you can return to the Network Admin --> Sites area of wp-admin and begin adding your +sites. + + diff --git a/sites/upsun/src/get-started/stacks/wordpress/vanilla.md b/sites/upsun/src/get-started/stacks/wordpress/vanilla.md index 02f1633755..6fdb9f1e20 100644 --- a/sites/upsun/src/get-started/stacks/wordpress/vanilla.md +++ b/sites/upsun/src/get-started/stacks/wordpress/vanilla.md @@ -24,7 +24,7 @@ you still need to add some required files and make a few changes to your {{% ven There are many ways you can set up a WordPress site or {{% vendor/name %}} project. The instructions on this page were designed based on the following assumptions: -- You selected PHP as your runtime, and MariaDB as a service during the Getting Started guide. It's also assumed that +- You selected **PHP** as your runtime, and **MariaDB** as a service during the Getting Started guide. It's also assumed that while using the Getting Started guide you named the project `myapp`, which you will notice is the top-level key in all configuration below. - You are currently in the same directory where you created your project during the Getting Started guide. @@ -57,19 +57,22 @@ download a zip archive from WordPress.org, or use `curl` to download a tarball: 5. Create a `wp-config.php` file inside the directory from step 4 and copy and paste the contents from [this example file](https://github.com/upsun/snippets/blob/main/examples/wordpress-vanilla/wordpress/wp-config.php). -6. Optional: if you plan on using [wp-cli](https://wp-cli.org/), add a `wp-cli.yml` file and add the following contents +6. To make using [wp-cli](https://wp-cli.org/) easier, add a `wp-cli.yml` file and add the following contents to it: ```yaml path: /app/wordpress/ color: true ``` - - **Note**: If you changed the name of the directory at step 4 you'll need to update the `path` property above to match. + {{< note theme="info" >}} +If you changed the name of the directory at step 4 you'll need to update the `path` property above to match. + {{< /note >}} 7. Add all the files from the steps above to your repository - 1. `git add .` - 2. `git commit -m "adds wordpress core files"` + ```bash location="Terminal" + git add . + git commit -m "adds wordpress core files" + ``` ## 2. Update configuration files @@ -131,6 +134,11 @@ If you changed the name of the directory at step 1.4 you'll need to update the ` source_path: "uploads" ``` + {{< note theme="info">}} +When uncommenting, pay attention to the indentation and that the `mounts` key aligns with other sibling keys (e.g. `relationships`, `web`, etc.) + {{< /note >}} + + 4. Once the images for our application have been built, there are a few key tasks that must be completed before our newly-built application can receive requests. These tasks include: @@ -138,8 +146,9 @@ If you changed the name of the directory at step 1.4 you'll need to update the ` - Running the WordPress database update procedure, in case core is being updated with the newly deployed changes - Running any due cron jobs - To perform these tasks, we'll utilize the [deploy hook](/learn/overview/build-deploy.md#deploy-steps). Locate the - `deploy:` section (below the `build:` section). Update the `deploy:` section as follows: + To perform these tasks, we'll utilize the [`deploy`](/learn/overview/build-deploy.md#deploy-steps) and + [`post_deploy`](/create-apps/hooks/hooks-comparison.html#post-deploy-hook) hooks. Locate the `deploy:` section + (below the `build:` section). Update the `deploy:` section as follows: ```yaml {configFile="app"} applications: @@ -150,11 +159,13 @@ If you changed the name of the directory at step 1.4 you'll need to update the ` hooks: deploy: | - set -eux + set -eu # Flushes the object cache wp cache flush # Runs the WordPress database update procedure wp core update-db + post_deploy: | + set -eu # Runs all due cron events wp cron event run --due-now ``` @@ -180,26 +191,36 @@ If you changed the name of the directory at step 1.4 you'll need to update the ` - '/^wp-*/' ``` -6. Optional: Add the wp-cli tool to your application build. Locate the `dependencies:` section that is commented out, - and update it as follows: +6. To ensure we are able to perform tasks later in the deployment stage (e.g. updating the database, flushing cache, etc.) + we need to make sure the [wp-cli](https://wp-cli.org/) utility is a dependency of the application container. While still + in the `.upsun/config.yaml` file, locate the `dependencies.php` section, and add the following: - ```yaml {configFile="app"} - applications: - myapp: - source: - root: "/" - type: 'php:8.3' - - dependencies: - php: - wp-cli/wp-cli-bundle: "^2.4" + ```yaml {configFile="app"} + applications: + myapp: + source: + root: "/" + type: 'php:8.3' + + dependencies: + php: + composer/composer: "^2" + wp-cli/wp-cli-bundle: "^2.4" ``` + {{< note theme="info" >}} + +It is possible the `dependencies` section is commented out. When uncommenting, pay attention to the indentation and that +the `dependencies` key aligns with other sibling keys (e.g. `build`, `hooks`, etc.) + + {{< /note >}} + + 7. Add and commit your changes. ```bash {location="Terminal"} git add .upsun/config.yaml - git commit -m "Updates configuration file" + git commit -m "Updates {{% vendor/name %}} configuration file" ``` ## 3. Update `.environment` @@ -218,29 +239,58 @@ export DB_PASSWORD="$MARIADB_PASSWORD" export DB_SCHEME="$MARIADB_SCHEME" export DATABASE_URL="${DB_SCHEME}://${DB_USERNAME}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_PATH}" ``` -To configure the remaining environment variables WordPress needs to run smoothly, follow these steps. -1. Open the `.environment` file for editing -2. Add the following at the end of the file: - - ```bash {location=".environment"} - export WP_HOME=$(echo $PLATFORM_ROUTES | base64 --decode | jq -r 'to_entries[] | select(.value.primary == true) | .key') - export WP_SITEURL="${WP_HOME}wordpress" - export WP_DEBUG_LOG=/var/log/app.log - if [ "$PLATFORM_ENVIRONMENT_TYPE" != "production" ] ; then - export WP_ENV='development' - else - export WP_ENV='production' - fi - ``` -3. Add and commit your changes: - 1. `git add .environment` - 2. `git commit -m "adds remaining environment variables to .environment"` +To configure the remaining environment variables WordPress needs to run smoothly, open the `.environment` file. Just +after the other database-related variables, add a blank line or two and add the following: + +```bash {location=".environment"} +# Routes, URLS, and primary domain +export SITE_ROUTES=$(echo $PLATFORM_ROUTES | base64 --decode) +export UPSTREAM_URLS=$(echo $SITE_ROUTES | jq -r --arg app "${PLATFORM_APPLICATION_NAME}" 'map_values(select(.type == "upstream" and .upstream == $app )) | keys') +export DOMAIN_CURRENT_SITE=$(echo $SITE_ROUTES | jq -r --arg app "${PLATFORM_APPLICATION_NAME}" 'map_values(select(.primary == true and .type == "upstream" and .upstream == $app )) | keys | .[0] | if (.[-1:] == "/") then (.[0:-1]) else . end') +``` + +Save, add, and commit those changes: +```bash {location="Terminal"} +git add .environment +git commit -m "adds remaining environment variables to .environment" +``` ## 4. Push and deploy Now that we've added the required files, you're ready to push your changes and deploy your WordPress site: -```bash -upsun push -y +```bash {location="Terminal"} + +{{% vendor/cli %}} push -y + ``` + +## 5. Routinely run WP Cron (optional) +If your site does not receive enough traffic to ensure [WP Cron jobs](https://developer.wordpress.org/plugins/cron/) run +in a timely manner, or your site uses caching heavily such that WP Cron isn't being triggered, you might consider adding +a [cron job](/create-apps/app-reference/single-runtime-image.html#crons) to your project's configuration to have WP CLI +run those scheduled tasks on a routine basis. To do so, locate the `crons:` section that is commented out, and update it +as follows: + +```yaml {configFile="app"} + applications: + myapp: + source: + root: "/" + type: 'php:8.3' + + crons: + wp-cron: + spec: '*/15 * * * *' + commands: + start: wp cron event run --due-now + shutdown_timeout: 600 +``` +The above example will trigger the wp-cli every 15th minute to run WP Cron tasks that are due. Feel free to adjust based +on your individual requirements. + + {{< note theme="info">}} +When uncommenting, pay attention to the indentation and that the `crons` key aligns with other sibling keys (e.g. `hooks`, `dependencies`, etc.) + {{< /note >}} + ## Further resources - [All files (Upsun configuration, `.environment`, `wp-cli.yml`, `wp-config.php`)](https://github.com/upsun/snippets/tree/main/examples/wordpress-vanilla) ### Documentation