How to deploy a WordPress site on Platform.sh in 5 minutes

Estimated time: 5 minutes

1. Install Platform.sh DevOps tools

   The first tool to set up is Git. As a platform as a service, or PaaS, Platform.sh automatically manages everything your application needs to run; relying on the Git tool to manage the files. Every commit you make results in a new deployment, and your entire configuration is managed almost entirely by a small number of YAML files in your Git (which we’ll cover in the steps below). Your infrastructure, described in these files, becomes part of your application itself – completely transparent and version-controlled. If you don’t have Git on your computer yet, you should install it now.

   Next, you’ll need Secure Shell (SSH) to securely connect to your Git repository and environments. SSH clients are readily available for all platforms and may already be installed on your computer.

   Platform.sh supports both key pair and certificate authentication. Both are secure and protect your account from snooping when you log in. For now, you can use certificate authentication because it is simpler. You will be prompted to log in via your web browser the first time you run Platform SSH. If you want to use key-pair authentication, check the Platform.SH SSH page before proceeding.

   Finally, in this guide, you will interact with your project on Platform.sh both from your browser and from the command line using Platform.sh’s CLI. Both use our API so you can make changes to your projects, but the CLI will be the tool you use most in this guide.

   Below are a set of installation commands for different operating systems:

   # Linux/OSx $ curl -sS https://platform.sh/cli/installer | php
# Linux/OSx $ curl -sS https://platform.sh/cli/installer | php
# Windows $ curl https://platform.sh/cli/installer -o cli-installer.php $ php cli-installer.php
# Verify the installation $ platform
# View the list of CLI commands $ platform list

2. Configure the Platform.sh environment for WordPress

   You can deploy a WordPress template directly to Platform.sh. You can sign up for the service using an existing GitHub, Bitbucket or Google account.

   In many ways, a project is simply a collection of tools around a Git repository. It mimics exactly the branch structure of a repository, but with one important addition: any branch can be activated to become an environment on Platform.sh.

   Activated environments go through the build and deployment phases of Platform.sh, which provides a completely isolated execution site for each activated branch (or pull request) on that repository.
   Once an environment is activated, Platform.sh provisions a cluster of containers to deploy your application, and the configuration of this cluster is controlled by three YAML files:

   .platform/routes.yaml controls how incoming requests are routed to your application, or your applications if you are using a multi-application setup. It also controls the built-in HTTP cache.

   .platform/services.yaml controls additional services that are created to support your application, such as databases or search servers. Each environment has its own independent copy of each service.

   .platform.app.yaml controls the configuration of the container where your application lives. This is the most powerful one, with the most options, so it can be a bit long depending on your configuration.

   Every project on Platform.sh needs at least these three files and each can be customized to your needs. However, most WordPress sites will have a fairly similar configuration, at least at first.

   You can start by creating empty versions of each of these files in your repository:

   Create empty Platform.sh configuration files

   touch .platform.app.yaml && mkdir -p .platform && touch .platform/routes.yaml && touch .platform/services.yaml

   Now that you have added these files to your project, you can review and configure each of them for WordPress on the official Platform.sh website. Each section covers a particular configuration file, defines what each attribute configures, and then shows a final code snippet that includes the recommended configuration for WordPress from its template. Within this snippet, be sure to read each of the comments, as they provide additional information and explain why WordPress requires these values.

3. Customize Your WordPress Site via Platform.sh

   Now that your code contains all the configuration needed to deploy to Platform.sh, it’s time to prepare your WordPress site to run in a Platform.sh environment.

   Install the Configuration Player
   
   Platform.sh provides all the information about the runtime environment, including how to connect to services, through environment variables. These are accessible directly, but it is often easier to use the Config Reader library that Platform.sh provides.

   The Config Reader is simply a set of utilities to wrap the environment variables and make them a bit more user-friendly. The code below uses it, so you’ll need to install it via Composer if you haven’t already.

   composer require platformsh/config-reader

   Once the Configuration Reader library is installed, add or update a wp-config.php file at the root of your repository to match the code below.

   In this file, the library’s Config object is used to:
   
   – Retrieve the login credentials for MariaDB via the database relationship to configure the WordPress database. This will configure the database automatically and save you from having to configure the connection yourself during installation.
   – Use the project routes to set the WP_HOME and WP_SITEURL parameters. Set all WordPress security and authentication keys in the PLATFORM_PROJECT_ENTROPY variable provided by Platform.sh – a hash variable specific to your repository and consistent across environments.
   Many other WordPress settings are predefined in this file for you, see the online comments for more information.

   Configuring Composer
   
   In this guide, you’ll configure your WordPress repository to install everything it needs to during its build using Composer. This includes themes, plugins, and even the WordPress core itself. Any new plugins you want to use or migrate from your existing application can be sent as dependencies using Composer, but we need to make some changes to the composer.json file to prepare it for the final Platform.sh environment.
   You can find the details of these configurations on the official Platform.sh website here.

4. Deploy your WordPress site

   If you’ve been customizing your existing project along the way, now is the time to make sure all the code is validated on Git and push it to Platform.sh on the master branch.

   Platform.sh will then build your code, producing a read-only file system image of your application, and then deploy it to a running container cluster.

   You can view the process from the management console; when it is complete, click on the URL displayed in the console to view your site.

   Configuring WordPress to write to Platform.sh
   
   By default, applications deployed on Platform.sh are read-only for security and stability. However, when using a WordPress, we tend to want to install different plugins and these plugins must have permission to write to certain files in order to function normally.

   Let’s see together how to set up writing to the wp-content folder.
   
   Open the .platform.app.yaml file and insert these lines below the “dependencies” section:

   mounts:
   “wordpress/wp-content”:
   source: local
   source_path: “wp-content

   We have just added a “mount” section to our Platform.sh application. This mount is defined as a folder that is writable (of course, we have to push these modifications on the git and redeploy the application).

   To summarize, thanks to these few lines of configuration, we have just made the wp-content folder and its content editable. This will allow us to install plugins that need to create folders/modify files as we go along.

   Finally, one of the other files that often needs to be modified is: wp-config.php. This file is not in the wp-content folder, but in the root of the project.

   You are going to say to me, why not put directly the root folder in mount, which would allow to have everything in writing?
   
   The problem with this solution is that you will have to potentially modify things that should not be modified. Moreover, in order to ensure healthy and easy to deploy environments, code modifications should only be done via git, which allows to follow the evolution of the application. The mount should only be used for uploads, logs or temporary files.

   To quote their documentation: “In Platform.sh, you can’t ‘hack the production’. It’s a constraint, but a good one.

   But Platform.sh offers an alternative, in the local folder of your application is a file wp-config.php (the one we talk about earlier in the article when installing the Configuration Reader).

   This is the file that is used for each deployment. You just have to add the line you want and it will be taken into account during the deployment. For example :

   define( 'WP_CACHE', true );

   This line is used by many cache management plugins. In order to make them work, you will have to add this line by hand, then push the modifications to the git.