Running Drupal CMS on Upsun

While the release of Drupal CMS may be new, it is still built on the normal Drupal core, and as such it is easy to install and is built to run on Upsun or Platform.sh in the usual way!

This short tutorial will take you through the steps of getting it running on Upsun.

1. Get Drupal code
2. Add the Upsun config files
3. Push to an Upsun project

Before we start:

• Sign up for an Upsun trial account if you haven't already

(Optional) Install the Upsun CLI . This is recommended, but we won't require it for this tutorial.

Prerequisites:

• A working terminal shell, with git and composer installed. Any current version of PHP should do.

The Drupal CMS starter and install instructions comes with DDEV support, which is great, but we won't actually need it for this demo. 

TL;DR:

You can run this command to get an instant version of Drupal CMS deployed for you under your own Upsun account!

curl -fsSL https://raw.githubusercontent.com/upsun/drupal-scaffold/refs/heads/main/QUICK_DRUPAL_CMS.sh | bash

😂 No, don't really do that! It will work, but you won't learn anything that way. You can review the QUICK_DRUPAL_CMS script directly though, as it contains all the steps described in this tutorial. It's only 12 lines long, and half of that is git basics.

To follow the steps more carefully, please read on…

Get a copy of Drupal CMS

You can either download the zip or use composer create-project to get started, as in the Drupal docs.

composer create-project --ignore-platform-reqs --no-install "drupal/cms:^1"
cd cms

Note the --no-install option here. We don't actually want to check out all the libraries yet, and we need to .gitignore many things first.

Initialize the project and git repository

Everything that gets deployed to Upsun happens through git releases. (Docs on upsun and git). We will start a git project locally, then link it to a repository hosted on Upsun for releases.

• Initialize git locally. 

  git init
  git add .
  git commit -m "Initial checkout of drupal/cms:1"

Create Upsun project

• Create a new empty Upsun project from the Upsun console ("Kickstart a new repository" or “Start from scratch”)
  • When prompted for a region, consider choosing a “green” region for your hosting.

This will take a minute while the resources are set up for you. Once that is created, you will be given an URL for your git repository.

Upsun is designed to work with your existing workflows using Github, Bitbucket, Gitlab etc, but for now we will just deploy directly from your local environment to the Upsun target.

The Upsun console project wizard will tell you that the repository can be targeted by running upsun project:set-remote yoUrPr0jCTId . That works when you have the CLI installed. But if you access your new project, you can also easily find the git URL under the ‘Code’ button and use that.

Attach your code repository to the Upsun project

git remote add upsun yoUrPr0jCTId@git.eu-5.platform.sh:yoUrPr0jCTId.git

Your local codebase and the Upsun hosting environment are now connected, and a git push will be used to deploy. But first

Add Upsun configuration to the Drupal CMS project.

Adding Upsun support basically means just adding a YAML config file to your codebase, as documented in “Configure your codebase”. 

But with each CMS or web application, there is going to be a little bit more to it than that. We also need to define the services like a database, and how the App will communicate with it. The Upsun team at Platform.sh already know how to make Drupal work well, so I have provided a composer scaffold plugin that will do this automatically for us for any version of Drupal, including Drupal-CMS, (which is currently  Drupal-11).

Adding this plugin is done with the following commands (explained more in the README).

composer config repositories.upsun-drupal-scaffold vcs https://github.com/upsun/drupal-scaffold
composer config --json --merge extra.drupal-scaffold.allowed-packages '["upsun/drupal-scaffold"]'
composer require --ignore-platform-reqs upsun/drupal-scaffold

You will see the changes that upsun/drupal-scaffold made to the project listed in the install log. These are explained further in the drupal-scaffold project README.

Scaffolding files for upsun/drupal-scaffold:
  - Copy [project-root]/.gitignore from assets/common/.gitignore
  - Copy [project-root]/.environment from assets/common/.environment
  - Copy [project-root]/config/sync/.htaccess from assets/common/config/sync/.htaccess
  - Copy [project-root]/.upsun/config.yaml from assets/common/.upsun/config.yaml
  - Copy [project-root]/drush/platformsh_deploy_drupal.sh from assets/common/drush/platformsh_deploy_drupal.sh
  - Copy [project-root]/drush/platformsh_generate_drush_yml.php from assets/common/drush/platformsh_generate_drush_yml.php
  - NOTICE Creating a new file at [web-root]/sites/default/settings.php. Examine the contents and ensure that it came out correctly.
  - Append to [web-root]/sites/default/settings.php from assets/common/web/sites/default/settings.php.append
  - Copy [web-root]/sites/default/settings.platformsh.php from assets/common/web/sites/default/settings.platformsh.php
