# Deploy Vanilla WordPress on Upsun Fixed

**Note**: 

Before you start, check out the [Upsun demo app](https://console.upsun.com/projects/create-project)
and the main [Getting started guide](https://docs.upsun.com/get-started/here.md).
They provide all the core concepts and common commands you need to know before using the following materials.

For WordPress to successfully deploy and operate, **after completing the [Getting started guide](https://docs.upsun.com/get-started/here.md)**,
you still need to add some required files and make a few changes to your Upsun configuration.

## Before you begin

You need:

- [Git](https://git-scm.com/downloads).
  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](https://auth.upsun.com/register).
  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](https://docs.upsun.com/administration/cli.md).
  This lets you interact with your project from the command line.
  You can also do most things through the [Web Console](https://docs.upsun.com/administration/web.md).

**Assumptions**: 

There are many ways you can set up a WordPress site or Upsun 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
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.

## 1. Add required files

To ensure you have all the required files and directories in your project, follow these steps:

1. If you haven't already, you will need to retrieve the [WordPress](https://wordpress.org/) core files. You can either
download a zip archive from WordPress.org, or use `curl` to download a tarball:

   ```shell
   curl https://wordpress.org/latest -o wordpress.tar.gz
   ```

2. Extract the contents of the archive. If you used curl in step 1. you can extract the contents using `tar`:

   ```shell
   tar -xvf wordpress.tar.gz
   ```

3. After extracting the files from the archive, delete the archive as it no longer needed (e.g. `rm wordpress.tar.gz`)

4. Whether you downloaded the zip, or the tarball, after extraction the extracted files should be contained in a
   directory named `wordpress`. This directory will become your public directory later. If you decide to rename this
   directory, make note of it for later steps.

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

7. Add all the files from the steps above to your repository
   ```bash
    git add .
    git commit -m "adds wordpress core files"
   ```

## 2. Update configuration files

1. Open the `.upsun/config.yaml` file created during the [Getting started guide](https://docs.upsun.com/get-started/here.md)

2. Locate the `web:locations` section and update the root (`/`) location as follows:

    ```yaml  {location=".upsun/config.yaml"}
    applications:
      myapp:
        source:
          root: "/"
        type: 'php:8.5'
        web:
          locations:
            "/":
              passthru: "/index.php"
              root: "wordpress"
              index:
                - "index.php"
              expires: 600
              scripts: true
              allow: true
              rules:
                ^/license\.txt$:
                  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
    ```

    **Note**: 

If you changed the name of the directory at step 1.4 you’ll need to update the ``root`` property to match for both locations.

3. Application containers are read-only by default; WordPress needs a writable location to store uploaded media.
   To make the location writable, set up [a mount](https://docs.upsun.com/create-apps/image-properties/mounts.md). To do so,
   locate the `mounts:` section that is commented out, and update it as follows:

   ```yaml  {location=".upsun/config.yaml"}
   applications:
    myapp:
      source:
        root: "/"
      type: 'php:8.5'

      mounts:
        "wordpress/wp-content/uploads":
          source: storage
          source_path: "uploads"
    ```

    **Note**: 

When uncommenting, pay attention to the indentation and that the ``mounts`` key aligns with other sibling keys (e.g. ``relationships``, ``web``, etc.)

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:

   - 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 perform these tasks, we'll utilize  the [`deploy`](https://docs.upsun.com/learn/overview/build-deploy.md#deploy-steps) and
    [`post_deploy`](https://docs.upsun.com/create-apps/hooks/hooks-comparison.md#post-deploy-hook) hooks. Locate the `deploy:` section
    (below the `build:` section). Update the `deploy:` and `post_deploy:` section as follows:

    ```yaml  {location=".upsun/config.yaml"}
    applications:
      myapp:
        source:
          root: "/"
        type: 'php:8.5'

        hooks:
          deploy: |
            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
    ```

5. Add your crons

Under your application configuration you can now add a cron.

```yaml  {location=".upsun/config.yaml"}
applications:
  myapp:
    source:
      root: "/"
    type: 'php:8.3'
    ...
    crons:
      wp-cron:
        spec: '*/10 * * * *'
        commands:
          start: wp cron event run --due-now
        shutdown_timeout: 600
```

6. Locate the `routes:` section, and beneath it, the `"https://{default}/":` route. Update the route as follows:

    ```yaml  {location=".upsun/config.yaml"}
    applications:
      myapp:
        source:
          root: "/"
        type: 'php:8.5'
        ...

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

7. 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  {location=".upsun/config.yaml"}
    applications:
      myapp:
        source:
          root: "/"
        type: 'php:8.5'

        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.)

8. Add and commit your changes.

   ```bash  {location="Terminal"}
   git add .upsun/config.yaml
   git commit -m "Updates Upsun configuration file"
   ```

## 3. Update `.environment`

The CLI generated a `.environment` file during the Getting started guide. Notice it has already created some environment
variables for you to connect to your database service.

```bash  {location=".environment"}
# Set database environment variables
export DB_HOST="$MARIADB_HOST"
export DB_PORT="$MARIADB_PORT"
export DB_PATH="$MARIADB_PATH"
export DB_DATABASE="$DB_PATH"
export DB_USERNAME="$MARIADB_USERNAME"
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, 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  {location="Terminal"}
upsun 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](https://docs.upsun.com/create-apps/image-properties/crons.md) 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  {location=".upsun/config.yaml"}
 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**: 

When uncommenting, pay attention to the indentation and that the ``crons`` key aligns with other sibling keys (e.g. ``hooks``, ``dependencies``, etc.)

## Further resources
- [All files (Upsun configuration, `.environment`, `wp-cli.yml`, `wp-config.php`)](https://github.com/upsun/snippets/tree/main/examples/wordpress-vanilla)
### Documentation

- [PHP documentation](https://docs.upsun.com/languages/php.md)

- [Extensions](https://docs.upsun.com/languages/php/extensions.md)

- [Performance tuning](https://docs.upsun.com/languages/php/tuning.md)

- [PHP-FPM sizing](https://docs.upsun.com/languages/php/fpm.md)

### Community content

- [PHP topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93&query=php)
- [WordPress topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93&query=wordpress)

### Blogs

- [To Upsun, a WordPress migration story](https://upsun.com/blog/to-upsun-a-wordpress-migration-story/)