Configure WordPress for Platform.sh
Back to home
On this page
You now have a project running on Platform.sh. In many ways, a project is just a collection of tools around a Git repository. Just like a Git repository, a project has branches, called environments. Each environment can then be activated. Active environments are built and deployed, giving you a fully isolated running site for each active environment.
Once an environment is activated, your app is deployed through a cluster of containers. You can configure these containers in three ways, each corresponding to a YAML file:
- Configure apps in a
.platform.app.yamlfile. This controls the configuration of the container where your app lives. - Add services in a
.platform/services.yamlfile. This controls what additional services are created to support your app, such as databases or search servers. Each environment has its own independent copy of each service. If you’re not using any services, you don’t need this file. - Define routes in a
.platform/routes.yamlfile. This controls how incoming requests are routed to your app or apps. It also controls the built-in HTTP cache. If you’re only using the single default route, you don’t need this file.
Start by creating empty versions of each of these files in your repository:
# Create empty Platform.sh configuration files
mkdir -p .platform && touch .platform/services.yaml && touch .platform/routes.yaml && touch .platform.app.yamlNow that you’ve added these files to your project, configure each one for WordPress in the following sections. Each section covers basic configuration options and presents a complete example with comments on why WordPress requires those values.
Configure apps in .platform.app.yaml 
Your app configuration in a .platform.app.yaml file is allows you to configure nearly any aspect of your app.
For all of the options, see a complete reference.
The following example shows a complete configuration with comments to explain the various settings.
Notice that the build flavor is set to composer, which will automatically download WordPress core, as well as your plugins, themes, and dependencies during the build step as defined in your composer.json file. Since WordPress’s caching and uploads require write access at runtime, they’ve been given corresponding mounts defined for them at the bottom of the file. MariaDB is accessible to WordPress internally at database.internal thanks to the relationship definition database. The WordPress CLI is added as a build dependency, but we will still need to add some additional dependencies in the next step so that it can be used by the application and via SSH.
# Complete list of all available properties: https://docs.platform.sh/create-apps/app-reference.html
# A unique name for the app. Must be lowercase alphanumeric characters. Changing the name destroys data associated
# with the app.
name: app
# The runtime the application uses.
# Complete list of available runtimes: https://docs.platform.sh/create-apps/app-reference.html#types
type: 'php:8.1'
# Specifies a default set of build tasks to run. Flavors are language-specific.
# More information: https://docs.platform.sh/create-apps/app-reference.html#build
build:
flavor: composer
# Installs global dependencies as part of the build process. They’re independent of your app’s dependencies and
# are available in the PATH during the build process and in the runtime environment. They’re installed before
# the build hook runs using a package manager for the language.
# More information: https://docs.platform.sh/create-apps/app-reference.html#dependencies
dependencies:
php:
composer/composer: '^2'
wp-cli/wp-cli-bundle: "^2.4.0"
# Hooks allow you to customize your code/environment as the project moves through the build and deploy stages
# More info:
hooks:
# The build hook is run after any build flavor.
# More information: https://docs.platform.sh/create-apps/hooks/hooks-comparison.html#build-hook
build: |
set -e
# Copy manually-provided plugins into the plugins directory.
# This allows manually-provided and composer-provided plugins to coexist.
rsync -a plugins/* wordpress/wp-content/plugins/
# The deploy hook is run after the app container has been started, but before it has started accepting requests.
# More information: https://docs.platform.sh/create-apps/hooks/hooks-comparison.html#deploy-hook
deploy: |
# Flushes the object cache which might have changed between current production and newly deployed changes
wp cache flush
# Runs the WordPress database update procedure in case core is being updated with the newly deployed changes
wp core update-db
# Runs all cron events that are due now and may have come due during the build+deploy procedure
wp cron event run --due-now
# The relationships of the application with services or other applications.
# The left-hand side is the name of the relationship as it will be exposed
# to the application in the PLATFORM_RELATIONSHIPS variable. The right-hand
# side is in the form `<service name>:<endpoint name>`.
# More information: https://docs.platform.sh/create-apps/app-reference.html#relationships
relationships:
database: "db:mysql"
# The web key configures the web server running in front of your app.
# More information: https://docs.platform.sh/create-apps/app-reference.html#web
web:
# Each key in locations is a path on your site with a leading /.
# More information: https://docs.platform.sh/create-apps/app-reference.html#locations
locations:
"/":
# The public directory of the app, relative to its root.
root: "wordpress"
# The front-controller script to send non-static requests to.
passthru: "/index.php"
# Wordpress has multiple roots (wp-admin) so the following is required
index:
- "index.php"
# The number of seconds whitelisted (static) content should be cached.
expires: 600
scripts: true
allow: true
# The key of each item in rules is a regular expression to match paths exactly. If an incoming request
# matches the rule, it’s handled by the properties under the rule, overriding any conflicting rules from the
# rest of the locations properties.
# More information: https://docs.platform.sh/create-apps/app-reference.html#rules
rules:
^/composer\.json:
allow: false
^/license\.txt$:
allow: false
^/readme\.html$:
allow: false
"/wp-content/cache":
root: "wordpress/wp-content/cache"
scripts: false
allow: false
"/wp-content/uploads":
root: "wordpress/wp-content/uploads"
scripts: false
allow: false
rules:
# Allow access to common static files.
'(?<!\-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
# The size of the persistent disk of the application (in MB). Minimum value is 128.
disk: 2048
# Mounts define directories that are writable after the build is complete. If set as a local source, disk property is required.
# More information: https://docs.platform.sh/create-apps/app-reference.html#mounts
mounts:
"wordpress/wp-content/cache":
source: local
source_path: "cache"
"wordpress/wp-content/uploads":
source: local
source_path: "uploads"
# More information: https://docs.platform.sh/create-apps/app-reference.html#extensions
runtime:
extensions:
- blackfire
########################################################################################################################
## ##
## This source operation is part of the Platform.sh process of updating and maintaining our collection of templates. ##
## For more information see https://docs.platform.sh/create-apps/source-operations.html and ##
## https://github.com/platformsh/source-operations ##
## ##
## YOU CAN SAFELY DELETE THIS COMMENT AND THE LINES BENEATH IT ##
## ##
########################################################################################################################
source:
operations:
auto-update:
command: |
curl -fsS https://raw.githubusercontent.com/platformsh/source-operations/main/setup.sh | { bash /dev/fd/3 sop-autoupdate; } 3<&0 Note
During the template’s build hook above, you see an rsync command that allows you to commit and use plugins that aren’t accessible via Composer. The command moves all non-Composer plugins in a committed plugins directory to the final wp-content/plugins destination so that they can be enabled through the administration panel.
If you are migrating WordPress or starting from scratch, you should copy this line for your committed non-Composer plugins and, if needed, modify it to move committed themes to wp-content/themes in the same way.
Add services in .platform/services.yaml
You can add the managed services you need for you app to run in the .platform/services.yaml file.
You pick the major version of the service and security and minor updates are applied automatically,
so you always get the newest version when you deploy.
You should always try any upgrades on a development branch before pushing to production.
We recommend the latest MariaDB version for WordPress.
You can add other services if desired, such as Solr or Elasticsearch. You need to configure to use those services once they’re enabled.
Each service entry has a name (db in the example)
and a type that specifies the service and version to use.
Services that store persistent data have a disk key, to specify the amount of storage.
# The services of the project.
#
# Each service listed will be deployed
# to power your Platform.sh project.
# More information: https://docs.platform.sh/add-services.html
# Full list of available services: https://docs.platform.sh/add-services.html#available-services
db:
type: mariadb:10.4
disk: 2048
Define routes
All HTTP requests sent to your app are controlled through the routing and caching you define in a .platform/routes.yaml file.
The two most important options are the main route and its caching rules.
A route can have a placeholder of {default},
which is replaced by your domain name in production and environment-specific names for your preview environments.
The main route has an upstream, which is the name of the app container to forward requests to.
You can enable HTTP cache.
The router includes a basic HTTP cache.
By default, HTTP caches includes all cookies in the cache key.
So any cookies that you have bust the cache.
The cookies key allows you to select which cookies should matter for the cache.
Generally, you want the user session cookie, which is included in the example for WordPress.
You may need to add other cookies depending on what additional modules you have installed.
You can also set up routes as HTTP redirects.
In the following example, all requests to www.{default} are redirected to the equivalent URL without www.
HTTP requests are automatically redirected to HTTPS.
If you don’t include a .platform/routes.yaml file, a single default route is used.
This is equivalent to the following:
https://{default}/:
type: upstream
upstream: <APP_NAME>:httpWhere <APP_NAME> is the name you’ve defined in your app configuration.
The following example presents a complete definition of a main route for a WordPress app:
# The routes of the project.
#
# Each route describes how an incoming URL is going
# to be processed by Platform.sh.
# More information: https://docs.platform.sh/define-routes.html
"https://{default}/":
type: upstream
upstream: "app:http"
# Platform.sh supports HTTP caching at the server level. Caching is enabled by default, but is only applied to
# GET and HEAD requests.
# More information: https://docs.platform.sh/define-routes/cache.html
cache:
# All possible cache configuration options: https://docs.platform.sh/define-routes/cache.html#cache-configuration-properties
enabled: true
# Base the cache on the session cookies. Ignore all other cookies.
cookies:
- '/^wordpress_logged_in_/'
- '/^wordpress_sec_/'
- 'wordpress_test_cookie'
- '/^wp-settings-/'
- '/^wp-postpass/'
- '/^wp-resetpass-/'
# A basic redirect definition
# More information: https://docs.platform.sh/define-routes.html#basic-redirect-definition
"https://www.{default}/":
type: redirect
to: "https://{default}/"