Wordpress multisite

.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
 

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'
+    <snip>
+    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)

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'
-       ...
+       <snip>
        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'
+    <snip>
+    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).</br>
@@ -186,7 +208,7 @@ Such tasks include:
 
 To launch these tasks during the deploy hook,
 locate the `deploy:` section (below the `build:` section).</br>
-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')
+```
+<!-- @todo figure out the full expression for 1.5
+{{< note >}}
+If you decide to change the version of PHP to 8.1, the PHP 8.1 image ships with `jq` version 1.5. The jq function
+`map_values()` was not added until version 1.6. For version 1.5, you can simulate the function by using the [array
+unpack operator](https://jqlang.org/manual/v1.5/#.[]), feeding the results to your select function, and wrapping all of
+it as an array. For example, the `jq` expression for `UPSTREAM_URLS` for v1.5 of `jq` can be written as
+
+```bash {location=".environment"}
+export UPSTREAM_URLS=$(echo $SITE_ROUTES | jq -r --arg app "${PLATFORM_APPLICATION_NAME}" '[.[] | select(.type == "upstream" and .upstream == $app )] | keys')
+```
+{{< /note >}}
+
+-->
+
+## 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"
+    <snip>
+    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