Table of Contents

Manual Steps

PayPal IPN Setup

Ensure that the client does this, or get the PayPal credentials and add them to our password safe.

Enable Instant Payment Notifications for the account.

CiviCRM Admin docs:

TODO: distill the above references and include complete documentation here.

Ensure Filesystem Permissions

Hopefully, past issues with permissions have been resolved; but never say never.

If after you run the chapter creation utility, you find there are issues with file permissions, use the setfacls utility located at /var/www/

Unlike other scripts in the suite, it does not take environment parameters. Set the PROOT environment variable to select the parent of your web-root or export it to your session.

$ PROOT=/var/www/ ./setfacls

Add existing contacts to the chapter

Confirm the domain under Administer > System Settings > Multi Site Settings.

Add any contacts to that group that you want to give access to.

Set Appropriate Staff Drupal Roles

Log into the new chapter site using the admin login.

Find the FIS staff user and replicate their roles from the primary site.

Set Primary Domain Info and Site Info

i.e. CiviCRM > Administer > Communications > Organization Address and Contact Info

The name of the organization is already set. Setting the Description is a good idea.

Drupal > Administration > Configuration > System > Site Information

Update Outgoing Mail Settings

TODO: update this section.

We are back to using SparkPost. All the chapters use the same sending-domain and therefore the same API-key.

Set Mosaico WYSIWYG Configs

When FIS wanted some changes to Mosaico, we found it was only do-able through a hook.

So we created an extension to manage two settings: mosaico_plugins and mosaico_toolbar.

Make sure to com.ginkgostreet.mosaicotoolbarconfig extension is enabled on the new chapter.

Go to Administer > CiviMail > Mosaico Settings

Copy the Plugin List and Toolbar Settings from another chapter.

There are some utils in the Makefile that should aid in validating that these settings are uniform for all chapters, as well as setting new values for all chapters. Use the Source, Luke.

Compile Theme Assets

Check that sites/*/files/adaptivetheme/adaptivetheme_subtheme_files/ exists and contains theme files. If not, proceed with the work-around.

BTW, this theme appears to only be used for the CiviCRM Admin theme, so maybe pretty easy to get rid of this bull-crap. Last chapter creation showed that the layout on CiviCRM pages was broken in minor ways without doing the following.

The theme (after being installed in the new drupal instance for the chapter) needs to build an aggregate CSS file based on the selections in the theme settings form. There is no API for this.

This is documented in the module here:


When the script enables the fis_multisite_config module, it's install hook does a drupal_form_submit() 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.


There is an issue that has recurred and without a full chapter-spin-up, it is not certain that it has been resolved. The symptom is that an error message is displayed in the footer of the site, on every page. This has pretty catastrophic consequences.

The issue is with composer_manager_sa (security alerts). This should be a dependency of composer_manager, but apparently is not installed automatically. It has been added explicitly to the chapter script. However, I am not certain that installing via the script will perform the composer dependency updates. Research might be necessary to learn how to trigger composer updates if they do not run when enabling the module in an automated script.

Below is sample output from enabling the module manually.

The following extensions will be enabled: composer_manager_sa
Do you really want to continue? (y/n): y
composer_manager_sa was enabled successfully.                                                                                                                                                       [ok]
One or more extensions have dependencies managed by Composer.
Update packages managed by Composer? (y/n): y
Cannot create cache directory /home/mzd/.composer/cache/repo/, or directory is not writable. Proceeding without cache
Cannot create cache directory /home/mzd/.composer/cache/files/, or directory is not writable. Proceeding without cache
Loading composer repositories with package information
Updating dependencies (including require-dev)
  - Installing symfony/polyfill-mbstring (v1.11.0)
    Downloading: 100%         

  - Installing psr/log (1.1.0)
    Downloading: 100%         

  - Installing symfony/debug (v3.0.9)
    Downloading: 100%         

  - Installing symfony/console (v2.8.49)
    Downloading: 100%         

  - Installing sensiolabs/security-checker (v2.0.6)
    Downloading: 100%         

symfony/console suggests installing symfony/event-dispatcher ()
symfony/console suggests installing symfony/process ()
symfony/console suggests installing psr/log-implementation (For using the console logger)
Package egeloen/http-adapter is abandoned, you should avoid using it. Use php-http/httplug instead.
Writing lock file
Generating autoload files
SensioLabs\Security\Exception\RuntimeException: An error occurred: Could not resolve host: in                                                                              [error]
Stack trace:
#0 /var/www/ SensioLabs\Security\SecurityChecker->check('/var/www/prod.i...')
#1 /var/www/ composer_manager_sa_vulnerabilities('/var/www/prod.i...')
#2 /var/www/ composer_manager_sa_check('/var/www/prod.i...')
#3 /var/www/ composer_manager_sa_print()
#4 /var/www/ composer_manager_sa_composer_dependencies_install()
#5 /var/www/ module_invoke_all('composer_depend...')
#6 /var/www/ drush_composer_manager('update')
#7 /var/www/ drush_composer_manager_write_if_changed()
#8 phar:///usr/local/bin/drush/includes/ drush_composer_manager_post_pm_enable('composer_manage...')
#9 phar:///usr/local/bin/drush/includes/ _drush_invoke_hooks(Array, Array)
#10 phar:///usr/local/bin/drush/includes/ drush_command('composer_manage...')
#11 phar:///usr/local/bin/drush/lib/Drush/Boot/BaseBoot.php(67): drush_dispatch(Array)
#12 phar:///usr/local/bin/drush/includes/ Drush\Boot\BaseBoot->bootstrap_and_dispatch()
#13 phar:///usr/local/bin/drush/includes/ drush_main()
#14 phar:///usr/local/bin/drush/drush(114): drush_startup(Array)
#15 /usr/local/bin/drush(10): require('phar:///usr/loc...')
#16 {main}
mzd@testtube:/var/www/$ cd ..
mzd@testtube:/var/www/$ sudo -u www-data drush @sites cc all
You are about to execute 'cc all' non-interactively (--yes forced) on all of the following targets:


You've completed the chapter set-up, congratulations.

The rest of the documents in this section document provide details useful for troubleshooting and document the utility script itself.