mirror of
https://github.com/livebook-dev/livebook.git
synced 2024-09-20 10:05:57 +08:00
Add documentation on use cases (#2567)
--------- Co-authored-by: Hugo Baraúna <hugo.barauna@gmail.com>
This commit is contained in:
parent
5e7f8a477a
commit
c1a913ae1c
94
docs/use_cases.md
Normal file
94
docs/use_cases.md
Normal file
|
@ -0,0 +1,94 @@
|
|||
# Use cases
|
||||
|
||||
There are many ways Elixir developers use and leverage Livebook today.
|
||||
|
||||
## Documentation with `Mix.install`
|
||||
|
||||
Livebook is an excellent tool for documentation. Many Elixir packages use
|
||||
Livebook as tutorials but you can also directly run Livebook within the context
|
||||
of your existing application with the help of `Mix.install/2`.
|
||||
|
||||
As an example, imagine you have created a notebook inside your current project,
|
||||
at `notebooks/example.livemd`. In order to run within the root Mix project, using
|
||||
the same configuration and dependencies versions, you can change your notebook
|
||||
setup cell to invoke `Mix.install/2` with the following arguments:
|
||||
|
||||
```elixir
|
||||
Mix.install(
|
||||
[
|
||||
{:my_app, path: Path.join(__DIR__, ".."), env: :dev}
|
||||
],
|
||||
config_path: :my_app,
|
||||
lockfile: :my_app
|
||||
)
|
||||
```
|
||||
|
||||
## Deploying custom apps and internal tooling
|
||||
|
||||
Your Livebook notebooks can be deployed as applications which
|
||||
you may then share within your team and company. Docker deployment
|
||||
is provided out of the box and you can automate your deployment,
|
||||
share secrets, configure authentication and more with
|
||||
[Livebook Teams](https://livebook.dev/teams).
|
||||
|
||||
## Communication and automation of Elixir systems
|
||||
|
||||
You may also deploy notebooks as applications that automate and monitor
|
||||
live Elixir systems. By clicking on "+ Smart cell", you will find Livebook
|
||||
provides a "Remote execution" widget, that allows you to configure the
|
||||
node name, cookie, and the code you want to execute on the remote node.
|
||||
|
||||
The node and cookie information are configured directly in the production
|
||||
system you want to connect to. For example, to connect to a
|
||||
[Phoenix application](https://phoenixframework.org/) running on your machine,
|
||||
you may start it as follows:
|
||||
|
||||
```shell
|
||||
$ iex --sname phoenix-app --cookie secret -S mix phx.server
|
||||
```
|
||||
|
||||
With this information in hand, you can query and automate tasks within
|
||||
existing Elixir systems. You may also mix remote execution with Livebook's
|
||||
rich features to deploy applications that interact with those systems.
|
||||
|
||||
## Debugging live systems (with attached mode)
|
||||
|
||||
Livebook uses the concept of a **runtime**, which in practice is an Elixir node
|
||||
responsible for evaluating your code. You can choose the runtime by clicking
|
||||
the "Runtime" icon on the sidebar (or by using the `s` `r` keyboard shortcut).
|
||||
|
||||
By default, a new Elixir runtime is started (similarly to starting `iex`)
|
||||
for each notebook. You can click reconnect whenever you want to discard the
|
||||
current runtime and start a new one.
|
||||
|
||||
You can also manually *attach* to an existing node by picking the "Attached Node"
|
||||
runtime. While in the previous section we used the "Remote execution" smart cell
|
||||
to connect the default Livebook runtime to an existing node, the "Attached Node"
|
||||
will make it so the Livebook runtime itself runs within the external node.
|
||||
|
||||
To do so, open up a new notebook and click the "Runtime" icon on the sidebar.
|
||||
Click to "Configure" the runtime and choose "Attached node". Input the
|
||||
name and cookie from the remote node and you should be ready to connect
|
||||
to it. Once connected, be careful: any code that you execute in the notebook
|
||||
now runs within the connected application. You are also limited on actions
|
||||
you may perform. For example, you can't install dependencies (nor would that
|
||||
be a good idea on a running system).
|
||||
|
||||
You may also [connect your local Livebook instance to a node running in
|
||||
production depending on your platform](https://fly.io/docs/elixir/advanced-guides/connect-livebook-to-your-app/).
|
||||
|
||||
## Scaffolding embedded systems with Nerves
|
||||
|
||||
If you want to run Livebook on embedded devices, such as Raspberry Pi,
|
||||
BeagleBone, etc., check out [the Livebook
|
||||
firmware](https://github.com/nerves-livebook/nerves_livebook) built
|
||||
with [Nerves](https://www.nerves-project.org/). In such cases, Livebook
|
||||
uses a special runtime, called the Embedded Runtime, where all of your
|
||||
code runs within Livebook itself, without starting additional runtimes
|
||||
(which may be too expensive on limited devices).
|
||||
|
||||
## Ready to get started?
|
||||
|
||||
Head out to [Livebook homepage](https://livebook.dev/) to install it.
|
||||
Once you have it up and running, head to the "Learn" section on the
|
||||
sidebar to learn more!
|
|
@ -179,110 +179,6 @@ graph TD;
|
|||
C-->D;
|
||||
```
|
||||
|
||||
## Elixir integration and use cases
|
||||
|
||||
There are many ways Elixir developers use and leverage Livebook today.
|
||||
|
||||
<!-- livebook:{"break_markdown":true} -->
|
||||
|
||||
### Documentation with `Mix.install`
|
||||
|
||||
Livebook is an excellent tool for documentation. Many Elixir packages use
|
||||
Livebook as tutorials but you can also directly run Livebook within the context
|
||||
of your existing application with the help of `Mix.install/2`.
|
||||
|
||||
As an example, imagine you have created a notebook inside your current project,
|
||||
at `notebooks/example.livemd`. In order to run within the root Mix project, using
|
||||
the same configuration and dependencies versions, you can change your notebook
|
||||
setup cell to invoke `Mix.install/2` with the following arguments:
|
||||
|
||||
<!-- livebook:{"force_markdown":true} -->
|
||||
|
||||
```elixir
|
||||
Mix.install(
|
||||
[
|
||||
{:my_app, path: Path.join(__DIR__, ".."), env: :dev}
|
||||
],
|
||||
config_path: :my_app,
|
||||
lockfile: :my_app
|
||||
)
|
||||
```
|
||||
|
||||
<!-- livebook:{"break_markdown":true} -->
|
||||
|
||||
### Deploying custom apps and internal tooling
|
||||
|
||||
Your Livebook notebooks can be deployed as actual applications which
|
||||
you may then share within your team and company. We have a
|
||||
[whole guide dedicated to this topic](/learn/notebooks/deploy-apps),
|
||||
which is recommended reading for those who want to learn more.
|
||||
The next use case also builds on top of notebook deployment,
|
||||
let's check it out.
|
||||
|
||||
<!-- livebook:{"break_markdown":true} -->
|
||||
|
||||
### Communication and automation of Elixir systems
|
||||
|
||||
You may also deploy notebooks as applications that automate and monitor
|
||||
live Elixir systems. By clicking on "+ Smart cell", you will find Livebook
|
||||
provides a "Remote execution" widget, that allows you to configure the
|
||||
node name, cookie, and the code you want to execute on the remote node.
|
||||
|
||||
The node and cookie information are configured directly in the production
|
||||
system you want to connect to. For example, to connect to a
|
||||
[Phoenix application](https://phoenixframework.org/) running on your machine,
|
||||
you may start it as follows:
|
||||
|
||||
```shell
|
||||
$ iex --sname phoenix-app --cookie secret -S mix phx.server
|
||||
```
|
||||
|
||||
With this information in hand, you can query and automate tasks within
|
||||
existing Elixir systems. You may also mix remote execution with Livebook's
|
||||
rich features to [deploy applications](/learn/notebooks/deploy-apps)
|
||||
that interact with those systems.
|
||||
|
||||
<!-- livebook:{"break_markdown":true} -->
|
||||
|
||||
### Debugging live systems (with attached mode)
|
||||
|
||||
Livebook uses the concept of a **runtime**, which in practice is an Elixir node
|
||||
responsible for evaluating your code. You can choose the runtime by clicking
|
||||
the "Runtime" icon (<i class="ri-livebook-runtime"></i>) on the sidebar
|
||||
(or by using the <kbd>s</kbd> <kbd>r</kbd> keyboard shortcut).
|
||||
|
||||
By default, a new Elixir runtime is started (similarly to starting `iex`)
|
||||
for each notebook. You can click reconnect whenever you want to discard the
|
||||
current runtime and start a new one.
|
||||
|
||||
You can also manually *attach* to an existing node by picking the "Attached Node"
|
||||
runtime. While in the previous section we used the "Remote execution" smart cell
|
||||
to connect the default Livebook runtime to an existing node, the "Attached Node"
|
||||
will make it so the Livebook runtime itself runs within the external node.
|
||||
|
||||
To do so, open up a new notebook and click the "Runtime" icon on the sidebar.
|
||||
Click to "Configure" the runtime and choose "Attached node". Input the
|
||||
name and cookie from the remote node and you should be ready to connect
|
||||
to it. Once connected, be careful: any code that you execute in the notebook
|
||||
now runs within the connected application. You are also limited on actions
|
||||
you may perform. For example, you can't install dependencies (nor would that
|
||||
be a good idea on a running system).
|
||||
|
||||
You may also [connect your local Livebook instance to a node running in
|
||||
production depending on your platform](https://fly.io/docs/elixir/advanced-guides/connect-livebook-to-your-app/).
|
||||
|
||||
<!-- livebook:{"break_markdown":true} -->
|
||||
|
||||
### Scaffolding embedded systems with Nerves
|
||||
|
||||
If you want to run Livebook on embedded devices, such as Raspberry Pi,
|
||||
BeagleBone, etc., check out [the Livebook
|
||||
firmware](https://github.com/nerves-livebook/nerves_livebook) built
|
||||
with [Nerves](https://www.nerves-project.org/). In such cases, Livebook
|
||||
uses a special runtime, called the Embedded Runtime, where all of your
|
||||
code runs within Livebook itself, without starting additional runtimes
|
||||
(which may be too expensive on limited devices).
|
||||
|
||||
## Erlang support
|
||||
|
||||
Livebook also allows developers to write Erlang code. To do so,
|
||||
|
@ -431,7 +327,7 @@ That's our quick intro to Livebook! Where to go next?
|
|||
notebook;
|
||||
|
||||
* [Write and deploy a chat application](/learn/notebooks/deploy-apps)
|
||||
using Livebook;
|
||||
using Livebook and learn more about our [use cases](https://hexdocs.pm/livebook/use_cases.html)
|
||||
|
||||
* Go back [to the Learn page](/learn) and see how to use Livebook to
|
||||
deploy apps, explore data, plot graphs, and much more;
|
||||
|
|
1
mix.exs
1
mix.exs
|
@ -217,6 +217,7 @@ defmodule Livebook.MixProject do
|
|||
defp extras() do
|
||||
[
|
||||
{"README.md", title: "Welcome to Livebook"},
|
||||
"docs/use_cases.md",
|
||||
"docs/authentication.md",
|
||||
"docs/deployment/docker.md",
|
||||
"docs/deployment/basic_auth.md",
|
||||
|
|
6
mix.lock
6
mix.lock
|
@ -12,7 +12,7 @@
|
|||
"earmark_parser": {:hex, :earmark_parser, "1.4.39", "424642f8335b05bb9eb611aa1564c148a8ee35c9c8a8bba6e129d51a3e3c6769", [:mix], [], "hexpm", "06553a88d1f1846da9ef066b87b57c6f605552cfbe40d20bd8d59cc6bde41944"},
|
||||
"ecto": {:hex, :ecto, "3.11.1", "4b4972b717e7ca83d30121b12998f5fcdc62ba0ed4f20fd390f16f3270d85c3e", [:mix], [{:decimal, "~> 2.0", [hex: :decimal, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "ebd3d3772cd0dfcd8d772659e41ed527c28b2a8bde4b00fe03e0463da0f1983b"},
|
||||
"eini": {:hex, :eini_beam, "2.2.3", "4c809b483b0435789c5924642b81ed1cd6fa7d23f5e2efb3e420522a051fa483", [:rebar3], [], "hexpm", "10381b4cb76b8340b492653dae8f6ab7cb372305906ea196d6a1c070516e7a5f"},
|
||||
"ex_doc": {:hex, :ex_doc, "0.31.1", "8a2355ac42b1cc7b2379da9e40243f2670143721dd50748bf6c3b1184dae2089", [:mix], [{:earmark_parser, "~> 1.4.39", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_c, ">= 0.1.1", [hex: :makeup_c, repo: "hexpm", optional: true]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "3178c3a407c557d8343479e1ff117a96fd31bafe52a039079593fb0524ef61b0"},
|
||||
"ex_doc": {:hex, :ex_doc, "0.32.1", "21e40f939515373bcdc9cffe65f3b3543f05015ac6c3d01d991874129d173420", [:mix], [{:earmark_parser, "~> 1.4.39", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_c, ">= 0.1.1", [hex: :makeup_c, repo: "hexpm", optional: true]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "5142c9db521f106d61ff33250f779807ed2a88620e472ac95dc7d59c380113da"},
|
||||
"expo": {:hex, :expo, "0.5.1", "249e826a897cac48f591deba863b26c16682b43711dd15ee86b92f25eafd96d9", [:mix], [], "hexpm", "68a4233b0658a3d12ee00d27d37d856b1ba48607e7ce20fd376958d0ba6ce92b"},
|
||||
"file_system": {:hex, :file_system, "0.2.10", "fb082005a9cd1711c05b5248710f8826b02d7d1784e7c3451f9c1231d4fc162d", [:mix], [], "hexpm", "41195edbfb562a593726eda3b3e8b103a309b733ad25f3d642ba49696bf715dc"},
|
||||
"finch": {:hex, :finch, "0.16.0", "40733f02c89f94a112518071c0a91fe86069560f5dbdb39f9150042f44dcfb1a", [:mix], [{:castore, "~> 0.1 or ~> 1.0", [hex: :castore, repo: "hexpm", optional: false]}, {:mime, "~> 1.0 or ~> 2.0", [hex: :mime, repo: "hexpm", optional: false]}, {:mint, "~> 1.3", [hex: :mint, repo: "hexpm", optional: false]}, {:nimble_options, "~> 0.4 or ~> 1.0", [hex: :nimble_options, repo: "hexpm", optional: false]}, {:nimble_pool, "~> 0.2.6 or ~> 1.0", [hex: :nimble_pool, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "f660174c4d519e5fec629016054d60edd822cdfe2b7270836739ac2f97735ec5"},
|
||||
|
@ -24,8 +24,8 @@
|
|||
"jose": {:hex, :jose, "1.11.6", "613fda82552128aa6fb804682e3a616f4bc15565a048dabd05b1ebd5827ed965", [:mix, :rebar3], [], "hexpm", "6275cb75504f9c1e60eeacb771adfeee4905a9e182103aa59b53fed651ff9738"},
|
||||
"jsx": {:hex, :jsx, "3.0.0", "20a170abd4335fc6db24d5fad1e5d677c55dadf83d1b20a8a33b5fe159892a39", [:rebar3], [], "hexpm", "37beca0435f5ca8a2f45f76a46211e76418fbef80c36f0361c249fc75059dc6d"},
|
||||
"makeup": {:hex, :makeup, "1.1.1", "fa0bc768698053b2b3869fa8a62616501ff9d11a562f3ce39580d60860c3a55e", [:mix], [{:nimble_parsec, "~> 1.2.2 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "5dc62fbdd0de44de194898b6710692490be74baa02d9d108bc29f007783b0b48"},
|
||||
"makeup_elixir": {:hex, :makeup_elixir, "0.16.1", "cc9e3ca312f1cfeccc572b37a09980287e243648108384b97ff2b76e505c3555", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "e127a341ad1b209bd80f7bd1620a15693a9908ed780c3b763bccf7d200c767c6"},
|
||||
"makeup_erlang": {:hex, :makeup_erlang, "0.1.2", "ad87296a092a46e03b7e9b0be7631ddcf64c790fa68a9ef5323b6cbb36affc72", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "f3f5a1ca93ce6e092d92b6d9c049bcda58a3b617a8d888f8e7231c85630e8108"},
|
||||
"makeup_elixir": {:hex, :makeup_elixir, "0.16.2", "627e84b8e8bf22e60a2579dad15067c755531fea049ae26ef1020cad58fe9578", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "41193978704763f6bbe6cc2758b84909e62984c7752b3784bd3c218bb341706b"},
|
||||
"makeup_erlang": {:hex, :makeup_erlang, "0.1.5", "e0ff5a7c708dda34311f7522a8758e23bfcd7d8d8068dc312b5eb41c6fd76eba", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "94d2e986428585a21516d7d7149781480013c56e30c6a233534bedf38867a59a"},
|
||||
"mime": {:hex, :mime, "2.0.5", "dc34c8efd439abe6ae0343edbb8556f4d63f178594894720607772a041b04b02", [:mix], [], "hexpm", "da0d64a365c45bc9935cc5c8a7fc5e49a0e0f9932a761c55d6c52b142780a05c"},
|
||||
"mint": {:hex, :mint, "1.5.1", "8db5239e56738552d85af398798c80648db0e90f343c8469f6c6d8898944fb6f", [:mix], [{:castore, "~> 0.1.0 or ~> 1.0", [hex: :castore, repo: "hexpm", optional: true]}, {:hpax, "~> 0.1.1", [hex: :hpax, repo: "hexpm", optional: false]}], "hexpm", "4a63e1e76a7c3956abd2c72f370a0d0aecddc3976dea5c27eccbecfa5e7d5b1e"},
|
||||
"mint_web_socket": {:hex, :mint_web_socket, "1.0.3", "aab42fff792a74649916236d0b01f560a0b3f03ca5dea693c230d1c44736b50e", [:mix], [{:mint, ">= 1.4.1 and < 2.0.0-0", [hex: :mint, repo: "hexpm", optional: false]}], "hexpm", "ca3810ca44cc8532e3dce499cc17f958596695d226bb578b2fbb88c09b5954b0"},
|
||||
|
|
Loading…
Reference in a new issue