Skip to content

Commit 420aaef

Browse files
zphzph
committed
Update README
1 parent b8541c5 commit 420aaef

File tree

4 files changed

+142
-64
lines changed

4 files changed

+142
-64
lines changed

‎.config/README.md.template

Lines changed: 70 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -2,48 +2,88 @@
22

33
## Summary
44

5-
Runbook is a commandline tool that guides users in an opinionated approach to creating dynamic runbooks.
5+
Runbook is a powerful CLI tool that transforms your operational procedures into interactive, executable notebooks. It combines the best of documentation and automation by letting you create dynamic runbooks using Markdown, Deno, or Python.
66

7-
In this context, a runbook is a mixture of markdown and executable code that contains the steps needed for successful operational executions such as server maintenance, database management, or creating a weekly report.
7+
Think of it as "infrastructure as code" meets "documentation as code" - perfect for DevOps teams who want both flexibility and reliability.
88

9-
### When would you use this?
10-
1. When you want quick to write tools that can't be entirely automated, but want the safey of auditable tools.
11-
2. When your tooling needs to adjust rapidly and contain prepared rollback procedures.
12-
3. When this is a semi-custom situation that doesn't warrant building dedicated and expensive tooling
13-
4. When you've grown out of shell scripts but aren't ready to build it in Golang or Rust
9+
**At work, it empowered us to move 300 Mysql Clusters to TiDB with a small team [recording](https://www.youtube.com/watch?app=desktop&v=-_JoqZthrI8) over the course of 18 months.**
10+
11+
# Quick Start
12+
13+
```sh
14+
uv tool install git+https://github.com/zph/runbook.git@$RUNBOOK_VERSION
15+
16+
# Initialize a new runbook project in a repo of your choosing
17+
runbook init
18+
19+
# Create a new runbook
20+
runbook create -l deno runbook-name.ipynb
21+
22+
# Edit the runbook
23+
runbook edit runbook-name.ipynb
24+
25+
# Plan the runbook
26+
runbook plan runbook-name.ipynb --embed file.json --parameters '{"arg": 1, "foo": "baz"}'
27+
28+
# Run the runbook
29+
runbook run runbook-name.ipynb
30+
```
31+
32+
# Background
33+
34+
### What is a Runbook?
35+
A runbook is an executable document that combines:
36+
- Clear markdown documentation
37+
- Runnable code blocks
38+
- Parameterized inputs for reusability
39+
- Built-in safety checks
40+
41+
It's ideal for operations like encoding your Disaster Recovery Operations, spinning up a new cluster, or restoring from snapshots.
42+
43+
### When Should You Use This?
44+
- ✅ When you need **semi-automated tools** with audit trails and safety checks
45+
- ✅ When you want **rapid iteration** on operational procedures with built-in rollback steps
46+
- ✅ When you need something more powerful than shell scripts but don't want to build a full application
47+
- ✅ When you want to make complex operations both **safe and repeatable**
1448

1549
### Runbook Best Practices
16-
1. Include a Summary/Purpose, Step descriptions, Warning signs, Verification Steps and Execution Steps in their natural order
17-
2. Non-mutative actions can be included anyhere
18-
3. Mutative actions (destroy a server or force a failover) must use the `confirm` flag
19-
4. Write pre-check steps before mutation steps in order to increase safety of the procedure
20-
5. Runbooks for critical operations should be run by pairs of staff members
21-
1. One to execute the book
22-
2. A second to validate and perform safety checks
50+
1. Structure your runbooks with:
51+
- Clear purpose and summary
52+
- Step-by-step descriptions
53+
- Warning signs and precautions
54+
- Verification steps
55+
- Execution steps in logical order
56+
- Rollback and cleanup steps
57+
2. Keep read-only operations flexible
58+
3. Require explicit confirmation for destructive actions using the `confirm` flag
59+
4. Include pre-flight checks before any system modifications
60+
5. For critical operations, use pair execution:
61+
- One person to run the procedure
62+
- Another to verify and validate safety checks
2363

2464
## Workflow
2565

2666
1. Initialize a new folder project with `runbook init...`
2767
1. Create a new runbook with `runbook create -l deno runbook-name.ipynb`
68+
1. Edit the runbook with `runbook edit runbook-name.ipynb` (or using editor of choice) and add your title, description, steps
69+
1. For complex runbooks, offload the coding details into an SDK that you build beside the runbooks that can be reused across multiple runbooks
2870
1. Plan that runbook for a specific run `runbook plan runbook-name.ipynb --embed file.json --parameters '{"arg": 1, "foo": "baz"}'
29-
1. Run the instance of a runbook with either `runbook run runbook-name.ipynb` or use VSCode to run it `code runbooks/run/runbook-name.ipynb`
71+
1. Run the instance of a runbook with either `runbook run runbook-name.ipynb` or use VSCode to run it `code runbooks/runs/runbook-name.ipynb`
72+
1. Depending on auditing needs, you can either commit the "runs" folder to your repo or only keep the "binder" folder committed.
73+
1. In case of strict auditing needs, we recommend you add auditing of commands in the local SDK as well as in your cloud provider
3074

3175
## Installation
3276

33-
We recommend using [uv](https://docs.astral.sh/uv/) or [pipx](https://pypi.org/project/pipx/) for installing runbook as a cli tool.
77+
We recommend using [uv](https://docs.astral.sh/uv/) for installing runbook as a cli tool. If you already use pipx, you can use that instead.
3478

3579
```sh
3680
uv tool install git+https://github.com/zph/runbook.git
37-
# or
38-
pipx install git+https://github.com/zph/runbook.git
3981
```
4082

4183
Or pin to a version
4284

4385
```sh
44-
uv tool install git+https://github.com/zph/runbook.git@v0.0.1
45-
46-
pipx install git+https://github.com/zph/runbook.git@v0.0.1
86+
uv tool install git+https://github.com/zph/runbook.git@$RUNBOOK_VERSION
4787
```
4888

4989
## CLI
@@ -72,31 +112,29 @@ For advanced completion setup see [docs](https://click.palletsprojects.com/en/8.
72112

73113
# Principles
74114

75-
- Prefer deno for better package management and developer ergonomics
115+
- Prefer deno for better package management and developer ergonomics with typing
76116
- But allow for other kernels (python) as secondary option, via compatible libraries
77117
- Make `runbook` batteries included for interfacing with shell commands and common runbook
78-
operations (ie grafana and notifications)
79-
- Sets up necessary requirements to ensure cell executions are timed and displayed as
80-
long as executions run through `runbook run ...` command
118+
operations
81119

82120
# Caveats
83121

84122
1. Running notebook in VScode does not set the timings necessary in notebook for being auditable and exported later
85123
1. Recommendation: if auditable runs are needed, use jupyter via browser `runbook run TITLE`
86124
1. Notebooks have different structured ids per cell depending on run environment
87125
1. Recommendation: if requiring consistency, write your own pre-processor to standardize on an id format
88-
1. Builting shell package requires a shell environment and is only expected to run on Linux or Mac not Windows.
89-
1. Recommendation: suggest fixes in PR or Issues on Github
126+
1. Built-in shell package requires a shell environment and is only expected to run on Linux or Mac not Windows.
127+
1. Recommendation: Windows support is out of scope for now but we'll review PRs
90128

91129
## Deno / Typescript
92-
1. Parameter cells should use `let` declarations to allow for param overriding
93-
- This is required to correctly support executing the ts version of notebooks.
130+
1. Parameter cells must use `let` declarations to allow for param overriding
131+
- `var` or `let` work in Deno notebooks but only `let` works if using `runbook convert a.ipynb a.ts` and running the ts version
94132

95133
# Developing runbook cli
96134

97-
We use [hermit](https://hermit.dev/) to manage developement dependencies.
98-
99-
Use [uv](https://docs.astral.sh/uv/) as the package manager/execution environment.
135+
For development we use the following tools:
136+
- [hermit](https://hermit.dev/) to manage developement tool dependencies (see .hermit/bin)
137+
- [uv](https://docs.astral.sh/uv/) python package manager and cli runner (see pyproject.toml)
100138

101139
Necessary deps can be seen in [pyproject.toml](pyproject.toml) and .hermit/bin
102140

‎.config/templating.sh

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,6 @@
33
set -eou pipefail
44

55
export RUNBOOK_HELP="$(runbook --help)"
6+
export RUNBOOK_VERSION="$(runbook version | grep -i version | awk '{print $3}')"
67

78
envsubst < ".config/README.md.template" > README.md

‎NOTES.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
- [ ] Use execute and upload output to S3 for non-interactive: https://github.com/nteract/papermill/tree/main?tab=readme-ov-file#execute-via-cli
1111

1212
## P0
13+
- [ ] Add `runbook init` suggestion or automation to add `export RUNBOOK_WORKING_DIR=...` to shell initializations
1314
- [ ] Install pre-commit.yml or git integration during `init` for secure linting and talisman
1415
- [x] Setup versioning and bumper (using versioner from npm ecosystem @release-it and @release-it/bumper)
1516
- [x] Fix tag key getting stripped out of planned runbooks b/c it breaks papermill

‎README.md

Lines changed: 70 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -2,48 +2,88 @@
22

33
## Summary
44

5-
Runbook is a commandline tool that guides users in an opinionated approach to creating dynamic runbooks.
5+
Runbook is a powerful CLI tool that transforms your operational procedures into interactive, executable notebooks. It combines the best of documentation and automation by letting you create dynamic runbooks using Markdown, Deno, or Python.
66

7-
In this context, a runbook is a mixture of markdown and executable code that contains the steps needed for successful operational executions such as server maintenance, database management, or creating a weekly report.
7+
Think of it as "infrastructure as code" meets "documentation as code" - perfect for DevOps teams who want both flexibility and reliability.
88

9-
### When would you use this?
10-
1. When you want quick to write tools that can't be entirely automated, but want the safey of auditable tools.
11-
2. When your tooling needs to adjust rapidly and contain prepared rollback procedures.
12-
3. When this is a semi-custom situation that doesn't warrant building dedicated and expensive tooling
13-
4. When you've grown out of shell scripts but aren't ready to build it in Golang or Rust
9+
**At work, it empowered us to move 300 Mysql Clusters to TiDB with a small team [recording](https://www.youtube.com/watch?app=desktop&v=-_JoqZthrI8) over the course of 18 months.**
10+
11+
# Quick Start
12+
13+
```sh
14+
uv tool install git+https://github.com/zph/runbook.git@1.0.0-rc2
15+
16+
# Initialize a new runbook project in a repo of your choosing
17+
runbook init
18+
19+
# Create a new runbook
20+
runbook create -l deno runbook-name.ipynb
21+
22+
# Edit the runbook
23+
runbook edit runbook-name.ipynb
24+
25+
# Plan the runbook
26+
runbook plan runbook-name.ipynb --embed file.json --parameters '{"arg": 1, "foo": "baz"}'
27+
28+
# Run the runbook
29+
runbook run runbook-name.ipynb
30+
```
31+
32+
# Background
33+
34+
### What is a Runbook?
35+
A runbook is an executable document that combines:
36+
- Clear markdown documentation
37+
- Runnable code blocks
38+
- Parameterized inputs for reusability
39+
- Built-in safety checks
40+
41+
It's ideal for operations like encoding your Disaster Recovery Operations, spinning up a new cluster, or restoring from snapshots.
42+
43+
### When Should You Use This?
44+
- ✅ When you need **semi-automated tools** with audit trails and safety checks
45+
- ✅ When you want **rapid iteration** on operational procedures with built-in rollback steps
46+
- ✅ When you need something more powerful than shell scripts but don't want to build a full application
47+
- ✅ When you want to make complex operations both **safe and repeatable**
1448

1549
### Runbook Best Practices
16-
1. Include a Summary/Purpose, Step descriptions, Warning signs, Verification Steps and Execution Steps in their natural order
17-
2. Non-mutative actions can be included anyhere
18-
3. Mutative actions (destroy a server or force a failover) must use the `confirm` flag
19-
4. Write pre-check steps before mutation steps in order to increase safety of the procedure
20-
5. Runbooks for critical operations should be run by pairs of staff members
21-
1. One to execute the book
22-
2. A second to validate and perform safety checks
50+
1. Structure your runbooks with:
51+
- Clear purpose and summary
52+
- Step-by-step descriptions
53+
- Warning signs and precautions
54+
- Verification steps
55+
- Execution steps in logical order
56+
- Rollback and cleanup steps
57+
2. Keep read-only operations flexible
58+
3. Require explicit confirmation for destructive actions using the `confirm` flag
59+
4. Include pre-flight checks before any system modifications
60+
5. For critical operations, use pair execution:
61+
- One person to run the procedure
62+
- Another to verify and validate safety checks
2363

2464
## Workflow
2565

2666
1. Initialize a new folder project with `runbook init...`
2767
1. Create a new runbook with `runbook create -l deno runbook-name.ipynb`
68+
1. Edit the runbook with `runbook edit runbook-name.ipynb` (or using editor of choice) and add your title, description, steps
69+
1. For complex runbooks, offload the coding details into an SDK that you build beside the runbooks that can be reused across multiple runbooks
2870
1. Plan that runbook for a specific run `runbook plan runbook-name.ipynb --embed file.json --parameters '{"arg": 1, "foo": "baz"}'
29-
1. Run the instance of a runbook with either `runbook run runbook-name.ipynb` or use VSCode to run it `code runbooks/run/runbook-name.ipynb`
71+
1. Run the instance of a runbook with either `runbook run runbook-name.ipynb` or use VSCode to run it `code runbooks/runs/runbook-name.ipynb`
72+
1. Depending on auditing needs, you can either commit the "runs" folder to your repo or only keep the "binder" folder committed.
73+
1. In case of strict auditing needs, we recommend you add auditing of commands in the local SDK as well as in your cloud provider
3074

3175
## Installation
3276

33-
We recommend using [uv](https://docs.astral.sh/uv/) or [pipx](https://pypi.org/project/pipx/) for installing runbook as a cli tool.
77+
We recommend using [uv](https://docs.astral.sh/uv/) for installing runbook as a cli tool. If you already use pipx, you can use that instead.
3478

3579
```sh
3680
uv tool install git+https://github.com/zph/runbook.git
37-
# or
38-
pipx install git+https://github.com/zph/runbook.git
3981
```
4082

4183
Or pin to a version
4284

4385
```sh
44-
uv tool install git+https://github.com/zph/runbook.git@v0.0.1
45-
46-
pipx install git+https://github.com/zph/runbook.git@v0.0.1
86+
uv tool install git+https://github.com/zph/runbook.git@1.0.0-rc2
4787
```
4888

4989
## CLI
@@ -92,31 +132,29 @@ For advanced completion setup see [docs](https://click.palletsprojects.com/en/8.
92132

93133
# Principles
94134

95-
- Prefer deno for better package management and developer ergonomics
135+
- Prefer deno for better package management and developer ergonomics with typing
96136
- But allow for other kernels (python) as secondary option, via compatible libraries
97137
- Make `runbook` batteries included for interfacing with shell commands and common runbook
98-
operations (ie grafana and notifications)
99-
- Sets up necessary requirements to ensure cell executions are timed and displayed as
100-
long as executions run through `runbook run ...` command
138+
operations
101139

102140
# Caveats
103141

104142
1. Running notebook in VScode does not set the timings necessary in notebook for being auditable and exported later
105143
1. Recommendation: if auditable runs are needed, use jupyter via browser `runbook run TITLE`
106144
1. Notebooks have different structured ids per cell depending on run environment
107145
1. Recommendation: if requiring consistency, write your own pre-processor to standardize on an id format
108-
1. Builting shell package requires a shell environment and is only expected to run on Linux or Mac not Windows.
109-
1. Recommendation: suggest fixes in PR or Issues on Github
146+
1. Built-in shell package requires a shell environment and is only expected to run on Linux or Mac not Windows.
147+
1. Recommendation: Windows support is out of scope for now but we'll review PRs
110148

111149
## Deno / Typescript
112-
1. Parameter cells should use `let` declarations to allow for param overriding
113-
- This is required to correctly support executing the ts version of notebooks.
150+
1. Parameter cells must use `let` declarations to allow for param overriding
151+
- `var` or `let` work in Deno notebooks but only `let` works if using `runbook convert a.ipynb a.ts` and running the ts version
114152

115153
# Developing runbook cli
116154

117-
We use [hermit](https://hermit.dev/) to manage developement dependencies.
118-
119-
Use [uv](https://docs.astral.sh/uv/) as the package manager/execution environment.
155+
For development we use the following tools:
156+
- [hermit](https://hermit.dev/) to manage developement tool dependencies (see .hermit/bin)
157+
- [uv](https://docs.astral.sh/uv/) python package manager and cli runner (see pyproject.toml)
120158

121159
Necessary deps can be seen in [pyproject.toml](pyproject.toml) and .hermit/bin
122160

0 commit comments

Comments
 (0)