Table of Contents

Utilities

Utilities

A custom environment and more script(s) are installed in /var/www/dev.israelscouts.org/utils and can be used to create new chapter sites, re-stage the dev or stage site, and more.

Spinning Up New Chapters

To aid in the quick deployment of new chapter sites, a utility script has been installed at /var/www/dev.israelscouts.org/utils/fis_multisite_tools/create-multisite-instance.sh. It takes care of everything from creating the CMS database; to creating a new domain record in the CRM; to enabling common settings, themes, modules, and extensions; to assigning default user roles; to creating a cron job. Apache is configured such that no new vhosts need to be created. You need only execute the script and point the DNS.

The utility need not be run as root, but it does use sudo internally and may request your sudo password. The utility uses the login-path flag for mysql commands and assumes that the login-path “root” provides root access to MySQL. If you haven’t set this up for your user on the server, run mysql_config_editor set -h localhost -G root -u root -p and supply the MySQL root user’s password when prompted.

The utility allows the administrator to specify the environment (with the e flag) in which to spin up the chapter site. It is recommend that deployments be tested in another environment before being deployed to production.

Run it with the h flag for more information on how it works; for the full picture, read the source.

TODOS/GOTCHAS:

  • Be sure that you do not have a mysql .my.cnf in your home dir. Drush is very clever about looking for db credentials to use. Similarly for the custom utils script (which sometimes use mysql login-path).
  • We are no longer using a Wildcard SSL certificate. So, the cert will have to be regenerated to include the new chapter. See below on Apache config for further reference.
  • The script does not set file permissions on the new Drupal files (e.g., the files directory). By default they will be owned by the user who ran the script, which may cause issues using CiviCRM in a web browser (because Apache won’t be able to write CiviCRM cache). You’ll either need to adjust the permissions manually or add such a step to the script. An experimental utility set-perms.sh may help with this; read it before running it.
  • In environments other than prod, CIVICRM_UF_BASEURL may be set incorrectly. The environment may be appended to the subdomain twice (e.g., chapter-stage-stage.israelscouts.org) -- this can be fundamentally addressed in the generateBaseUrl() function present in sites/default/civicrm.common.settings.php, or set manually in the site’s civicrm.settings.php file for a quick fix. (It’s worth noting that this file does not appear to be under version control, though it’s referenced several times in fis_multisite_tools. I think this is probably intentional -- these files contain information that will vary according to the environment and that, being sensitive, should not be under version control. I’m inclined to think the mistake is putting generateBaseUrl() in this file; a better alternative would be for the settings file to include the function from a file that is indeed under version control.)
  • Not all steps required to spin up a chapter site are scriptable. The list of manual steps is, to the best of our knowledge:
    • Kick administrative theme. This step is necessitated by a quirk in Drupal's module lifecycle and/or a poor architecture decision on the part of the author of the theme. Basically the issue boils down to this: in order for the theme to display as intended, it needs to perform certain tasks, such as build an aggregate CSS file based on the selections in the theme settings form. A certain (manual) workflow is assumed, and some of those tasks are triggered by actions such as submitting the theme settings form. Such an architecture does not lend itself well to automation. The create-multisite-instance.sh script simulates a form submission which performs some of the tasks, but a manual step is still required. Following deployment, an administrator needs to submit the theme settings form at /admin/appearance/settings/adaptivetheme_subtheme. You needn't make any changes -- just submit the form.

Refresh Script

Note, the refresh.sh script (used on other GSL sites) is deprecated for refresh.php.

This utility allows the administrator to specify the environment (with the -e flag) to "refresh" it from the production site. It is recommend that deployments be tested in another environment before being deployed to production, and it is often helpful/necessary for the development environment to be a mirror of production.

Like the utility that spins up new chapter sites, the utility uses the login-path flag for mysql commands and assumes that the login-path associated with the environment provides root access to MySQL.

Run it with the -h flag for more information on how it works; for the full picture, read the source.

Mysql Login Path Setup

If you haven’t set this up for your user on the server:

mysql_config_editor set -h localhost -G prod -u root -p 

...and supply the MySQL root user’s password when prompted. Then repeat this for each environment, changing the -G flag for each: prod, dev, and stage.