Show HN: Add live runnable code to your dev docs (usedevbook.com)
I'm Vasek, co-founder, and CEO of Devbook [0]. Devbook is an SDK that you add to your docs website and then every time a user visits your dev docs, we spin up a VM just for that user. The VM is ready in about 18-20 seconds. We haven't had enough time to work on optimization but from our early tests, we are fairly confident we can get this to about 1-2 seconds.
In the VM you can run almost anything. Install packages, edit & save files, run binaries, services, etc.
You as a documentation owner have full control over the VM. We give you full access to filesystem, shell, stdout, and stderr. You don't have to worry about any infrastructure management. It's just one line of code on your frontend.
On the backend, the VM is a Firecracker microVM [1] with our custom simple orchestrator/scheduler built on top that just gets the job done. We chose Firecracker for 4 reasons:
* (1) the security with a combination of their jailer
* (2) its snapshotting capabilities
* (3) quick booting times
* (4) option to oversubscribe the underlying server resources
This allows you to create a whole new set of interactions between your dev docs and a developer visiting the docs. We've had users building coding playgrounds [2] to show how their SDK works or adding embedded terminals to a landing page [3] to show how their CLI works.
The way Devbook works is that you use our frontend SDK [4] on our website. The SDK pings our backend and we boot up a VM. The VMs are ephemeral and get destroyed after a while of not getting pinged. You can predefine what the VM filesystem will look like through our CLI via a simple Dockerfile [5]. We also have an open sourced UI library for components like terminal, file system explorer, or code editor [6].
The need for Devbook came from our own frustration with dev docs. It has always felt strange that dev docs contain so much code but none of it is actually runnable. You as a developer have to set up full environments to see how the API works and get a deeper understanding.
We are very early so we don't offer self-serve for now. A bit of manual work is still required when we are onboarding new customers. We are looking for some specific use-case that would make our go-to-market strategy much easier. It feels like the product we offer is way too general. We basically say "here's a whole computer, have fun".
I'd love to know what you think about it. I'll hang out here and I'm happy to answer your questions!
[1] https://github.com/firecracker-microvm/firecracker
[2] https://app.banana.dev/docs/carrot?ref=navmenu
[4] https://github.com/devbookhq/sdk
32 comments
[ 3.2 ms ] story [ 76.6 ms ] threadi.e. spin up VMs for me when I go to any site, not just the sites which have chosen to use devbook.
I reckon that could make adoption a lot faster/easier and also it means the people/orgs directly receiving the value are the ones paying.
What do you think this "Devbook docs collection" should look like? Just sharing docs with live code snippets?
[0] https://github.com/devbookhq/ui
[1] https://runops.io/
> Can't you just run it in a container or WASM in the browser?
Great thing about VMs is the security, quick snapshotting, and resource oversubscription.
> WASM in the browser
I personally love WASM and am very excited about it. There are however a lot of use-cases where WASM doesn't cut it. Having full environments with a file system and being able to start any Linux binary is very useful. Especially when you want to show some real-life examples with your API.
>Having full environments with a file system and being able to start any Linux binary is very useful.
https://humphd.github.io/browser-shell/
That said, not practical if the OS image needs to be huge.
We have goals on our roadmap which will make the experience much better and near instant. The time and our execution will tell.
We currently extract all of our docs snippets at build time, run them, and most importantly put them through automated testing to make sure they never accidentally break. We then capture the output as static content for display. I would still want to do that, including capturing output so the results loads instantly with the page. But we have also wanted to add live editing as an enhancement.
We are having a bit of traffic on our shared server sorry about that one. The playground demo from Banana.dev should load in about 20 seconds [1].
The pricing is currently custom based on our customer needs.
I'd love to chat about your use-case if you are up to it, can you shoot me an email vasek at usedevbook.com?
[1] https://app.banana.dev/docs/carrot
[0]: https://beta.reactjs.org/learn
[1]: https://sandpack.codesandbox.io/
[2]: https://news.ycombinator.com/item?id=29417937
The dev docs future looks exciting!
Yes we like MDX and live code blocks to embed natively runnable code in your page.
I don't like the idea of loading a remote iframe much (at least for most cases using JS).
The StackBlitz / WebContainer approach also seems better than a remote VM + iframe
We'll likely use a project called React-Runner in the future, quite similar to our current setup (real native embed) but lighter.
> I guess a useful side effect of running this is that it will be super obvious when the docs contain broken code!
Yes! One of the things we've learned is that companies are building very complicated in-house systems to make sure their docs code snippets are runnable. With Devbook, you could just start a Devbook VM from you CI/CD pipeline and run all the code snippets in the same environment your users will get when they visit your docs.
> How are errors handled? Am I able to see errors that my customers raised while interacting with the docs?
That's what we are exploring right now. We are building a dashboard that would give you an overview of what is happening with your docs code snippets and give you better understanding if developers are struggling with your docs and API/SDK.
AWS Lambda worst performer (JVM) I think takes much less than that, like 5 seconds in cold start. You must be loading something really bulky at startup...
Why don't you offer warmed VMs? Like reserved concurrency in AWS Lambda. Preemptively increase the number of VMs (like an auto-scaler) as traffic increases.
We have a few unoptimized things happening on our infra in the moment. We are working on it to make it better and it will be better soon. Most likely around 1-2 seconds.
Once we had the early version ready, we started focusing on figuring out the business side of Devbook and iterating on the product. So certain things aren't as high priority right now but will be very high in the near future.
Declaring the code in the frontend and having the VM execute whatever comes from it is asking for serious abuse.
[1] https://github.com/devbookhq/devbookctl
[2] https://github.com/devbookhq/devbookctl/blob/master/example-...
Usually most of these tools seems to stick with the easy cases, POSIX CLI or Web.
And what to do about those darn crypto miners?