Adding documentation for setting up workspace on Drupal projects

src/drupal8/docs/contribute.md

@@ -1,21 +1,35 @@
 # Contributing to the Drupal 8 harness
 
-Clone the project:
-```
+Clone the project from [harness-base-php]:
+```bash
 git clone [email protected]:inviqa/harness-base-php.git
 ```
 
 ## Make changes
-Update the required files in `src/drupal8`
+
+Update the required files in `src/drupal8`, or if the change is relevant to all harnesses, `src/_base`.
 
 ## Testing your changes
-```
+```bash
 ./build && ./test drupal8 dynamic
 ```
 This uses `src/drupal8/.ci/sample-dynamic/workspace.yml` so any attributes you want to test specifically can be changed here (but not committed)
 
-### Pre-requisite 
+### Pre-requisite
 You will need to first export the `MY127WS_KEY` in order to run a build:
 ```
 export MY127WS_KEY="<key>"
 ```
+
+## Create a Pull Request
+
+Make a new branch and commit your changes.
+
+If you have write access to [harness-base-php], you can push the new branch
+to the same repository, else you will have to fork via GitHub's UI, add
+your fork of the repository as a git remote and push the branch there.
+
+Once the branch is pushed up to GitHub, you can raise a pull request against
+the current default branch in [harness-base-php].
+
+[harness-base-php](https://github.com/inviqa/harness-base-php)

src/drupal8/docs/customise/advanced.md

@@ -1,19 +1,19 @@
 # Advanced customisation
 
 There may be times when you need to customise the Workspace environment beyond what is capable via attribute overrides.  
- 
- In these situations, if the customisation can be generalised then please look at the [contributing guide] on how to make the feature available for all projects. 
+
+ In these situations, if the customisation can be generalised then please look at the [contributing guide] on how to make the feature available for all projects.
 
 
 ## Adding a new service
-If you need a service that isn't already provided (see [available base services](../../../_base/_twig/docker-compose.yml/service)) then you can register a new service following the [docker-compose](https://docs.docker.com/compose/compose-file/) notation.
+If you need a service that isn't already provided (see [available base services](https://github.com/inviqa/harness-base-php/blob/0.10.x/src/_base/_twig/docker-compose.yml/service)) then you can register a new service following the [docker-compose](https://docs.docker.com/compose/compose-file/) notation.
 
 Create your new service file in the `tools/workspace/_twig/docker-compose.yml/service/` directory.  
 
-See the example `solr.yml.twig` service file below. Note the indentation, this is deliberate and must be followed to avoid docker-compose errors. 
+See the example `solr.yml.twig` service file below. Note the indentation, this is deliberate and must be followed to avoid docker-compose errors.
 ```yaml
   solr:
-    image: {{ @('solr.image') }}:{{ @('solr.version') }}
+    image: {{ @('services.solr.image') }}
     labels:
       - traefik.backend=solr{{ @('workspace.name') }}
       - traefik.frontend.rule=Host:solr-{{ @('hostname') }}
@@ -40,8 +40,7 @@ attribute('app.services'):
   - redis
   - solr
 
-attribute('solr.image'): solr
-attribute('solr.version'): 6.6.6
+attribute('services.solr.image'): "solr:6-slim"
 attribute('solr.config_dir'): = @('drupal.docroot') ~ '/modules/contrib/search_api_solr/solr-conf/6.x'
 ```
 
@@ -50,16 +49,16 @@ attribute('solr.config_dir'): = @('drupal.docroot') ~ '/modules/contrib/search_a
 When overriding harness files or adding application overlay files using twig templates can be valuable for providing access to Workspace attributes. Not only this but you will have the power of [twig] at your fingertips.
 
 To use a twig template there are 2 key steps;
-* First create your file and append `.twig` to the filename. 
+* First create your file and append `.twig` to the filename.
 * Second, register your file within `confd.yml` to be compiled by the twig render method.
 
 Let's work through an example for adding drush aliases based on a list of multi-site domains.  
 Keep in mind that in `workspace.yml` we have defined our hostnames as follows:
 ```yaml
 attribute('hostname_aliases'):
-  - site-one
-  - site-two
-  - site-three
+  - site-one-projectname
+  - site-two-projectname
+  - site-three-projectname
 ```
 
 ### Create the template file
@@ -82,18 +81,18 @@ Now the file exists, but it won't be compiled until it has been registered. This
 More information on the `confd` type can be found [here](https://github.com/my127/workspace/blob/0.1.x/docs/types/confd.md)
 
 To update the file we will need to override the defaults.  
-Create the `confg.d` override in following folder structure:
+Create the `confd` override in following folder structure:
 ```
 tools/workspace/harness/config/confd.yml
 ```
 
 Make sure you copy the default configuration from the relevant harness.   
 The Drupal 8 defaults can be found [here](../../harness/config/confd.yml)
- 
+
 Adding the new file path will look like this:
 ```yaml
 confd('harness:/'):
-  ...
+  ...existing files...
   # Custom templates
   - { src: application/overlay/docroot/drush/sites/ws.site.yml }
 ```

src/drupal8/docs/customise/commands.md

@@ -3,11 +3,14 @@
 Adding commands can help with productivity and to standardise tasks.  
 Information on writing commands can be found [here](https://github.com/my127/workspace/blob/0.1.x/docs/types/command.md)
 
-There are also a number of [default commands](/src/_base/harness/config/commands.yml) available that may already provide the funcitonality you require. 
+There are also a number of [default commands](https://github.com/inviqa/harness-base-php/blob/0.10.x/src/_base/harness/config/commands.yml) available that may already provide the functionality you require.
 
 If not, here are some example that might be a good starting point.
 
-_Note: if your command will be executed on a CI environment it is good practice to include the `COMPOSE_PROJECT_NAME` environment variable to define the project that the command should be executed on._
+_Note: If someone clones the project repository as a different name than what's in workspace.yml for
+`workspace('projectname')`, docker-compose commands will fail due to using the directory name by default.
+The way around this is to ensure you include the `COMPOSE_PROJECT_NAME` environment variable any time
+you use `docker-compose` from within a custom command._
 
 ### Refresh script - `ws drupal-refresh`
 ```yaml
@@ -16,6 +19,7 @@ command('drupal-refresh'):
     COMPOSE_PROJECT_NAME: = @('namespace')
   exec: |
     #!bash(workspace:/)|@
+    docker-compose exec console echo "Running drupal-refresh"
     ws composer install
     ws drush -y cr
     ws drush -y updb
@@ -29,6 +33,7 @@ command('sanitise-db'):
     COMPOSE_PROJECT_NAME: = @('namespace')
   exec: |
     #!bash|=
+    docker-compose exec console echo "Running sanitise-db"
     ws drush sql-sanitize --sanitize-password=password -y
     ws drush uublk 1
     ws drush uli

src/drupal8/docs/customise/overrides.md

@@ -5,7 +5,7 @@ More information can be found on the attribute type in the Workspace documentati
 
 ## Set an attribute value
 Take a moment to see the attributes that are defined in the Drupal 8 [harness.yml]. These are built on the defaults from [common.yml] in the base harness.  
-These can all be customised in `workspace.yml` using `attribute()`. 
+These can all be customised in `workspace.yml` using `attribute()`.
 
 Here are some examples:
 * Change the database name:
@@ -21,13 +21,6 @@ Here are some examples:
   # Set the local URL to mysite.my127.site
   attribute('hostname'): = 'mysite.' ~ @('domain')
   ```
-* It is even possible to update service definitions:
-  ```yaml
-  attribute('services.redis.volumes'):
-    - = './' ~ @('redis.config_dir') ~ ':/server-config'
-
-  attribute('services.redis.command'): redis-server /server-config/redis.conf
-  ```
 
 ## Merge not override
 
@@ -69,7 +62,7 @@ You can find even more in [common.yml], e.g. `frontend.build.steps`.
 
 When you see `steps`, there will more than likely be a `task` that defines how and when these steps are executed.
 
-To understand more, take a look at the tasks in the `console` docker image [here](../../../_base/docker/image/console/root/lib/task) 
+To understand more, take a look at the tasks in the `console` docker image [here](https://github.com/inviqa/harness-base-php/blob/0.10.x/src/_base/docker/image/console/root/lib/task)
 
 [harness.yml]: ../../harness.yml
-[common.yml]: ../../../_base/harness/attributes/common.yml
+[common.yml]: https://github.com/inviqa/harness-base-php/blob/0.10.x/src/_base/harness/attributes/common.yml

src/drupal8/docs/install/existing-project.md

@@ -1,41 +1,56 @@
 # Setting up Workspace on an existing project
 
 1. To add Workspace to an existing project, the easiest way to do this is to first change to the project directory:
-    ```
+    ```bash
     cd /path/to/project
     ```
     From here, run the `ws create` command, but don't run the installation:
-    ```
-    ws create <projectName> inviqa/drupal8:v0.9.4
+    ```bash
+    ws create <projectName> inviqa/drupal8:v0.9.4 --no-install
     ```
     (Note: see [harnesses.json] for available versions.)
 
-2. You will now have a new directory, `<projectName>` containing a number of files and folders. We don't need to be concerned with all of them.
+2.  You will now have a new directory, `<projectName>` containing a number of files and folders.
+
+    To be able to continue, we need to get to the point that the "skeleton" and "overlay" is applied,
+    so we can copy to our original project:
+    ```bash
+    cd <projectName>
+    git init
+    ws harness download
+    ws harness prepare
+    rsync --exclude='*.twig' --exclude='_twig' -a .my127ws/application/skeleton/ .
+    rsync --exclude='*.twig' --exclude='_twig' -a .my127ws/application/overlay/ .
+    ```
+
+3. We should be left with several folders and files from the harness skeleton.
+
+    You can see the list with `git status`.
 
     The following files are unlikely to already exist in the current project, if they do then you will need to review them and merge/override appropriately:
     * `workspace.yml`
-    * `workspace.override.yml`
-    * `features/`
-    * `behat.yml`
+    * `workspace.override.yml` - this will be in .gitignore, so won't show up in `git status`
     * `Jenkinsfile`
+    * `behat.yml`
+    * `features/`
     * `phpstan.neon`
 
     Move these from `<projectName>` into the project root.
 
-3. There will be some files that more than likely already exist in the project. These will need to be merged manually.
+4. There will be some files that more than likely already exist in the project. These will need to be merged manually.
     * `.gitignore`
     * `composer.json`
         * Specifically the `require-dev` and `scripts` sections.
     * `README.md`
 
-4. You can now delete the initial `<projectName>` folder:
+5. You can now delete the initial `<projectName>` folder:
     ```
     rm -r <projectName>
     ```
 
-5. Run `ws install` to set up the workspace.
+6. Run `ws install` to set up the workspace.
 
-6. Follow steps 2. and 5. from the [New project] install guide.
+7. Follow steps 2. and 5. from the [New project] install guide.
 
 [harnesses.json]: https://my127.io/workspace/harnesses.json
 [New project]: new-project.md

src/drupal8/docs/install/multi-site.md

@@ -19,15 +19,15 @@ At this point you should have at least a `workspace.yml` file in the project roo
 Here the hostnames for the multi-sites can be defined using the `hostname_aliases` attribute:
 ```yaml
 attribute('hostname_aliases'):
-  - site-one
-  - site-two
-  - site-three
+  - site-one-projectname
+  - site-two-projectname
+  - site-three-projectname
 ```
 
 These will have the `.my127.site` suffix added and will end up as:
-* site-one.my127.site
-* site-two.my127.site
-* site-three.my127.site
+* site-one-projectname.my127.site
+* site-two-projectname.my127.site
+* site-three-projectname.my127.site
 
 
 ## Creating multiple databases during install
@@ -48,16 +48,17 @@ You may have noticed that there is not a step to create a database for `one_site
 Having the database named `drupal` doesn't make sense here, so update the name for consistency:
 ```yaml
 attribute('database.name'): one_site
-``` 
+```
 
 
 ### Importing databases during install
 If you want to import databases during the Workspace install you can do so in the backend init steps. However, please be aware that you **MUST** have the database files in place before running `ws install`.
 
 ```yaml
 attribute('backend.init.steps'):
-  - DB_NAME=two_site task "assets:apply"
-  - DB_NAME=three_site task "assets:apply"
+  - ... existing GRANT steps from above ...
+  - DB_NAME=two_site task assets:apply
+  - DB_NAME=three_site task assets:apply
 ```
 
 The database dumps should be located in `tools/assets/development`, ensuring that the filename is the same as the database name that you defined in the previous step:
@@ -75,10 +76,10 @@ project-root/
 ## Update `sites.php`
 You will need to ensure that Drupal knows which site to serve when you visit a valid domain. `<drupalRoot>/sites/sites.php` should be updated to include the new Workspace URLs:
 ```php
-$sites['site-one.my127.site'] = 'default';
-$sites['site-two.my127.site'] = 'two';
-$sites['site-three.my127.site'] = 'three';
-``` 
+$sites['site-one-projectname.my127.site'] = 'default';
+$sites['site-two-projectname.my127.site'] = 'two';
+$sites['site-three-projectname.my127.site'] = 'three';
+```
 
 ## Update Drupal settings (`settings.local.php`)
 A perfectly acceptable solution is to add a `settings.local.php` file manually to the appropriate site directory when setting up the project locally.  
@@ -89,7 +90,7 @@ To do this you will need to update the workspace declaration to define the `over
 workspace('multisite-example'):
   ...
   overlay: tools/workspace
-``` 
+```
 
 The next step is to add the `settings.local.php` files to be copied over to the local environment. These will be located as follows:
 ```
@@ -102,7 +103,7 @@ project-root/
 .  .  .  .  └- docroot/
 .  .  .  .  .  └- sites/   
 .  .  .  .  .  .  ├- default
-.  .  .  .  .  .  ⎪  └- settings.local.php
+.  .  .  .  .  .  ⎪  └- settings.local.php.twig - copy from .my127ws/application/overlay/settings.local.php.twig
 .  .  .  .  .  .  ├- two
 .  .  .  .  .  .  ⎪  └- settings.local.php
 .  .  .  .  .  .  └- three
@@ -134,18 +135,18 @@ E.g. `ws.site.yml`:
 ```yaml
 one:
   root: /app/docroot
-  uri: https://site-one.my127.site
+  uri: https://site-one-projectname.my127.site
 two:
   root: /app/docroot
-  uri: https://site-two.my127.site
+  uri: https://site-two-projectname.my127.site
 three:
   root: /app/docroot
-  uri: https://site-three.my127.site
+  uri: https://site-three-projectname.my127.site
 ```
 Take a look at the [advanced customisation guide] for more ideas on how to improve on this.
- 
-## Allow directory write access for CI 
-This is only really relevelant if you're using the Jenkins or pipelines CI environments.
+
+## Allow directory write access for CI
+This is only really relevant if you're using the Jenkins or pipelines CI environments.
 
 Update the defaults to include the multisite files directories.
 ```yaml
@@ -154,9 +155,9 @@ attribute('app.web_writable_dirs'):
   - '/app/docroot/modules'              # ⎪ These are the defaults
   - '/app/docroot/profiles'             # ⎪ from the Drupal 8 harness.yml
   - '/app/docroot/sites/default/files'  # ⎦
-  - '/app/docroot/sites/site-one/files'
-  - '/app/docroot/sites/site-two/files'
-  - '/app/docroot/sites/site-three/files'
+  - '/app/docroot/sites/one/files'
+  - '/app/docroot/sites/two/files'
+  - '/app/docroot/sites/three/files'
 ```
 
 [new project]: new-project.md