Skip to content

Commit 7047e3d

Browse files
dzhou121dzhou121
committedApr 17, 2024·
update docs
1 parent 21623a8 commit 7047e3d

File tree

10 files changed

+580
-236
lines changed

10 files changed

+580
-236
lines changed
 

‎README.md

+1
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@
2929
* **TUI:** Tiron has a built in terminal user interfaces to display the outputs of the running tasks.
3030
* **Correctness:** Tiron pre validates all the runbook files and will throw errors before the task is started to execute.
3131
* **Speed:** On validating all the input, Tiron also pre populates all the data for tasks, and send them to the remote machines in one go to save the roundtrips between the client and remote.
32+
* **LSP:** Tiron provides a LSP server which can provide syntax highlighting, linting, formatting, code jumps, completion etc.
3233

3334
## Quickstart
3435

‎docs/content/docs/_index.md

+1-6
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,5 @@
22
title = "docs"
33
template = "docs/page.html"
44
sort_by = "weight"
5+
redirect_to = "docs/getting-started/"
56
+++
6-
7-
Getting started
8-
- Installation
9-
- CLI usage
10-
- Directory structure
11-
- config.toml

‎docs/content/docs/getting-started/_index.md

+2-6
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,6 @@
22
title = "Getting Started"
33
sort_by = "weight"
44
weight = 1
5+
template = "docs/page.html"
6+
redirect_to = "docs/getting-started/overview/"
57
+++
6-
7-
Getting started
8-
- Installation
9-
- CLI usage
10-
- Directory structure
11-
- config.toml

‎docs/content/docs/getting-started/overview.md

+210
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,213 @@ Run below to install latest Tiron binary to ```/usr/local/bin```
1212
curl -sL https://tiron.run/install.sh | sh
1313
```
1414

15+
### Usage
16+
17+
To run a Tiron runbook
18+
19+
```bash
20+
$ tiron run
21+
```
22+
23+
It will run `main.tr` in the current directory.
24+
You can also give a path of the runbook you want to run.
25+
26+
```bash
27+
$ tiron run folder/subfolder/production.tr
28+
```
29+
30+
You can also pre validates the runbook without actually running it by using `check`
31+
which takes the same input as `run`
32+
33+
```bash
34+
$ tiron check
35+
```
36+
37+
### Runbook
38+
39+
The center of Tiron is a runbook. A runbook is a set of settings and actions
40+
for Tiron to know what and how to run things on your remote machines.
41+
42+
#### HCL
43+
44+
For Tiron runbook, we use [HCL](https://github.com/hashicorp/hcl) as the configuration
45+
language.
46+
47+
### Simple Runbook Example
48+
49+
We'll start with a very simple runbook for you to get familiar with the concepts
50+
of Tiron runbooks.
51+
52+
#### group
53+
54+
Before everything, we need to know what remote machines to run actions on, and that's
55+
the `group` block in Tiron. E.g. you want to have a "webservers" group with remote machines
56+
"web1", "web2", and "web3", you'll define it as follows:
57+
58+
```tcl
59+
group "webservers" {
60+
host "web1" {}
61+
host "web2" {}
62+
host "web3" {}
63+
}
64+
```
65+
66+
A group can contain host and other groups at the same time:
67+
68+
```tcl
69+
group "production" {
70+
group "webservers" {}
71+
host "db1" {}
72+
}
73+
```
74+
75+
You can define variables in group or host level
76+
77+
```tcl
78+
group "production" {
79+
group "webservers" {
80+
group_var = "webservers_group_var"
81+
}
82+
host "db1" {
83+
host_var = "host_var"
84+
}
85+
group_production_var = "group_production_var"
86+
}
87+
```
88+
89+
#### run
90+
91+
Now we know what remote machines we'll use,
92+
we can start to run things on them. To do that,
93+
you simply have a `run` block on a `group` you defined earlier:
94+
95+
```tcl
96+
run "production" {
97+
}
98+
```
99+
100+
For things we want to run the remote machines, we call it `action` in Tiron.
101+
And the following run a "copy" `action` which copies `src_file` from local
102+
to `/tmp/dest_path` on the remote machines.
103+
104+
```tcl
105+
run "production" {
106+
action "copy" {
107+
params {
108+
src = "src_file"
109+
dest = "/tmp/dest_path"
110+
}
111+
}
112+
}
113+
```
114+
115+
You can have as many as actions you want in a `run`
116+
117+
```tcl
118+
run "production" {
119+
action "action1" {}
120+
action "action2" {}
121+
action "action1" {}
122+
}
123+
```
124+
125+
#### job
126+
127+
You might have a set of actions you want to reuse in different runs.
128+
`job` would be useful here. A job is defined as a set of actions
129+
that you can use in a `run`. To define a job, you give it a name
130+
and the set of actions it contains. And you can also include another job in a job.
131+
132+
```tcl
133+
job "job1" {
134+
action "action1" {}
135+
action "action2" {}
136+
}
137+
138+
job "job2" {
139+
action "action1" {}
140+
action "action2" {}
141+
action "job" {
142+
params {
143+
name = "job1"
144+
}
145+
}
146+
}
147+
```
148+
149+
Now you can use `job` in your `run`
150+
151+
```tcl
152+
run "production" {
153+
action "action1" {}
154+
action "action2" {}
155+
action "action1" {}
156+
action "job" {
157+
params {
158+
name = "job2"
159+
}
160+
}
161+
}
162+
```
163+
164+
#### use
165+
166+
You might want to use a `group` or `job` from another runbook. And `use` can be used to
167+
import them.
168+
169+
```tcl
170+
use "folder/another_runbook.tr" {
171+
job "job1" {}
172+
group "group1" {}
173+
}
174+
```
175+
176+
You can use `as` to bind the imports to a different name. It would be useful if
177+
you have defined a job or group in your runbook with the same name.
178+
179+
```tcl
180+
use "folder/another_runbook.tr" {
181+
job "job1" {
182+
as = "another_job_name"
183+
}
184+
group "group1" {
185+
as = "another_group_name"
186+
}
187+
}
188+
189+
group "group1" {
190+
host "machine1" {}
191+
}
192+
193+
job "job1" {
194+
action "action1" {}
195+
action "action2" {}
196+
}
197+
198+
run "group1" {
199+
action "job" {
200+
params {
201+
name = "another_job_name"
202+
}
203+
}
204+
}
205+
206+
run "another_group_name" {
207+
action "job" {
208+
params {
209+
name = "job1"
210+
}
211+
}
212+
}
213+
```
214+
215+
These are pretty much all the components in Tiron for you to write your runbooks.
216+
The next thing you'll want to check out is the list of `action` we include in Tiron.
217+
You can view the action docs [here](/docs/actions/command/) or via the tiron command in the console
218+
219+
```bash
220+
$ tiron action
221+
$ tiron action copy
222+
```
223+
224+
There's also some example runbooks at [https://github.com/lapce/tiron/blob/main/examples/example_tiron_project](https://github.com/lapce/tiron/blob/main/examples/example_tiron_project)

0 commit comments

Comments
 (0)
Please sign in to comment.