doc: updating README.md and start writing wingmate.yaml.md
This commit is contained in:
parent
6092629cb4
commit
97d637ef2c
32
README.md
32
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
|
||||
inside the config path should look like this.
|
||||
where it reads by setting `WINGMATE_CONFIG_PATH` environment variable. Wingmate supports
|
||||
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
|
||||
│ ├── cron2.sh
|
||||
│ └── cron3.sh
|
||||
│ ├── cron1.sh
|
||||
│ ├── cron2.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
|
||||
yet. It is recommended to write a shell script and put the path to shell script in
|
||||
The command part only support simple command and arguments. Shell expression is not supported.
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
Loading…
Reference in New Issue