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.
Note:
With some caveats, it is of course possible to deploy WordPress to Platform.sh without using Composer, though not recommended. You can consult the “WordPress without Composer on Platform.sh” guide to set that up, but do consider upgrading to use Composer.
Going through the steps below you will have two options:
- 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.
- 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.
Note:
All of the examples in this deployment guide use the wordpress-composer
template maintained by the Platform.sh team. That template is built using the John Bloch Composer fork of WordPress, which is meant to make managing WordPress with Composer a simple process, but the template comes with its own assumptions. The most obvious being that WordPress core is downloaded by default into a wordpress
subdirectory when installed, but other teams would rather specify another subdirectory along with many more asssumptions.
An alternative approach is shown in Platform.sh’s Bedrock template, which installs core into web/wp
, exports environment customization to a separate config/environments
directory, and largely depends on setting environment variables to configure the database. Your are free to follow that template as an example with this guide, though there will be slight differences. For its ease of use, the Bedrock approach will often be used as a substitute starting point in some of the other WordPress guides in this documentation.
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.
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.
Note:
If you are integrating a repository to Platform.sh that contains a number of open pull requests, the default integration options should not be used. This is because projects are limited to *three development environments (active and deployed branches or pull requests), and you would need to deactivate them individually to test this guide's migration changes. Instead, each service integration should be made with the following flag:
$ platform integration:add --type=<service> ... --build-pull-requests=false
You will then be able to go through this guide and activate the environment when you're ready to deploy.
*Note that it is also possible to purchase additional development environments for your project at any time through the management console. View your list of projects and select "Edit plan" from the dropdown of your WordPress project. From there you can add additional environments on the "Environments" line and get a price estimate for the changes to your plan.
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.