6 ms·
Runme – Interactive Runbooks Built with Markdown
- lowbloodsugar 3y agoHow is this better than actual Jupiter?
- theossuary 3y agoI wouldn't squirrel my documentation away in an ipynb file. So even though I'd like to use notebooks as runbooks, Jupyter just isn't the right solution for that. This could be a great tool for when you want to augment markdown documentation with runnable snippets. I really like this idea, it gives off literate programming[0] vibes. [0]: http://literateprogramming.com/ http://literateprogramming.com/
- joncp 3y agoAnother is that it looks like runme is written in Go instead of python. It's a single executable I can drop onto any new machine instead of futzing around getting a particular python version installed before doing any work.
- admc 3y agoI'm on the Runme team, and one of the goals of the primary goals of runme is to use a shared markdown parsing engine so that there is consistent behavior between CLI/GH Action and the VS Code Notebook.
- admc 3y agoYou nailed it, thanks for calling that connection out. We were very much inspired by literate programming.
- enriquto 3y ago> I wouldn't squirrel my documentation away in an ipynb file. This! ipynb files are a nightmare to deal with. Fortunately, you can use jupyter without ever seeing a .ipynb file, by storing your notebooks in a different format (e.g. as programs or as markdown files). Bonus points: you'll hear fewer complains from your local graybeards if they can edit and run notebooks from their favorite text editor.
- admc 3y agoThere are actually many differences. We focus more on operational tasks, and allow cells to contain code from a number of programming languages in addition to python. In fact most folks are using Runme to make executing runbooks full of bash commands a better experience.
- lowbloodsugar 3y agoOk, so from the front page I got the impression it was only bash. I'm hitting cloud APIs via python so Jupyter works for that, and I'm using the python to ssh into systems and run bash there. The two missing things from Jupyter are 1. ssh-ing to remote hosts and running shell scripts (we do it with a bunch of code) and 2. running cells concurrently. But python is a hard requirement.
- admc 3y agoI've just added the currently supported languages you can execute to runme.dev in the features section (Javascript, Typescript, Shell, Lua, Perl, Python and Ruby for now). Also, the Runme CLI (https://github.com/stateful/runme https://github.com/stateful/runme) also supports running cells in parallel with `runme run -all -p`. We'd be interested to know how we can help Runme satisfy your use cases, join us on Discord! https://discord.gg/runme https://discord.gg/runme
- mst 3y agoI wonder if you'd get some mileage from my https://p3rl.org/Object::Remote https://p3rl.org/Object::Remote module (or at least stealing the ideas therein ;) - it effectively applies https://p3rl.org/App::FatPacker https://p3rl.org/App::FatPacker on-demand over the wire so the remote code can use any (pure perl) module you've got installed locally without needing to be able to write to the disk. (at https://shadow.cat/ https://shadow.cat/ we use it to investigate things on new customers' platforms with only an ssh login and a perl core install as requirements, along with as an ad-hoc "I need to run this on lots of machines without being intrusive" tool)
- sourishkrout 3y ago
- IggleSniggle 3y agoI made a VSCode extension to do this but never published it. All it required was that md code snippets had a language annotation/label, and that you either had a default interpreter pre-installed or could configure an interpreter. I still have no clue why I did it NOR why I never published it.
- admc 3y agoJoin us, come hack on Runme - it's OSS and we are always looking for more contributors: https://github.com/stateful/runme https://github.com/stateful/runme
- codeonline 3y agoI like the idea of this conceptually but it feels that I could do all this with github actions. Is it the interactivity and ease of changing the script that is the selling point here?
- theCodeStig 3y agoYes, most likely. Many organisations are still tied to manual/semi-manual deployments due to company policy or regulatory compliance (banks for example).
- admc 3y agoWe've seen that it's not unusual in operations for folks to walk through runbooks running commands that require small (but important) amounts of human input. Runme makes that experience considerably better by utilizing the markdown that's already there and allowing for behavioral configuration (user prompts, process execution, language interpreter etc). But you can also name, and run groups of cells/commands to streamline your workflows.
- siliconc0w 3y agoMy company is investing heavily in interactive runbooks (their own impl) and while I kinda dislike the idea of runbooks in general this is a nice implementation. Interactive Runbooks exist in some sort of tech-debt limbo where you have enough time to write a nice little runbook but apparently not enough time to properly automate whatever the task is. Ideally automation is easy and all change flows through a SDLC and you get all the nice things that come from that (testing for one). Instead companies build these cybernetic business processes via these adhoc notebooks to manually poke and prod production. This kinda made sense when they were these low-effort throw away things for rare events or short-term triage but now they're kinda-sorta code but without tests or reusability (or maybe you even further down the crazy well and write libraries and tests for your notebooks at which point you're really investing in the cybernetic operational model, and like, why?).
- number6 3y agoWouldn't Ansible be the better runbook then?
- vladsanchez 3y agoI thought the same but about leaving Ansible for Runme. Not sure it's a wise idea but I like Runme DX/UX.
- vineyardmike 3y ago> Interactive Runbooks exist in some sort of tech-debt limbo where you have enough time to write a nice little runbook but apparently not enough time to properly automate whatever the task is I think this is a really common place to fall into. Automating 100% of conditions is hard, but having a google-doc full of bash commands is kinda meh. One of my previous teams decided on a "Maintainer Lambda" which would help with some tasks we couldn't automate fully. The Lambda could either make an action (trigger a db backup, trigger a bounce, etc) or it could perform some query (find FQDN hostname of server where ${INPUT} metric is in alarm). It'd help with calling complex APIs (eg. AWS APIs) repeatably, and testable, and it'd handle any permissions and input validations. The Lambda had unit testing, and it could run automatically under certain limited conditions. Over time, we've added to it, and let it handle more tasks, as long as it'd log it's actions in a ticket (eg. drain server, then auto-bounce on mem-full alarm). We'd embed cURL scripts into the runback doc, to trigger the functions manually. But the biggest win was whenever we got an automated ticket, for things like alarming metrics, it'd auto-run and parse the ticket, spitting out useful commands into the comments that the on-call could run (eg. copy+paste'able SSH-to-host commands based on which server triggered alarm). It's basically a reverse-run book. Instead of looking up what to do, we let the ticket tell us what to do, then slowly automate those steps.
- theCodeStig 3y agoIt's like a specialised case of org-babel for the masses. Anyone with emacs can do this today, for free. The huge caveat is that it requires emacs. Where this tool shines, is that it's a superset of markdown, and thus not tied to any particular editor.
- pxc 3y agoI haven't played with any of the alternative/independent implementations of Org mode but there are several out there¹. It would be cool to use one as the basis for a tool like Runme, or a collection of plugins for other editors. -- 1: https://orgmode.org/worg/org-tools/index.html https://orgmode.org/worg/org-tools/index.html
- pxc 3y agoGNU Emacs has this feature built-in as part¹ of Org mode². I have recently started using it at work, including extracting shell snippets into script files³ that are tested and reused in CI. A frontend like this would be nice for bringing the interactivity to users of other editors! -- 1: https://orgmode.org/worg/org-contrib/babel/ https://orgmode.org/worg/org-contrib/babel/ 2: https://orgmode.org/ https://orgmode.org/ 3: https://orgmode.org/manual/Extracting-Source-Code.html https://orgmode.org/manual/Extracting-Source-Code.html
- edublancas 3y agoFor those who don't know, Jupyter has a bash kernel: https://github.com/takluyver/bash_kernel https://github.com/takluyver/bash_kernel And you can run Jupyter notebooks from the CLI with Ploomber: https://github.com/ploomber/ploomber https://github.com/ploomber/ploomber
- woleium 3y agoThis is a good solution
- admc 3y agoVery cool, thanks for calling that out, we are big fans of Jupyter!
- enriquto 3y agoAlso, often you don't need to save your Jupyter notebook in the unergonomical json format; instead save it as a script containing your code cells (and the markdown cells as comments). Thus you can run it directly from the command line in whatever language your notebook is, python, bash... To save notebooks as plain text files you pip install jupytext, and it magically works: jupyter will interpret your .py files as notebooks, and so on.
- mdaniel 3y agoThat's how GitLab thinks about that problem, too: https://docs.gitlab.com/ee/user/project/clusters/runbooks/#executable-runbooks https://docs.gitlab.com/ee/user/project/clusters/runbooks/#e... > The JupyterHub app offered via the GitLab Kubernetes integration now ships with Nurtch’s Rubix library, providing a simple way to create DevOps runbooks although this is another case of the "don't use the word 'simple' in your description unless it actually is"
- perpil 3y agoIf you like this, you may also like Speedrun. It's markdown to build tools straight into your GitHub README's, wikis and documentation so you users can do what they came to do with a click. https://speedrun.nobackspacecrew.com https://speedrun.nobackspacecrew.com
- dharmatech 3y agoSee also, executable-tutorials: https://github.com/dharmatech/executable-tutorials/blob/main/executable-tutorials.org https://github.com/dharmatech/executable-tutorials/blob/main...
- VectorLock 3y agoSeems like a pretty good idea for a simple project, but when wrapped in yet another fly by night SaaS venture I think I'll pass.
- kitd 3y agoNice! Xc is another doing a similar job https://xcfile.dev/ https://xcfile.dev/
- grozmovoi 3y agoWhile in principle I agree with the usefulness of this approach I wonder about how actually it benefits orgs and projects. Seems to me that the fact that there exist extensive runbooks that are maintained separately from the scripts of the project that either duplicate actions between them or those just only exist in runbooks are massive smells.
- raskelll 3y agoThis looks very similar to LiveBook¹. It is purely Elixir/BEAM based, but is quite polished and seems like a perfect workflow tool that is also able to expose these workflows (simply called livebooks) as web apps that some functional, non-technical person can execute on his/her own. 1: https://livebook.dev/ https://livebook.dev/
- lionkor 3y agoIs that video on the homepage a Fiverr gig?
- michaelsalim 3y agoHaha now that you mention it, sure does feel like it. I think the music plays a big part as to why
- sourishkrout 3y agoIt is not a fiverr video. Runme’s very own Lizz Parody wrote, recorded, and edited the video with input from the team. She did a fantastic job.
- jen20 3y agoThis reminds me of a less-refined version of Moment.dev [1]. [1]: https://www.moment.dev/ https://www.moment.dev/
- jrib 3y agoI keep trying to click the logo to play a video :)