README

Used by digipolis, serving as an example.

This package contains a RoboFileBase class that can be used in your own RoboFile. All commands can be overwritten by overwriting the parent method.

Example

<?php

use DigipolisGent\Robo\Drupal8\RoboFileBase;

class RoboFile extends RoboFileBase
{
    use \Robo\Task\Base\loadTasks;

    /**
     * @inheritdoc
     */
    public function digipolisDeployDrupal8(
        array $arguments,
        $opts = [
            'app' => 'default',
            'site-name' => 'Drupal',
            'profile' => 'standard',
            'force-install' => false,
            'config-import' => false,
            'existing-config' => false,
            'worker' => null,
        ]
    ) {
        $collection = parent::digipolisDeployDrupal8($arguments, $opts);
        $collection->taskExec('/usr/bin/custom-post-release-script.sh');
        return $collection;
    }
}

Available commands

Following the example above, these commands will be available:

digipolis:backup-drupal8           Create a backup of files
(sites/default/files) and database.
digipolis:build-drupal8            Build a Drupal 8 site and package it.
digipolis:clean-dir                Partially clean directories.
digipolis:clear-op-cache           Command digipolis:database-backup.
digipolis:database-backup          Command digipolis:database-backup.
digipolis:database-restore         Command digipolis:database-restore.
digipolis:deploy-drupal8           Build a Drupal 8 site and push it to the
servers.
digipolis:download-backup-drupal8  Download a backup of files
(sites/default/files) and database.
digipolis:init-drupal8-remote      Install or update a drupal 8 remote site.
digipolis:install-drupal8          Install the D8 site in the current folder.
digipolis:package-project          Package a directory into an archive.
digipolis:push-package             Command digipolis:push-package.
digipolis:restore-backup-drupal8   Restore a backup of files
(sites/default/files) and database.
digipolis:sync-drupal8             Sync the database and files between two
Drupal 8 sites.
digipolis:update-drupal8           Executes D8 database updates of the D8 site
in the current folder.
digipolis:upload-backup-drupal8    Upload a backup of files
(sites/default/files) and database to a server.

Multisites / site aliases

Drupal 8 multisites are supported. There are two ways to implement them:

Use Drupal's sites.php

This script can parse the site aliases from sites.php, where the keys of the $sites array are the urls and the values the folders (under the sites/ folder in the web root.

Use properties.yml:

You can define you site aliases in properties.yml under the remote key in the same manner: keys are the urls, values the folders. For example:

remote:
  aliases:
    example.com: default
    alias1.example.com: alias1
    alias2.example.com: alias2

You can read more about the properties.yml file in the Readme of the helpers package.

Multisite settings files

If you want to symlink the settings files of each of your multisite installations (which is recommended, since the alternative would be to have them in your repository), you'll have to add those symlinks to the properties.yml. Same goes for the files directories.

Using the example above, you'll have to add this to your properties.yml:

remote:
  symlinks:
    # Settings file symlinks.
    - '${remote.configdir}/alias1/settings.php:${remote.webdir}/sites/alias1/settings.php'
    - '${remote.configdir}/alias2/settings.php:${remote.webdir}/sites/alias2/settings.php'
    # Files directories symlinks.
    - '${remote.filesdir}/alias1/public:${remote.webdir}/sites/alias1/files'
    - '${remote.filesdir}/alias2/public:${remote.webdir}/sites/alias2/files'

Rollbacks on multisites

Since backups are made at the beginning of the multisite deploy, every site of the multisite is rolled back whenever there is an error in the deploy process, even when the error happens during the deploy of the first alias. So in the example above, at the beginning of the deploy, a database backup is made for default, alias1 and alias2. If the process fails during the deploy of default, the rollback process will restore the database backups of default, alias1 and alias2. Some goes for when it fails during the deploy of alias2. Deploys are done in the order the aliases are defined.

Adding a new site to an existing setup

When a new site is added to an existing installation, make sure all settings files and folders are in place (just like you would with a normal first time installation). The site that was newly added will go through the installation process, the sites that already existed will be left alone. This means you can't update one subsite, while adding another at the same time. You'll have to do that in two separate deploys.

Installing from an existing database

This goes for both 'normal' and multisite installations. If for some reason you would like to create a new site starting from an existing (meaning non-emtpy) database (not recommended), you can. Just fill your database with the data you need and trigger the deploy. The deploy will detect there is no site yet (since there will be no code on your server) and trigger the install script. Once your code is uploaded to your server, the install script will be able to connect to the database. It will then detect there's allready data in it, and skip the install process. This way your code is uploaded to your server and it will use the existing database. If your database is behind on you code (meaning you'll need to trigger database updates), you'll have to execute a second deploy.

This is also the reason, that when adding a new site to your multisite installation, the existing ones will be left alone. We would have had to overwrite the entire base package (robo-digipolis-helpers) to detect which site of the multisite is a new one and which one is an existing one that might need an update. So instead, when the deploy script detects that at least one site of the multisite installation needs an install from scratch, the install script is triggered for all sites of the multisite installation. If then the install script runs for one of the existing sites, it'll detect the existing data in its database and leave it at that. For the newly added site there'll be no data (unless you manually entered it in the database) and it will trigger the installation for that specific site.

General gotchas

We assume the value of $config_directories['sync'] is relative to the web root. We prepend it with the path to the web root ourselves.
If multiple aliases point to the same folder, we only use the first alias in the array. Keep this in mind for e.g. your sitemap.

digipolisgent / robo-digipolis-drupal8

Maintainers

Details