doc: updating README.md and start writing wingmate.yaml.md

README.md

@@ -50,17 +50,32 @@ You can find some examples for shell script in [alpine docker](docker/alpine) an
 
 When `wingmate` binary starts, it will look for some files. By default, it will
 try to read the content of `/etc/wingmate` directory. You can change the directory
-where it reads by setting `WINGMATE_CONFIG_PATH` environment variable. The structure
+where it reads by setting `WINGMATE_CONFIG_PATH` environment variable. Wingmate supports 
-inside the config path should look like this.
+two format of configurations: yaml and shell script.
 
+### YAML configuration
+
+File structure:
+```shell
+/etc
+ └── wingmate
+     └── wingmate.yaml
+```
+Wingmate will parse the `wingmate.yaml` file and start services and crones based on the content
+of the yaml file. Please read [wingmate.yaml.md](wingmate.yaml.md) for details on
+the structure of yaml configuration file and some examples.
+
+### Shell script configuration
+
+Files and directories structure:
 ```shell
 /etc
  └── wingmate
      ├── crontab
      ├── crontab.d
-     │   ├── cron1.sh
+     │   ├── cron1.sh
-     │   ├── cron2.sh
+     │   ├── cron2.sh
-     │   └── cron3.sh
+     │   └── cron3.sh
      └── service
          ├── one.sh
          └── spawner.sh
@@ -85,10 +100,13 @@ common UNIX crontab file format. Something like this
  * * * * * <commad or shell script or binary>
 ```
 
-The command part only support simple command and arguments. Shell expression is not supported
+The command part only support simple command and arguments. Shell expression is not supported.
-yet. It is recommended to write a shell script and put the path to shell script in
+It is recommended to write a shell script and put the path to shell script in
 the command part.
 
+**Note: It is recommended to use the yaml format instead of shell script. In order to avoid less
+obvious mistake when writing shell script.**
+
 # Appendix
 ## Wingmate PID Proxy binary
 

wingmate.yaml.md

@@ -0,0 +1,155 @@
+YAML Configuration
+---
+
+Table of content
+- [Service](#service)
+  - [Command](#command)
+  - [Environ](#environ)
+  - [User](#user-and-group)
+  - [Working Directory](#working-directory)
+  - [setsid](#setsid)
+  - [PID File](#pid-file)
+- [Cron](#cron)
+  - [Schedule](#schedule)
+
+Example
+```yaml
+service:
+  spawner:
+    command: [ wmspawner ]
+    user: "1200"
+    working_dir: "/var/run/test"
+
+  bgtest:
+    command:
+      - "wmstarter"
+      - "--no-wait"
+      - "--"
+      - "wmexec"
+      - "--setsid"
+      - "--"
+      - "wmbg"
+      - "--name"
+      - "test-run"
+      - "--pause"
+      - "10"
+      - "--log-path"
+      - "/var/log/wmbg.log"
+      - "--pid-file"
+      - "/var/run/wmbg.pid"
+    pidfile: "/var/run/wmbg.pid"
+
+cron:
+  cron1:
+    command: ["wmoneshot", "--", "sleep", "5"]
+    schedule: "*/5 * * * *"
+    working_dir: "/var/run/cron"
+    environ:
+      - "WINGMATE_LOG=/var/log/cron1.log"
+      - "WINGMATE_LOG_MESSAGE=cron executed in minute 5,10,15,20,25,30,35,40,45,50,55"
+  cron2:
+    command: ["wmoneshot", "--", "sleep", "5"]
+    schedule: "17,42 */2 * * *"
+    environ:
+      - "WINGMATE_LOG=/var/log/cron2.log"
+      - "WINGMATE_LOG_MESSAGE=cron scheduled using 17,42 */2 * * *"
+  cron3:
+    command:
+      - "wmoneshot"
+      - "--"
+      - "sleep"
+      - "5"
+    schedule: "7,19,23,47 22 * * *"
+    environ:
+      - "WINGMATE_LOG=/var/log/cron3.log"
+      - "WINGMATE_LOG_MESSAGE=cron scheduled using 7,19,23,47 22 * * *"
+
+```
+
+At the top-level, there are two possible entries: Service and Cron.
+
+## Service
+
+`service` is a top-level element that hosts the declaration of services to be started by `wingmate`.
+
+Example
+```yaml
+service:
+  svc1:
+    command: [ some_executable ]
+    user: "1200"
+    working_dir: "/var/run/test"
+```
+
+In the example above, we declare a service called `svc1`. `wingmate` will start a process based on all
+elements defined under `svc1`. To learn more about elements for a service, read below.
+
+### Command
+
+`command` element is an array of strings consists of an executable name (optionally with path) and
+its arguments (if any). `wingmate` will start the service as its child process by executing
+the executable with its arguments.
+
+Example
+
+```yaml
+command: [ executable1, argument1, argument2 ]
+```
+
+Based on YAML standard, the above example can also be written like
+
+```yaml
+command:
+  - executable1
+  - argument1
+  - argument2
+```
+
+### Environ
+
+`environ` element is an array of strings. It is a list of environment variables `wingmate` will pass to
+the child process or service. The format of each environment variable is a pair of key and value separated
+by `=` sign. By default, the child process or service will inherit all environment variables of its parent.
+
+Example
+
+```yaml
+environ:
+  - "S3_BUCKET=YOURS3BUCKET"
+  - "SECRET_KEY=YOUR_SECRET_KEY"
+```
+
+Note: don't worry if an environment variable value has one or more `=` character(s) in it. `wingmate` will
+separate key and value using the first `=` character only.
+
+### Working Directory
+
+`working_dir` is a string contains the path where the child process will be running in. By default, the child
+process will run in the `wingmate` current directory.
+
+### User and Group
+
+Both `user` and `group` take string value. `user` and `group` refer to the operating system's user and group.
+They can be in the form of name, like username or groupname, or in the form of id, like uid or gid.
+If they are set, the child process will run as the specified user and group. By default, the child process
+will run as the same user and group as the `wingmate` process. The `user` and `group` are only effective
+when the `wingmate` running as privileged user, such as `root`. The `user` and `group` configuration depends
+on the [wmexec](README.md#wingmate-exec-binary).
+
+### setsid
+
+`setsid` takes a boolean value, `true` or `false`. This feature is operating system dependant. If set to `true`,
+the child process will run in a new session. Read `man setsid` on Linux/UNIX. The `setsid` configuration depends
+on the [wmexec](README.md#wingmate-exec-binary).
+
+### PID File
+
+This feature is designated to handle service that run in the background. This kind of service usually forks a
+new process, terminate the parent process, and continue running in the background child process. It writes its
+background process PID in a file. This file is referred as PID file. Put the path of the PID file to this
+`pidfile` element. It will help `wingmate` to restart the service if its process exited / terminated. The `pidfile`
+configuration depends on the [wmpidproxy](README.md#wingmate-pid-proxy-binary).
+
+## Cron
+
+### Schedule