This template builds Drupal 8 in a multisite configuration using the "Drupal Recommended" Composer project. It is pre-configured to use MariaDB and Redis for caching. The Drupal installer will skip asking for database credentials as they are already provided.
It also includes instructions and a script to help with setting up additional multisite instances, although depending on your particular needs it may require some customization.
Drupal is a flexible and extensible PHP-based CMS framework capable of hosting multiple sites on a single code base.
- PHP 7.4
- MariaDB 10.4
- Redis 6
- Drush and Drupal Console included
- Pre-configured for multiple sites
- Automatic TLS certificates
- Composer-based build
Each subsite installs separately. As configured, this project uses a subdomain for each subsite. For each subsite, run through the Drupal installer as normal. You will not be asked for database credentials as those are already provided.
The following changes have been made relative to Drupal 8 as it is downloaded from Drupal.org. If using this project as a reference for your own existing project, replicate the changes below to your project.
- The
.platform.app.yaml
,.platform/services.yaml
, and.platform/routes.yaml
files have been added. These provide Platform.sh-specific configuration and are present in all projects on Platform.sh. You may customize them as you see fit. However, the multi-site logic will only work if the conventions documented below are retained. - An additional Composer library,
platformsh/config-reader
, has been added. It provides convenience wrappers for accessing the Platform.sh environment variables. - Drush and Drupal Console have been pre-included in
composer.json
. You are free to remove one or both if you do not wish to use them. (Note that the default cron and deploy hooks make use of Drush commands, however.) - The Drupal Redis module comes pre-installed. The placeholder module is not pre-installed, but it is enabled via
settings.platformsh.php
out of the box. - The
sites/sites.php
file has been modified to dynamically build a$sites
index based on the available routes. If you wish to alter the subsite logic you will need to change the contents of theforeach()
loop in that file. - The
sites/settings.platformsh.php
file contains Platform.sh-specific code to map environment variables into Drupal configuration. You can add to it as needed. See the documentation for more examples of common snippets to include here. It uses the Config Reader library. - The
sites/default
site directory is unused. It is retained as an example for copy-and-paste-ing only. - The
settings.php
file has been heavily customized to only define those values needed for both Platform.sh and local development. It calls out tosettings.platformsh.php
if available. You can add additional values as documented indefault.settings.php
as desired. It is also setup such that when you install Drupal on Platform.sh the installer will not ask for database credentials as they will already be defined.
Multisite on Platform.sh can be tricky. Drupal multisite bases its logic off of the domain name of the incoming request. However, the domain name of the request is by design highly variable on Platform.sh as every environment has a unique domain. As a result, this template establishes a number of conventions and custom configuration to make multi-site work.
- Every subsite is a subdomain off of a common domain. See
routes.yaml
. The domain prefix is the "subsite ID". - Every subsite has its own database and endpoint on a single MariaDB service instance. The endpoint name is the same as the subsite ID.
- The
sites/sites.php
file includes code to build a$sites
lookup list to map any incoming request, regardless of branch, to a settings directory named for the subsite ID. It iterates over all routes that point to the Drupal application and parses those routes into a domain name -> directory list, where the directory is the site ID. If you are not using a subdomain based multi-site you will likely need to modify the body of theforeach()
loop. - The
.platform.app.yaml
file is essentially the same as for a single-site Drupal installation, but its relationships include every defined MariaDB endpoint. The relationship is also named for the subsite ID. - Every subsite ID's
settings.php
file is identical, and largely similar to the standard Platform.shsettings.php
file. You may customize it if needed. In particular, the$platformsh_enable_redis
variable should be toggled totrue
for each site only after the install process is completed for that site, as Drupal cannot install with the redis module active. - The
settings.php
files also include a sharedsites/settings.platformsh.php
file. It is largely the same as in a single-site configuration but has been modified to leverage the subsite ID for:- Selecting which database relationship to use
- Including a cache prefix in Redis so that each site has its own effective cache pool.
- Setting the files and private files directories, which are subsite ID prefixes of top-level
files
andprivate
directories rather than under each site directory.
Adding a new subsite requires the following steps. For these steps, assume we're adding a subdomain named stuff
.
- Add a new route to
routes.yaml
with a newstuff
domain prefix. Copying and pasting an existing route is fine. - Copy the
sites/default
directory tosites/stuff
. - Edit
services.yaml
and add a new database and endpoint. Copying and pasting an existing entry is fine. The new relationship must be namedstuff
. - Edit
.platform.app.yaml
and add a new relationship:stuff: db:stuff
. (Wheredb
is the name of the database service fromservices.yaml
.) - Commit the above changes and push.
- In your browser, go to the
stuff.example.com
domain (or equivalent on a dev environment) and run through the Drupal installer as usual. Alternatively, you can use Drush as described bellow. - Edit the
sites/stuff/settings.php
file again and enable Redis by setting$platformsh_enable_redis
to true. - Commit and push that change.
- Profit.
Alternatively, a PHP shell script is provided that automates steps 1-4. See psh-subsite-add.php
.
In a Drupal multi-site setup, sites ID are defined in web/sites/sites.php. By default in this multi-site template, 2 subsites are defined in routes.yaml: first
and second
Any Drush command can therefore be used on a specific subsite by using --uri=
. For example:
drush status --uri=first
drush status --uri=second