No security vulnerability advisories found.
Using version ^11.0 for upsun/drupal-scaffold

Add the new scaffolded files to your project

git add .
git commit -m "Added Upsun support and built Drupal"

Deploy to Upsun

You can use the upsun CLI to do deployments, but if you are more comfortable with git. then a code release will be just a git push.

git push --set-upstream upsun main

And watch all the build steps happen. It should take a minute.

...
Validating configuration files
Processing activity: dman pushed to Main
    Found 3 commits
    Configuring resources
      Using default resources as fallback
      ...
    Building application 'drupal' (runtime type: php:8.3, tree: 7d87999)
      Generating runtime configuration.
      Installing build dependencies...
...
...
    Creating environment main
      Starting environment
      Updating endpoints for drupal and router
      Opening application drupal and its relationships
      Executing deploy hook for application drupal
        Created Drush configuration file: /app/.drush/drush.yml
        Drupal not installed. Skipping standard Drupal deploy steps

      Opening environment
      Environment configuration
        drupal (type: php:8.3, cpu: 0.5, memory: 224, disk: 512)
        db (type: mariadb:10.11, cpu: 0.5, memory: 1408, disk: 512)
        cache (type: redis:7.2, cpu: 0.5, memory: 1088)

      Environment routes
        http://main-bvxea6i-yoUrPr0jCTId.eu-5.platformsh.site/ redirects to https://main-bvxea6i-yoUrPr0jCTId.eu-5.platformsh.site/
        http://www.main-bvxea6i-yoUrPr0jCTId.eu-5.platformsh.site/ redirects to https://www.main-bvxea6i-yoUrPr0jCTId.eu-5.platformsh.site/
        https://main-bvxea6i-yoUrPr0jCTId.eu-5.platformsh.site/ is served by application `drupal`
        https://www.main-bvxea6i-yoUrPr0jCTId.eu-5.platformsh.site/ redirects to https://main-bvxea6i-yoUrPr0jCTId.eu-5.platformsh.site/

If you have a new project, then the `main` environment will be automatically activated for you, and be ready to preview!

Visit the URL for the Drupal CMS install wizard

And that's it! You are ready to go with Drupal CMS at the hosted address.

Review

The interesting thing to note is that with this approach:

All necessary changes to sites/default and sites/default/settings.php have been made

This was done by the drupal-scaffold setup, which added the required database connection details (and a few other tweaks) to the Drupal project. Everything is Upsun-enabled already.

Next steps

Extending Drupal

Drupal CMS does almost everything out-of-the-box, but Drupal is designed to be extended with additional modules and themes. To use them, you will have to make additions to your project locally, commit them to the project repository, and deploy those changes. 

The Drupal module browser will not work on the secure, read-only file system. This is by design on Upsun. Only code that was signed off through git commits is permitted to run on a production environment.

Unable to download modules via the UI: The file system is not writable.

Content sync

If you run through the install wizard, that will build your site remotely. If you want to do local development, then you will have to get used to synchronizing the remote content with your local development environment sometimes. This is made a lot easier by using DDEV, as supported by Drupal CMS already, and the Upsun/DDEV integration that does this for you! Once configured, you can ddev pull upsun and get a fresh copy of your production data transferred to your local development environment!

Glitch

You may encounter a PHP error at the end of the Drupal CMS install wizard! This appears to be caused by a race condition or timeout during the installation batch process (unconfirmed). If this happens, your Drupal site may need a cache flush. 

Drupal cache can be quickly flushed with the command:

upsun drush cache-rebuild

But, it's even easier if you visit the /update.php path in the root of your site! Initiating an update.php (Press [Continue] once) will implicitly do a cache clear for you. After that, the site should come right for you.