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 need a couple tools to interact with your Platform.sh project, one of which you likely already have.

  • Git. Git is the primary tool you use to manage everything your app needs to run. 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.

  • The Platform.sh CLI. This lets you interact with your Platform.sh project from the command line. You can also use your browser, but the CLI is the tool you use the most in this guide. Install it for your operating system:

    # Linux/macOS
    curl -sS https://platform.sh/cli/installer | php
    
    # Windows
    curl https://platform.sh/cli/installer -o cli-installer.php
    php cli-installer.php
    

    Once it’s installed, run the CLI in your terminal:

    # Verify the installation
    platform
    

    On the first run, you need to log in using a browser.

    Take a moment to view some of the available commands, by running:

    # 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 first need to register for a trial Platform.sh 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 can 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.