Gatsby multi-app projects

Background 

A common pattern for Gatsby sites is to decouple services from the main site, pulling in external data at build time. Supported by Gatsby’s source plugin ecosystem, data from conventional (or headless) content management systems can be collected into a common Data Layer, with that CMS typically located on a server elsewhere, and that data then used to fill out content on the frontend.

The location of an external CMS is usually hardcoded into Gatsby’s configuration, so when you’re developing your site every branch points to the same backend resource. Should the location of that resource change, you would need to commit the new URL to update the configuration.

The decoupled pattern can work differently on Platform.sh due to support for multi-app configuration on your projects. Consider the following project structure:

.
├── .platform
│   ├── routes.yaml
│   └── services.yaml
├── drupal
│   ├── <application code>
│   └── .platform.app.yaml
├── gatsby
│   ├── <application code>
│   └── .platform.app.yaml
└── README.md

Above is the repository structure for a Decoupled Drupal (Gatsby sourcing Drupal content) project on Platform.sh. Here, Gatsby and Drupal reside in their own subdirectories within the same repository. They are deployed to the same project from separate application containers, and from this cluster Gatsby can read data from Drupal internally. Their commit histories are tied together, such that each new pull request environment can test changes to either the frontend or backend freely from the same place.

Drupal is just one example of a backend CMS that can be used with this pattern, and at the bottom of this page are a few additional guides for alternatives that work well on Platform.sh.

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

Signing up for Platform.sh 

In each of the backend guides below, there will be a “Deploy on Platform.sh” button that will not only deploy the guide’s project for you, but also sign you up for a trial account. If you are planning on simply deploying a template and following along with these guides for greater context, feel free to move onto the next section.

If however you are planning on using the templates and guides to deploy your existing codebase to Platform.sh, 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. This is especially important with multi-application projects, so make sure to consult the Plan size note below for more details.

Plan size 

There are a few important points you will need to keep in mind when deploying this pattern if you have already deployed Gatsby by itself on Platform.sh, which are relevant to each backend example. After following the steps below, you may find that Gatsby fails to bundle assets during its build on projects of the “Development” plan size. This is a factor of both the size and number of Gatsby’s dependencies on the frontend, as well as the amount of data being pulled from the backend.

Multi-application projects generally require more resources to run on Platform.sh, and so the trial’s default development plan may not be enough to run your existing site. You are free to either proceed with a smaller plan to test or increase the resources at this point for the project. Otherwise, it may be best to initially deploy the templates listed in each backend guide to start out, and later modify that project to include your own code with more resources as you get used to developing on Platform.sh.

Headless backends 

Platform.sh maintains a number of multi-application templates for Gatsby, that generally have very similar configuration changes on the Gatsby side. Below are a few of those written as short guides for different backend content management systems.