Upsun User Documentation

Deploy WordPress on Upsun

Try Upsun for 15 days
After that, enjoy the same, game-changing Upsun features for less with the First Project Incentive!ยน A monthly $19 perk!
ยนTerms and conditions apply
Activate your 15-day trial

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 Anchor to this heading

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 Anchor to this heading

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 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 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 "Add files and directory"
    git push

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 Anchor to this heading

Locate the web:locations section and update the root (/) 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

3. Set up a location for uploads Anchor to this heading

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'
           ...
           mounts:
               "wordpress/wp-content/uploads":
                   source: storage
                   source_path: "uploads"

4. Install dependencies during the build hook Anchor to this heading

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:

./.upsun/config.yaml
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 Anchor to this heading

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: section as follows:

./.upsun/config.yaml
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
                # Runs all due cron events
                wp cron event run --due-now                

6. Configure your default route Anchor to this heading

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:

./.upsun/config.yaml
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 your MariaDB service relationship Anchor to this heading

You need to update the name used to represent the relationship 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:

./.upsun/config.yaml
applications:
    myapp:
        source:
            root: "/"
        type: 'php:8.3'
        ...
        relationships:
            database: "mariadb:mysql"

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

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

Further resources Anchor to this heading

Documentation Anchor to this heading

Community content Anchor to this heading

Blogs Anchor to this heading

Is this page helpful?