--> -->

How to Deploy WordPress on Platform.sh


WordPress is a popular Content Management System written in PHP. The recommended way to deploy WordPress on Platform.sh is by using Composer, the PHP package management suite. The most popular and supported way to do so is with the John Bloch Composer fork script. This guide assumes from the beginning that you’re migrating a Composer-flavored WordPress repository.

Using Composer is not traditionally the norm for WordPress development, but it is strongly recommended when deploying on Platform.sh. Like any other application, your WordPress site is most secure when you can ensure repeatable builds and commitable updates to your dependencies. Your infrastructure is committed through a set of configuration files which specifiy which version of PHP and MariaDB you want to use, and Composer provides the best way to make sure that your versions of WordPress core and your plugins are tied to your commit history in the same way.

Also, Platform.sh’s build and deploy pipeline prevents write access to the file system post-build, and it’s here where plugins that cannot be downloaded via Composer fail, since many require write acccess to their own file system as part of their setup process. There will be instructions in this guide for how to install plugins without using Composer, but it is still assumed that they stick to best practices and do not write to the file system at runtime and when enabling them. You can get around this issue by defining a mount where a plugin requires write access, but you will have to remember that the contents at that mount location will be wiped when deployment begins, so you will need to copy and re-copy accordingly.

If you have a WordPress site that is not using Composer, there are a few guides that cover the topic in more detail than this guide will address that you can consult before proceeding.

Going through the steps below you will have two options:

  1. You already have a Composer flavored WordPress site your are trying to deploy. In this case, you will able to go through each step to make the recommended changes to your repository to prepare it for Platform.sh.
  2. You have no code at this point. In this case, Platform.sh maintains a ready-made WordPress template that you will be able to deploy very quickly. The steps below will then hopefully help to clarify why the modifications have been made to a base WordPress project that is using Composer.

Tools 

Next, you’re going to need a few tools to be able to interact with your Platform.sh project, two of which you likely already have.

The first is Git, which you will need to have installed before moving forward. As a Platform as a Service, or PaaS, Platform.sh automatically manages everything your application needs in order to run. Git is the primary tool used to do this. Every commit pushed results in a new deployment, and all of your configuration is driven almost entirely by a small number of YAML files in your Git repository (which we will get to in the steps below). Your infrastructure, described in these files, becomes part of your application itself - completely transparent and version-controlled. If you do not already have Git on your computer, you should install it now.

Second, you will need Secure Shell (SSH) to securely connect to your Git repository and environments. SSH clients are readily available for every platform, and may already be installed on your computer. Platform.sh supports both keypair-based and certificate-based authentication. Both are secure and protect your account from snooping when you log in. For now, you can use certificate-based authentication as that is easier. You will be prompted to login via your web browser the first time you run platform ssh. If you wish to use keypair authentication, see the SSH page before continuing.

Lastly, in this guide you will be interacting with your project on Platform.sh both from within your browser and from the command line using the Platform.sh CLI. Both utilize our API so that you can make changes to your projects, but the CLI will be the tool you use the 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
    
# Windows
$ curl https://platform.sh/cli/installer -o cli-installer.php
$ php cli-installer.php

Once the installation has completed, you can run the CLI in your terminal with the command

# Verify the installation
$ platform

Take a moment to view some of the available commands with the command

# View the list of CLI commands
$ platform list

Sign up for Platform.sh and initialize your project 

Depending on whether or not you have an existing project you want to migrate to Platform.sh there are three ways to get started.

With a template

First, you can deploy a WordPress template itself straight to Platform.sh. Use the button below to launch a WordPress template project, and you will create a Platform.sh account along the way. If you don't want to sign up initially with your e-mail address, you can sign up using an existing GitHub, Bitbucket, or Google account. If you choose one of these options, you will be able to set a password for your Platform.sh account later.

Once the template is deployed, you can then follow along with the rest of this guide so you can better understand the extra files and tweaks in the repository.

Deploy on Platform.sh

With a brand new code base

If you want to start with a vanilla code base, or you have a pre-existing project you want to push to Platform.sh, that works, too.

You will first need to visit the Platform.sh accounts page and fill out your information to set up your trial account. If you don't want to sign up initially with your e-mail address, you can sign up using an existing GitHub, Bitbucket, or Google account. If you choose one of these options, you will be able to set a password for your Platform.sh account later.

After creating an account, you will be prompted to create your first project. Since you'll be providing your own code, use the "Blank project" option. You will be able to give the project a title and choose a region closest to the visitors of your site. You also have the option to select more resources for your project, although the development plan should be enough for you to get started.

Then initialize or clone your Git repository with existing code, or create a new Composer-based project from scratch. The commands below will create a brand new WordPress project using Composer, which you can then modify according to the rest of this guide.

$ git clone https://github.com/johnpbloch/wordpress && cd wordpress

Then, add a Git remote for the Platform.sh project you just created. The easiest way to get the ID of the project is to run just plaform on its own, which lists all of your projects. As you have only one project, you can copy its ID. Then in your Git repository run

$ platform set-remote <PROJECT_ID>

That creates an upstream called platform for your Git repository. Don't push to it yet, but once the project is fully configured you will be able to push to that remote and have the project build automatically.

From a third party Git provider

Platform.sh also supports third party Git hosting services, such as GitHub, GitLab, or BitBucket. In that case, the Platform.sh Git repository becomes a read-only mirror of the third party repository, which you can continue to use as normal.

You will first need to visit the Platform.sh accounts page and fill out your information to set up your trial account. If you don't want to sign up initially with your e-mail address, you can sign up using an existing GitHub, Bitbucket, or Google account. If you choose one of these options, you will be able to set a password for your Platform.sh account later.

After creating an account, you will be prompted to create your first project. Since you'll be providing your own code, use the "Blank project" option. You will be able to give the project a title and choose a region closest to the visitors of your site. You also have the option to select more resources for your project, although the development plan should be enough for you to get started.

Then, add an integration on Platform.sh to connect the new project to your existing third party repository. The process varies a bit for each supported service, so check the specific pages for each one.

They have a number of options, all of which you can ignore for now - the defaults will suffice at this point. Once you add the integration, any existing branches you have will automatically be synchronized to Platform.sh. The deploy on Platform.sh will report a failure at this point; that's OK, you haven't provided configuration files yet. That will be covered in the next step. Remember to have a local clone of your project as well.

Now that you have a local Git repository, a Platform.sh project, and a way to push code to that project, you're all set to continue.