Enhance script docs

docs/scripts.md

@@ -27,24 +27,68 @@ will show `I am running on mbb`.
 * The host-configuration gets exposes via the `host.`-prefix, so `port` maps to `%host.port%`, etc.
 * The dockerHost-configuration gets exposed via the `dockerHost`-prefix, so `rootFolder` maps to `%dockerHost.rootFolder%`
 * The global configuration of the yams-file gets exposed to the `settings`-prefix, so `uuid` gets mapped to `%settings.uuid%
-* Optional arguments to the `script`-taks get the `argument`-prefix, e.g. `%arguments.name%`. You can get all arguments via `%arguments.combined%`.
+* Optional arguments to the `script`-task get the `argument`-prefix, e.g. `%arguments.name%`. You can get all arguments via `%arguments.combined%`.
+* Questions will also be exposed under the `%arguments.`-prefix (See below)
+* Computed properties are exposed under the `%computed.`-prefix. (See below)
+* Secrets are exposed under the `%secret.`-prefixe (See the [secrets](/passwords)-section)
 * You can access hierarchical information via the dot-operator, e.g. `%host.database.name%`
 
+
 If phabalicious detects a pattern it can't replace it will abort the execution of the script and displays a list of available replacement-patterns.
 
+Here's a more elaborated example:
+
+```yaml
+foo: bar
+
+hosts:
+  a:
+    foo: foobar
+  b:
+    foo: baz
+
+scripts:
+  global-example:
+    - echo foo is %settings.foo%
+  host-specific:
+     - echo foo is %host.foo%
+  user-example:
+    defaults:
+      foo: %settings.foo%
+    script:
+      echo foo is %arguments.foo%
+
+```
+
+Here's the output:
+
+```shell
+$ phab -ca script global-example
+foo is bar
+
+$ phab -ca script host-specific
+foo is foobar
+
+$ phab -cb script host-specific
+foo is baz
+
+$ phab -ca script user-example --arguments foo=foobarbaz
+foo is foobarbaz
+```
+
 ## Internal commands
 
-There are currently 3 internal commands. These commands control the flow inside phabalicious:
+Phab provides a set of internal commands which can be called from within a script:
 
-* `fail_on_error(1|0)` If fail_on_error is set to one, phabalicious will exit if one of the script commands returns a non-zero return-code. When using `fail_on_error(0)` only a warning is displayed, the script will continue.
+* `fail_on_error(1|0)` If fail_on_error is set to one, phabalicious will exit if one of the script commands returns a non-zero return-code. When using `fail_on_error(0)` only a warning is displayed, the script will continue. Default is to stop execution if en error is detected
 * `execute(task, subtask, arguments)` execute a phabalicious task. For example you can run a deployment from a script via `execute(deploy)` or stop a docker-container from a script via `execute(docker, stop)`
 * `fail_on_missing_directory(directory, message)` will print message `message` if the directory `directory` does not exist.
 * `log_message(severity, message)` Prints a message to the output, for more info have a look at the [scaffolder-documentation](/scaffolder).
 * `confirm(message)` Will prompt for a confirmation from the user.
 
 ## Task-related scripts
 
-You can add scripts to the `common`-section, which will called for any host. You can differentiate by task-name and host-type, e.g. create a script which gets called for the task `deploy` and type `dev`.
+You can add scripts to the `common`-section, which will be called for any host. You can differentiate by task-name and host-type, e.g. create a script which gets called for the task `deploy` and type `dev`.
 
 You can even run scripts before or after a task is executed. Append the task with `Prepare` or `Finished`.
 
@@ -66,7 +110,7 @@ These scripts in the above examples gets executed only for the host `test` and t
 
 ## Defaults
 
-You an provide defaults for a script, which can be verridden via the `--arguments` commandline option
+You can provide defaults for a script, which can be overridden via the `--arguments` commandline option
 
 ```yaml
 scripts:
@@ -124,6 +168,53 @@ These script execution-contexts are available
    the script will be executed in a docker-container created with the provided name of the docker-image to use. The current folder will be mounted as a volume inside the docker-container at `/app` and the script will be executed as the current user and group (if not a dedicated user is set via `user`). The container will be deleted afterwards, if you need to keep files persistent, make sure to move/ copy them to `/app`
    The above example will install the node-based app and execute the `build`-command
 
+ * `docker-compose-run`
+
+   the script will be executed in a specific service of a docker-compose-setup. This will give you greater control when your app needs specific services running. When setting the context to `docker-compose-run` you need to provide the path to the `docker-compose.yml` file, the name of the service phab should use to execute the commands in and some other, optional parameters. Here's a full-fledge example:
+
+   ```yaml
+   scripts:
+     test:backend:
+       script:
+         - composer install
+         - php artisan migrate:fresh --seed
+         - vendor/bin/phpunit
+       context: docker-compose-run
+       rootFolder: ./hosting/tests
+       shellExecutable: /bin/bash # defaults to /bin/sh
+       service: php
+       environment:
+         FOO: bar
+         FOOBAR: baz
+   ```
+
+   Phab will search for a `docker-compose.yml` in `.hosting/tests` and will run `docker-compose run php /bin/bash` to start a shell in the container of the named `service`. Any environment variables in `environment` get passed to docker-compose beforehand. Afterwards it will run the script itself in the service. After the script completes, phab will remove any containers and volumes automatically. Here's the corresponding docker-compose.yml-file:
+
+   ```yaml
+   version: '2.1'
+   services:
+     php:
+       depends_on:
+         db:
+           condition: service_healthy
+       build:
+         context: ../../
+         dockerfile: ./hosting/builder/Dockerfile
+       environment:
+         DB_PASSWORD: root
+         DB_USERNAME: root
+         DB_DATABASE: tests
+         DB_HOST: db
+         APP_ENV: local
+       db:
+         image: mysql:8
+         environment:
+           MYSQL_ROOT_PASSWORD: root
+           MYSQL_DATABASE: tests
+         healthcheck:
+           test: "mysqladmin -u root -proot ping"
+   ```
+
 ## Questions
 
 A script can have a collection of questions to get data from the user in an interactive way. Here's an example: