From f8b5b4b75c1985bae131ca5777dbbcb3c3436064 Mon Sep 17 00:00:00 2001
From: Chris Thompson <chris@wolcen.com>
Date: Tue, 23 Jun 2020 12:39:57 -0400
Subject: [PATCH] Add additional instructions for new sites on Drutopia,
 including drush config

---
 creating-new-drutopia-site.md | 59 +++++++++++++++++++++++++++++++++--
 1 file changed, 56 insertions(+), 3 deletions(-)

diff --git a/creating-new-drutopia-site.md b/creating-new-drutopia-site.md
index 267fad6..4a85bd6 100644
--- a/creating-new-drutopia-site.md
+++ b/creating-new-drutopia-site.md
@@ -32,11 +32,12 @@ Ordinarily this will live under https://gitlab.com/agaric/sites (for Agaric clie
 
 Copy the composer.json used by the appropriate build source, such as the [default build source for the Drutopia Platform](https://gitlab.com/drutopia-platform/build_source).
 
-Replace EXAMPLE below with name of the site, usually derived from the main domain name, for instance `example-com`:
+Replace "example" below with name of the site, usually derived from the main domain name, for instance `example-com`:
 
 ```
-mkdir -p ~/Projects/agaric/sites/EXAMPLE
-cd ~/Projects/agaric/sites/EXAMPLE
+MY_SITE="example"
+mkdir -p ~/Projects/agaric/sites/$MY_SITE
+cd ~/Projects/agaric/sites/$MY_SITE
 ```
 
 Once you have created and are in this directory, whether `agaric/sites` or `drutopia-platform/sites` or wherever you want your project to live within the GitLab namespace, you can copy-paste these commands for a quick start:
@@ -48,3 +49,55 @@ ddev config --docroot=web --project-type=drupal8 --webserver-type=apache-fpm --m
 
 ```note
 Webserver, PHP, and MySQL versions and types are selected here to match those used on Elizabeth and should be adjusted to match your live environment, including double-checking that they are still valid for `elizabeth.mayfirst.org`.  Please update this documentation if it changes!  The last two options (enabling Xdebug by default and not using DNS for your local site) are optional at the developer's preference.
+```
+
+## Acquiring a database and configuration for the live instance
+
+In order to get a configuration that has the proper site key, it is easiest to first deploy the site to the production location, and sync that database locally.
+
+If you are creating a specialized build of Drutopia, you will have to add that to the host vars, and build that prior to deploying the site. `ahoy vars-edit` and `ahoy deploy-build <build_target>` are used for this. Note that new builds should be added ONLY as absolutely required. Configuration, and themes should be leveraged as much as possible prior to resorting to a new build. If additional/different modules are required, a new build is required - do *NOT* add them to build_source except when they are known to be required for *ALL* Drutopia basic sites.
+
+Create a new site (member entry) per instructions in Drutopia hosting, and use `ahoy deploy-site <sitename>` to deploy it. This should install the site, when one is not present.
+
+### Configure drush aliases
+
+The drush site aliases file can be used to provide easy access to the live/test instances of a site. From the root of your project directory (e.g. `agaric/sites/example/`), you may create one with:
+
+```
+MY_SITE="example-com"
+SERVER="drutopia.org"
+mkdir -p drush/sites/
+cat << EOF > drush/sites/self.site.yml
+live:
+  host: ${SERVER}
+  paths:
+    drush-script: /home/${MY_SITE/-/_}_live/site/vendor/bin/drush
+  root: /home/${MY_SITE/-/_}_live/site/web
+  uri: 'https://${MY_SITE}-live.drutopia.org/'
+  user: ${MY_SITE/-/_}_live
+test:
+  host: ${SERVER}
+  paths:
+    drush-script: /home/${MY_SITE/-/_}_test/site/vendor/bin/drush
+  root: /home/${MY_SITE/-/_}_test/site/web
+  uri: 'https://${MY_SITE}-test.drutopia.org/'
+  user: ${MY_SITE/-/_}_test
+EOF
+```
+
+This will create a self.site.yml using the expected pattern of "site_name_INSTANCE" (e.g. example_com_live for the example-com live instance). Supply the URL form of the site name for the MY_SITE variable (i.e. with dashes, rather than underscores).
+
+### Syncing, and setting up configuration
+
+Drutopia releases will expect the configuration in `$project_root/config/sync`. Be sure to set the appropriate variable in settings.ddev.yml (or settings.php) for it to be stored/retrieved from there:
+
+```
+$settings['config_sync_directory'] = '../config/sync';
+```
+
+Once you also have a working Drush installation and a live instance, you can then acuire and export the initial configuration with:
+
+```
+ddev exec drush sql-sync @live @self
+ddev exec drush cex -y
+```