From a8a4ec9f650c17c207b935347a7af4ad6387ef08 Mon Sep 17 00:00:00 2001 From: Stephan Huber Date: Tue, 5 Jul 2022 13:45:01 +0200 Subject: [PATCH] Enhance script docs --- docs/scripts.md | 101 +++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 96 insertions(+), 5 deletions(-) diff --git a/docs/scripts.md b/docs/scripts.md index 485e7741..574cdeb6 100644 --- a/docs/scripts.md +++ b/docs/scripts.md @@ -27,16 +27,60 @@ 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). @@ -44,7 +88,7 @@ There are currently 3 internal commands. These commands control the flow inside ## 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: