Table of Contents

Manual Steps

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/dev.israelscouts.org/utils/fis_multisite_tools/setfacls.

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/dev.israelscouts.org ./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

https://arava.israelscouts.org/civicrm/admin/domain?action=update&reset=1

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

Drupal > Administration > Configuration > System > Site Information

https://arava.israelscouts.org/admin/config/system/site-information

Update Outgoing Mail Settings

Since the SparkMonkey extension is dead to us... the script is out of date with respect to the mailer settings.

Any CiviCRM settings that are not in the instance config file, need to be explicitly configured.

There is a work-in-progress utility for this that works, but is not polished. See fis_multisite_utils/mailing_backend.mk.

Go to CiviCRM Administer > Communications > FROM email addresses, and add [email protected] and make it the default.

Go to CiviCRM Administer > System Settings > Outbound Email (SMTP/Sendmail). Make sure that SMTP is set and send a test email.

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: https://github.com/ginkgostreet/fis_multisite_config/blob/master/fis_multisite_config.install#L13

And

https://www.drupal.org/node/1809126

When the create-multisite-instance.sh 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.

Look-out!

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/https---packagist.org/, 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: security.sensiolabs.org. in                                                                              [error]
/var/www/prod.israelscouts.org/htdocs/sites/all/vendor/sensiolabs/security-checker/SensioLabs/Security/SecurityChecker.php:102
Stack trace:
#0 /var/www/prod.israelscouts.org/htdocs/sites/all/modules/composer_manager/composer_manager_sa/composer_manager_sa.module(85): SensioLabs\Security\SecurityChecker->check('/var/www/prod.i...')
#1 /var/www/prod.israelscouts.org/htdocs/sites/all/modules/composer_manager/composer_manager_sa/composer_manager_sa.module(39): composer_manager_sa_vulnerabilities('/var/www/prod.i...')
#2 /var/www/prod.israelscouts.org/htdocs/sites/all/modules/composer_manager/composer_manager_sa/composer_manager_sa.drush.inc(39): composer_manager_sa_check('/var/www/prod.i...')
#3 /var/www/prod.israelscouts.org/htdocs/sites/all/modules/composer_manager/composer_manager_sa/composer_manager_sa.module(16): composer_manager_sa_print()
#4 /var/www/prod.israelscouts.org/htdocs/includes/module.inc(965): composer_manager_sa_composer_dependencies_install()
#5 /var/www/prod.israelscouts.org/htdocs/sites/all/modules/composer_manager/composer_manager.drush.inc(102): module_invoke_all('composer_depend...')
#6 /var/www/prod.israelscouts.org/htdocs/sites/all/modules/composer_manager/composer_manager.drush.inc(153): drush_composer_manager('update')
#7 /var/www/prod.israelscouts.org/htdocs/sites/all/modules/composer_manager/composer_manager.drush.inc(128): drush_composer_manager_write_if_changed()
#8 phar:///usr/local/bin/drush/includes/command.inc(373): drush_composer_manager_post_pm_enable('composer_manage...')
#9 phar:///usr/local/bin/drush/includes/command.inc(224): _drush_invoke_hooks(Array, Array)
#10 phar:///usr/local/bin/drush/includes/command.inc(192): 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/preflight.inc(66): Drush\Boot\BaseBoot->bootstrap_and_dispatch()
#13 phar:///usr/local/bin/drush/includes/startup.inc(325): 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}
[email protected]:/var/www/prod.israelscouts.org/htdocs/sites/gilad.israelscouts.org$ 
[email protected]:/var/www/prod.israelscouts.org/htdocs/sites/gilad.israelscouts.org$ cd ..
[email protected]:/var/www/prod.israelscouts.org/htdocs/sites$ 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:
  /var/www/prod.israelscouts.org/htdocs#shemesh.israelscouts.org
  /var/www/prod.israelscouts.org/htdocs#kochav.israelscouts.org
  /var/www/prod.israelscouts.org/htdocs#atidnyc.israelscouts.org
  /var/www/prod.israelscouts.org/htdocs#pisga.israelscouts.org
  /var/www/prod.israelscouts.org/htdocs#chen.israelscouts.org
  /var/www/prod.israelscouts.org/htdocs#gefen.israelscouts.org
  /var/www/prod.israelscouts.org/htdocs#gilad.israelscouts.org
  /var/www/prod.israelscouts.org/htdocs#atidli.israelscouts.org

Congratulations

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.