Deploy Composer-based WordPress on Upsun

For WordPress to successfully deploy and operate, after completing the Getting started guide, you still need to add some required files and make a few changes to your Upsun configuration.

Before you begin

You need:

• Git. Git is the primary tool to manage everything your app needs to run. Push commits to deploy changes and control configuration through YAML files. These files describe your infrastructure, making it transparent and version-controlled.
• A Upsun account. If you don’t already have one, register for a trial account. You can sign up with an email address or an existing GitHub, Bitbucket, or Google account. If you choose one of these accounts, you can set a password for your Upsun account later.
• The Upsun CLI. This lets you interact with your project from the command line. You can also do most things through the Web Console.

1. Add required files

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 Example Snippets and add them to the root of your project:

   • The composer.json file declares project dependencies and specifies project settings and metadata for Composer to use
   • The wp-cli.yml file contains the configuration values, related to your site, for the WordPress CLI to use
   • The .environment file maps and creates environment variables to be used in wp-config.php
   • The 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.

3. Add and commit your changes.

   Terminal

   git add .
   git commit -m "Adds initial WordPress and Upsun configuration files"

2. Configure your root location

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:

applications:
  myapp:
    source:
      root: "/"
    type: 'php:8.3'
    web:
      locations:
        "/":
          passthru: "/index.php"
          root: "wordpress"
          index:
            - "index.php"
          expires: 600
          scripts: true
          allow: true
          rules:
            ^/license\.text$:
              allow: false
            ^/readme\.html$:
              allow: false

3. Set up a location for uploads

WordPress needs a writable location to store uploaded media. To set one up, follow these steps:

1. Create the location.
   To do so, add a /wp-content/uploads location as follows:

   .upsun/config.yaml

   applications:
     myapp:
       source:
         root: "/"
       type: 'php:8.3'
       web:
         locations:
           "/":
             passthru: "/index.php"
             root: "wordpress"
             index:
               - "index.php"
             expires: 600
             scripts: true
             allow: true
             rules:
               ^/license\.text$:
                 allow: false
               ^/readme\.html$:
                 allow: false
           "/wp-content/uploads":
             root: "wordpress/wp-content/uploads"
             scripts: false
             allow: false
             rules:
               '(?<!\-lock)\.(?i:jpe?g|gif|png|svg|bmp|ico|css|js(?:on)?|eot|ttf|woff|woff2|pdf|docx?|xlsx?|pp[st]x?|psd|odt|key|mp[2-5g]|m4[av]|og[gv]|wav|mov|wm[av]|avi|3g[p2])$':
                 allow: true
                 expires: 1w

2. To make the location writable, set up a mount.
   To do so, locate the mounts: section that is commented it out, and update it as follows:

   .upsun/config.yaml

   applications:
     myapp:
       source:
         root: "/"
       type: 'php:8.3'
       <snip>
       mounts:
         "wordpress/wp-content/uploads":
           source: storage
           source_path: "uploads"

   Note

   If you have designated a different directory through the wordpress-install-dir property in your composer.json file, update the mount location accordingly.

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

applications:
  myapp:
    source:
      root: "/"
    type: 'php:8.3'
    <snip>
    dependencies:
      php:
        composer/composer: "^2"
        wp-cli/wp-cli-bundle: "^2.4"

5. Install dependencies during the build hook

To ensure your Composer dependencies are installed during the build stage, locate the build: section (below the hooks: section).
Update the build: section as follows:

applications:
  myapp:
    source:
      root: "/"
    type: 'php:8.3'
    ...
    hooks:
      build: |
        set -eux
        composer install --prefer-dist --optimize-autoloader --apcu-autoloader --no-progress --no-ansi --no-interaction
        rsync -a plugins/ wordpress/wp-content/plugins/        

You can adjust the composer install command to meet your specific requirements.

If you aren’t using the plugins directory to manage non-public plugins, remove the rsync command.

5. Launch tasks during the deploy hook

Some tasks need to be performed after the images for our application are built, but before the newly built application can receive requests. Therefore, the best time to launch them is during the deploy hook.

Such tasks include:

• Flushing the object cache, which might have changed between current production and newly deployed changes
• Running the WordPress database update procedure, in case core is being updated with the newly deployed changes
• Running any due cron jobs

To launch these tasks during the deploy hook, locate the deploy: section (below the build: section).
Update the deploy: and post_deploy sections as follows:

applications:
  myapp:
    source:
      root: "/"
    type: 'php:8.3'
    ...
    hooks:
      deploy: |
        set -eux
        # 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        

6. Configure your default route

Next, instruct the router how to handle requests to your WordPress app. To do so, locate the routes: section, and beneath it, the "https://{default}/": route.

Update the route as follows:

applications:
  myapp:
    source:
      root: "/"
    type: 'php:8.3'
    ...

routes:
  "https://{default}/":
    type: upstream
    upstream: "myapp:http"
    cache:
      enabled: true
      cookies:
        - '/^wordpress_*/'
        - '/^wp-*/'

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 the .environment file

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:

# 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 UPSTREAM_URLS=$(echo $SITE_ROUTES | jq -r --arg app "${PLATFORM_APPLICATION_NAME}" '[.[] | select(.type == "upstream" and .upstream == $app )] | keys')

9. Commit and push

You can now commit all the changes made to .upsun/config.yaml and .environment and push to Upsun.

git add .
git commit -m "Add changes to complete my upsun configuration"
upsun push

10. Install WordPress

Once Upsun 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 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 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:

 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.

Further resources

Documentation

• PHP documentation

• Extensions

• Performance tuning

• PHP-FPM sizing

• Authenticated Composer

Community content

• PHP topics
• WordPress topics

Blogs

• To Upsun, a WordPress migration story