Skip to main content
Before you start, check out the Upsun demo app and the main Getting started guide. 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, you still need to add some required files and make a few changes to your Upsun configuration.

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 APP_NAME, 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 core files. You can either download a zip archive from WordPress.org, or use curl to download a tarball: 
    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: 
    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.
  6. To make using wp-cli easier, add a wp-cli.yml file and add the following contents to it: 
     path: /app/wordpress/
 color: true
    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 
     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
  2. Locate the web:locations section and update the root (/) location as follows:
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.
  1. 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. To do so, locate the mounts: section that is commented out, and update it as follows:
When uncommenting, pay attention to the indentation and that the mounts key aligns with other sibling keys (e.g. relationships, web, etc.)
  1. 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 and post_deploy hooks. Locate the deploy: section (below the build: section). Update the deploy: and post_deploy: section as follows:
  1. Add your crons
Under your application configuration you can now add a cron.
  1. Locate the routes: section, and beneath it, the "https://{default}/": route. Update the route as follows:
  1. 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:
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.)
  1. Add and commit your changes.
    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.
.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:
.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:
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:
Terminal
upsun push -y

​
5. 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: 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.
When uncommenting, pay attention to the indentation and that the crons key aligns with other sibling keys (e.g. hooks, dependencies, etc.)

​
Further resources

​
Documentation

​
Community content

​
Blogs

Last modified on March 11, 2026