diff --git a/README.md b/README.md index 8294101..5c43234 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ -# colink-playbook-dev +# CoLink Playbook Dev -You can use this module to quickly set up a protocol of CoLink with just a few lines in the TOML file. +This module can be used to quickly set up a CoLink protocol with just a few lines in the TOML file. -## Run a protocol by playbook +## Running a Protocol by Playbook 1. Download the release binary of your system from GitHub. @@ -18,11 +18,11 @@ You can use this module to quickly set up a protocol of CoLink with just a few l cargo build --release ``` -2. Get your *colink-server address* and the *user's jwt* who wants to run the protocol as `` and ``, which can refer to [rust sdk](https://github.com/CoLearn-Dev/colink-sdk-rust-dev). +2. Get your *colink-server address* and the *user's jwt* who wants to run the protocol as `` and ``, which can be referred to in the [Rust SDK](https://github.com/CoLearn-Dev/colink-sdk-rust-dev). -3. Define your new protocol in the TOML file ( `colink.toml` by default), and get the path of your protocol as ``. +3. Define your new protocol in a config file (`colink.toml` by default) in TOML format, and get the path of your TOML file as ``. -4. [Optional] If your TOML file is not `colink.toml`, you need to set the env variable `COLINK_PLAYBOOK_CONFIG = `. +4. [Optional] If your TOML file name is not `colink.toml`, you need to set the env variable `COLINK_PLAYBOOK_CONFIG = `. 5. Run your protocol @@ -32,10 +32,12 @@ You can use this module to quickly set up a protocol of CoLink with just a few l ## Format of `TOML` file -You can define your protocol like this: (you need to replace all the field as `<...>`) +* You can define your protocol like the example below (you need to replace all the fields as `<...>`). + +* The playbook will run each step in order for each role. ```toml -[] +[] # po stands for protocol workdir = name = @@ -44,7 +46,7 @@ You can define your protocol like this: (you need to replace all the field as `< max_num = # [optional] Limit the number of users with this role in this protocol min_num = # [optional] as previous [.roles..playbook] - workdir = # [optional] If not defined, will set the protocol working path as role path + workdir = # [optional] If not defined, the protocol working path will be set as the role path [[.roles..playbook.steps]] # write actions here @@ -53,20 +55,21 @@ You can define your protocol like this: (you need to replace all the field as `< # write actions here [.roles.] - #define your other role action here + # define your other role action here [.roles.] - #define your other role action here + # define your other role action here ``` -## Template string +### Template String + +* Templating will activate in all `path`, `variable name`, and `entry name` fields. -* The template string is a string with the format `{{...}}`. The content in the `{{...}}` will be replaced by the dynamic values. Currently, we support two dynamic values: `task_id` and `user_id` (refer to [rust sdk](https://github.com/CoLearn-Dev/colink-sdk-rust-dev)). +* The template string is a string with the format `{{...}}`. The content in the `{{...}}` will be replaced by the dynamic values. Currently, we support two dynamic values: `task_id` and `user_id` (refer to the [Rust SDK](https://github.com/CoLearn-Dev/colink-sdk-rust-dev)). -* templating will activate in all `path`, `variable name` and `entry name` fields. -* templating supports the rust-style slices. - * format example: +* Templating supports the Rust-style slices. + * Format example: ``` "{{task_id}}" @@ -75,23 +78,25 @@ You can define your protocol like this: (you need to replace all the field as `< "{{task_id[2..5]}}" ``` - the slices will be `[a,b)` for `{{task_id[a..b]}}` + The slices will be `[a,b)` for `{{task_id[a..b]}}` -## Supported action +### Supported Action -* run action with condition +* Run action with condition - you can use this statement to add a run condition for any step + You can use this statement to add a run condition for any step ```toml - if = "a bash command" # example: `grep -q '0' xx.txt` + [[xxx.steps]] + if = "a bash command" # example: `grep -q '0' xx.txt` + # other steps ``` - this action will run the bash command and get its exit code. If return `0`, will run this step, otherwise, this step will be skipped. + This action will run the bash command and get its exit code. If it returns `0`, the step will run, otherwise, this step will be skipped. -* sub-process +* Sub-process - * start the sub-process: + * Start the sub-process: ```toml [[xxx.steps]] @@ -99,7 +104,7 @@ You can define your protocol like this: (you need to replace all the field as `< process = "your command here" ``` - * force kill the sub-process + * Force kill the sub-process ```toml [[xxx.steps]] @@ -110,7 +115,7 @@ You can define your protocol like this: (you need to replace all the field as `< check_exit_code = # [optional] set this field to check the exit code of process (notice that if this process is killed, the exit code is 9) ``` - * join the sub-process + * Join the sub-process ```toml [[xxx.steps]] @@ -121,13 +126,13 @@ You can define your protocol like this: (you need to replace all the field as `< check_exit_code = # [optional] set this field to check the exit code of process ``` - * other supported format + * Other supported format ```toml [[xxx.steps]] step_name = "your sub-process name" process = "your command here" - process_wait = "sub-process name of the one to join" # can also be replace with `process_kill` + process_wait = "sub-process name of the one to join" # can also be replaced with `process_kill` stdout_file = "your file name" stderr_file = "your file name" exit_code = "your file name" @@ -137,12 +142,12 @@ You can define your protocol like this: (you need to replace all the field as `< * Notes: * `step_name` **cannot** start with `__` - * Besides the existing env variables, the subprocess will also get `COLINK_CORE_ADDR` and `COLINK_JWT` , which stand for the *server address* and *user jwt*. + * Besides the existing env variables, we will set two new variables named `COLINK_CORE_ADDR` and `COLINK_JWT` in the process, which stand for the *server address* and *user jwt*. * If the exit code subprocess is not `0` (or not `9` after calling the *kill* action), the `wait` and `kill` action will throw an exception. -* variable transfer through CoLink +* Variable Transfer through CoLink - * send variable + * Send variable ```toml [[xxx.steps]] @@ -152,9 +157,9 @@ You can define your protocol like this: (you need to replace all the field as `< index = 0 # [optional] not set for all ones ``` - * receive variable + * Receive variable - this action will block the action until receiving the required variable + This action will block the action until receiving the required variable ```toml [[xxx.steps]] @@ -164,9 +169,9 @@ You can define your protocol like this: (you need to replace all the field as `< index = 0 # [necessary] the index of the roles matched in participants ``` -* entry actions of CoLink +* Entry Actions of CoLink - * create entry + * Create entry ```toml [[xxx.steps]] @@ -174,7 +179,7 @@ You can define your protocol like this: (you need to replace all the field as `< file = "file of the content of entry" ``` - * update entry + * Update entry ```toml [[xxx.steps]] @@ -182,7 +187,7 @@ You can define your protocol like this: (you need to replace all the field as `< file = "file of the content of entry" ``` - * read entry + * Read entry ```toml [[xxx.steps]] @@ -190,14 +195,14 @@ You can define your protocol like this: (you need to replace all the field as `< file = "file to store the content of entry" ``` - * delete entry + * Delete entry ```toml [[xxx.steps]] delete_entry = "name of the entry to delete" ``` - * read_or_wait entry + * Read or Wait Entry ```toml [[xxx.steps]] @@ -207,5 +212,4 @@ You can define your protocol like this: (you need to replace all the field as `< ## Example -* There is an example that uses `playbook` to run `unifed-fedtree`, you can find it [here](https://github.com/walotta/colink-unifed-fedtree-playbook). - +* An example that uses `playbook` to run `unifed-fedtree` can be found [here](https://github.com/walotta/colink-unifed-fedtree-playbook). \ No newline at end of file