solara-ui 1.31.0__py2.py3-none-any.whl

solara/website/pages/documentation/advanced/content/20-understanding/12-reacton-basics.md

@@ -0,0 +1,108 @@
+---
+title: Understanding the basics of Reacton
+description: Using your favorite component, we try to understand better how it works to improve your understanding of Reacton and, thus, how to use Solara.
+---
+# Reacton basic understanding
+
+
+Let us take our favorite component, and try to understand a bit better how it works to improve your understanding of Reacton and thus how to use Solara.
+
+
+```solara
+import solara
+
+
+@solara.component
+def ClickButton():
+    clicks, set_clicks = solara.use_state(0)
+
+    def my_click_hander():
+        set_clicks(clicks + 1)
+
+    return solara.Button(label=f"Clicked: {clicks}", on_click=my_click_hander)
+
+Page = ClickButton
+```
+
+This example does a few things:
+
+ * Add state (`clicks`) to the component.
+ * Create a callback function (`my_click_handler`). When executed, it will increase ask Solara/Reacton to increase the `clicks` value on the next render, by calling `set_clicks`.
+ * Pass the callback function to the child component (`Button`).
+ * Set the `label` value on each render.
+
+Now if a user clicks the button:
+
+ * The `my_click_hander` callback will be called by Solara/Reacton.
+ * Your code (the body of `my_click_hander`) will be executed and will ask Reacton to change the state of `clicks` by increasing the value by 1.
+ * Solara/Reacton got asked to change the of `clicks`, and will execute your render function (the body of the `ClickButton` component) once.
+ * Solara/Reacton will compare the return value of your component and will update the associated widget. In this case it will update the label to `"`Clicked: 1"`.
+
+This pattern is very common, where a parent component (ClickButton) managed the state (the number of times clicked), and state changes (increasing the clicks by 1 on a button click).
+
+## Graphically
+
+Is the above text a bit dry? Maybe the annotated code will make it easier to understand for you.
+
+![basics](https://dxhl76zpt6fap.cloudfront.net/public/docs/reacton-basics.webp)
+
+
+## Going deeper
+
+
+Still not satisfied? Let's go through all the steps in more detail in this sequence diagram:
+
+```mermaid
+sequenceDiagram
+    actor You
+    participant Frontend as Frontend
+    participant ipywidgets as IPyWidgets
+    participant react as Reacton
+    participant component as ButtonClick
+    participant app as Solara
+
+    app->>component: el=ButtonClick()
+    app->>react: render(el)
+
+    activate react
+    react->>component: render()
+    component->>react: use_state(0)<br>(returns 0)
+
+    react->>react: reconsolidate()
+    react->>ipywidgets: create Button<br>description="Clicked: 0"
+    deactivate react
+    ipywidgets--)Frontend: create Button view
+
+    You->>Frontend: clicks button
+
+    Frontend--)ipywidgets: Button clicked
+    ipywidgets->>component: on_click
+    activate component
+    component->>react: set_clicks(1)
+    activate react
+    deactivate component
+    react->>+component: render()
+    component->>-react: use_state(0)<br> (now returns 1)
+    react->>react: reconsolidate()
+    react->>ipywidgets: update Button<br>description="Clicked 1"
+    deactivate react
+    ipywidgets--)Frontend: update Button<br>description="Clicked 1"
+```
+
+In words
+
+   1. Solara create `el = ButtonClick()` from your component.
+   1. The `display(el)` triggers the call to Reacton.
+   1. The render call enters the render phase, which will call the function body (which we call render function) of the `ButtonClick` component.
+   1. Our ButtonClick render function calls [`use_state`](/documentation/api/hooks/use_state). Because this is our first render phase, this returns the initial value (0).
+   1. The ButtonClick render function returns a Button element (not a widget!) with `description="Clicked: 0 times"`.
+   1. The Reacton render call is done with the render phase, and enters the reconciliation phase, where it looks at the difference between the real widgets and the virtual widgets tree (represented by the Reacton elements). We find there is no previous widget associated with the virtual widget (or element) and decide to create a widget.
+   1. Asynchronously via the Jupyter protocol, a widget model and view are created and displayed to the user in the browser.
+   1. The user clicks on the button.
+   1. The `on_click` handler gets triggered on the Python side, inside of the `ButtonClick` component (called `my_click_handler`).
+   1. `my_click_handler` handler calls `set_clicks(1)` which triggers a re-render.
+   1. The render call enters the render phase, which calls the render function of `ButtonClick` for the second time.
+   1. Our ButtonClick render function calls [`reacton.use_state`](#use_state). Because this is our second render phase, this returns the last set value, which is 1.
+   1. The ButtonClick render function returns a new Button element (not a widget!) with the description `"Clicked: 1 times"`.
+   1. The Reacton render call is done with the render phase, and enters the reconciliation phase, where it looks at the difference between the real widgets and the virtual widgets tree (represented by the Reacton elements). We find there is a widget associated with the virtual widget (or element) and decide to update the changed attributes of the widget and set `description` to `"Clicked: 1 times"`.
+   1. Asynchronously via the Jupyter protocol, the widet model and view are being updated in the browser.

solara/website/pages/documentation/advanced/content/20-understanding/15-anatomy.md

@@ -0,0 +1,23 @@
+---
+title: The anatomy of Solara's functionality
+description: Dive deep into how Solara uses the technologies it builds on.
+---
+# Anatomy
+
+For communication, it is useful to speak the same language and use the same idiom.
+As a reference, we provide this "anatomy" image of our favorite `ClickButton` component with a layout that we consider best practice.
+
+![anatomy](https://dxhl76zpt6fap.cloudfront.net/public/docs/anatomy.webp)
+
+## Explanations
+
+ * Import `solara` and you also get the `reacton` namespace with it (saves typing, and finding/remembering which hooks is in which packages)
+ * Add a `@solara.component` decorator to turn your function into a component.
+ * Start with `use_state` hooks and other hooks. This avoids issues with [conditional hooks](/documentation/advanced/understanding/rules-of-hooks) or hooks in loops.
+ * Data/state flows down (to children)
+ * Information (events, data) flows up from children via events and callbacks (`on_<some_event_name>=my_callback`).
+ * If you need multiple components, use a [parent container component](/documentation/components/layout/app_layout) as context manager. A good default name to give this context manager is `main`. Don't forget to return it in your render function!
+ * The body of your component (the function you wrote) is called the render function.
+ * In between the hooks as defining all your elements, you put your custom code, like checking variables, defining callbacks, and other logic.
+ * The only way for a component to cause itself to rerender is to have state (using `use_state`) and change it (calling the second return value with a different value).
+ * Reacton is declarative. Your render function gets executed after every state change (and thus should be relatively cheap to execute). Reacton will find out the changes for you and will add, remove and update the associated widgets for you. This means you can easily do conditional rendering (creating an element in an if statement or in a loop).

solara/website/pages/documentation/advanced/content/20-understanding/17-rules-of-hooks.md

@@ -0,0 +1,7 @@
+---
+title: The rules of hooks in Solara
+description: Learn the rules that govern the usage of hooks in your Solara application.
+----
+# Rules of hooks
+
+For now, we refer to the [ReactJS documentation](https://reactjs.org/docs/hooks-rules.html).

solara/website/pages/documentation/advanced/content/20-understanding/18-containers.md

@@ -0,0 +1,166 @@
+---
+title: Using Solara with containers to build complex UIs
+description: Solara allows for using python with statements to populate your UIs in a structured manner. This makes it easy to compose different components to build cohesive
+    wholes.
+---
+
+# Laying out components with containers
+
+## Introduction
+Some components, such as our favorite `ClickButton` only add logic on top of an existing component:
+
+```solara
+import solara
+
+
+@solara.component
+def ClickButton():
+    clicks, set_clicks = solara.use_state(0)
+
+    def my_click_hander():
+        set_clicks(clicks + 1)
+
+    # We return a single component
+    return solara.Button(label=f"Clicked: {clicks}", on_click=my_click_hander)
+
+Page = ClickButton
+```
+
+
+## Containers with children
+However, more sophisticated components will add multiple components together into a container component, let's take a look at an example.
+
+```solara
+import solara
+
+
+@solara.component
+def FancyClickButton():
+    clicks, set_clicks = solara.use_state(0)
+
+    def increase_count():
+        set_clicks(clicks + 1)
+
+    def reset_count():
+        set_clicks(0)
+
+    button_increase = solara.Button(label=f"Clicked: {clicks}", on_click=increase_count)
+    button_reset = solara.Button(label="Reset", on_click=reset_count)
+
+    return solara.Row(children=[button_increase,
+                                 button_reset,
+                                 ])
+
+
+Page = FancyClickButton
+
+```
+
+
+Here we use an [HBox](/documentation/components/layout/hbox) to lay out two child components horizontally.
+
+
+## Cleaner way to add children to containers
+
+Because using container components is so common, we created a more convenient way to pass children to components and made your code look neater and more structured as well (avoiding nested lists).
+
+```solara
+import solara
+
+
+@solara.component
+def FancyClickButton():
+    clicks, set_clicks = solara.use_state(0)
+
+    def increase_count():
+        set_clicks(clicks + 1)
+
+    def reset_count():
+        set_clicks(0)
+
+    with solara.Row() as main:
+        solara.Button(label=f"Clicked: {clicks}", on_click=increase_count)
+        solara.Button(label="Reset", on_click=reset_count)
+    return main
+
+Page = FancyClickButton
+
+```
+
+Here we are using the top-level Row as a context manager (with the name `main`). All child elements created within this context are automatically added as a child.
+
+### About Context managers
+
+Context managers are a Python language feature, there are two ways to use them:
+
+```python
+
+with some_anonymous_context_manager():
+    print("some code")
+
+with some_named_context_manager() as this_is_my_name:
+    print("some other code")
+```
+
+Where the last example assigns the context manager to a variable. In Solara we only need to do that to the top context manager, since we need to return that in our [render function](/documentation/advanced/understanding/anatomy).
+
+All Reacton or Solara components return elements that can be used as context managers. Context managers allow for code to be executed before and after your code block inside of the context manager. This allows us to capture all elements created inside of the context manager. If you want to know more about context managers, consult the Python documentation since this is not Solara specific.
+
+
+### Nested layout
+
+Adding children using context managers work at any level, you can nest Rows and Columns [or any other containers](/api#components).
+
+
+```solara
+import solara
+
+
+@solara.component
+def FancyClickButton():
+    clicks, set_clicks = solara.use_state(0)
+
+    def increase_count():
+        set_clicks(clicks + 1)
+
+    def reset_count():
+        set_clicks(0)
+
+    with solara.Column() as main:
+        with solara.Row():
+            solara.Button(label=f"Clicked: {clicks}", on_click=increase_count)
+            solara.Button(label="Reset", on_click=reset_count)
+        solara.Text("I am a child of a VBox")
+    return main
+
+Page = FancyClickButton
+
+```
+
+
+## Automatic containers
+
+
+Instead of returning the main container, Solara also allows you to not have a return value (or return `None`).
+If that is the case, Solara will look at what elements you created. If you created one, that element will be taken
+as a return value instead. If you make more than one element, those elements will be automatically wrapped by
+a [Column](/documentation/components/layout/column). The only benefit of returning an element, is that we can infer the correct return type,
+which can be useful for testing purposes. Users should probably never return an element, but use the automatic
+container feature.
+
+```solara
+import solara
+
+
+@solara.component
+def ClickButton():
+    clicks, set_clicks = solara.use_state(0)
+
+    def my_click_hander():
+        set_clicks(clicks + 1)
+
+    solara.Button(label=f"Clicked: {clicks}", on_click=my_click_hander)
+    solara.Button(label=f"Reset", on_click=lambda: set_clicks(0))
+
+Page = ClickButton
+```

solara/website/pages/documentation/advanced/content/20-understanding/20-solara.md

@@ -0,0 +1,18 @@
+---
+title: Understanding different parts of Solara
+description: Solara is made of two main components, the bulk of the Solara package with UI elements that can be used together with Jupyter, and Solara server, which
+    allows for these UI elements to be used in standalone apps and dashboards
+---
+# Solara
+
+Solara combines [ipywidgets](./ipywidgets), [reacton](./reacton) and puts it into a opinionated framework to make web apps with a focus on data (data apps for short).
+
+Solara consists of two main parts
+
+## Solara-ui
+
+A set of opinionated react components and hooks that allow you to build web apps and data apps faster.
+
+## Solara-server
+
+A web framework for deploying web apps or data apps in production. Opinionated about pages and routing.

solara/website/pages/documentation/advanced/content/20-understanding/40-routing.md

@@ -0,0 +1,240 @@
+---
+title: Understanding routing in multi-page solara apps
+description: Dive into Solara's routing, which provides a powerful way to compose multiple pages or dashboards into an integrated app.
+---
+# Routing
+
+Routing takes care of linking a web address (more specifically the [pathname](https://developer.mozilla.org/en-US/docs/Web/API/Location), e.g. "/docs/basics/solara") to a state of the UI,
+usually in the form of what appears as pages to a user.
+
+
+Routing includes navigation (hitting the back and forward button of your browser) without causing a page reload.
+
+
+## Automatic routing
+
+Setting up routing can be repetitive, and therefore Solara comes also with a more opinionated method for setting up routing automatically.
+
+### Based on a directory
+
+Using [`generate_routes_directory(path: Path) -> List[solara.Route]:`](/documentation/api/routing/generate_routes_directory) we can request Solara to give us a list of
+routes by scanning a directory for Python scripts, Notebooks and Markdown files.
+
+This function is being used by Solara if you run solara server with a directory as argument name, as used in [our Multi Page guide](/documentation/advanced/howto/multipage). More details can be found there.
+
+
+### Based on a Python package
+
+Similar to the previous section [`generate_routes(module: ModuleType) -> List[solara.Route]:`](/documentation/api/routing/generate_routes) will return a list of routes by scanning a Python package or module for `Page` components, or `app` elements. Again, more information can be found at [our Multi Page guide](/documentation/advanced/howto/multipage).
+
+## Manually defining routes
+
+In Solara, we set up routing by defining a list of `solara.Route` objects, where each route can have another list of routes, its children, forming
+a tree of routes. We assign this list to the `routes` variable in your main app script or module.
+
+### Defining route components
+
+If no `Page` component is found in your main script or module, Solara will assume you have either set the `component` or the `module` argument of the `solara.Route` object.
+
+For example
+
+```python
+import solara
+from solara.website.pages.examples.utilities import calculator
+
+
+@solara.component
+def Home():
+    solara.Markdown("Home")
+
+
+@solara.component
+def About():
+    solara.Markdown("About")
+
+
+routes = [
+    solara.Route(path="/", component=Home, label="Home"),
+    # the calculator module should have a Page component
+    solara.Route(path="calculator", module=calculator, label="Calculator"),
+    solara.Route(path="about", component=About, label="About"),
+]
+```
+
+### Defining route components
+
+If you do define a `Page` component, you are fully responsible for how routing is done, but we recommend using [use_route](/documentation/api/routing/use_route).
+
+An example route definition could be something like this:
+
+```python
+import solara as sol
+
+routes = [
+    # route level == 0
+    solara.Route(path="/"),  # matches empty path ''
+    solara.Route(
+        # route level == 1
+        path="docs",  # matches '/docs'
+        children=[
+            # route level == 2
+            solara.Route(path="basics", children=[  # matches '/docs/basics'
+                # route level == 3
+                solara.Route(path="react"),      # matches '/docs/basics/react'
+                solara.Route(path="ipywidgets"), # matches '/docs/basics/ipywidgets'
+                solara.Route(path="solara"),     # matches '/docs/basics/solara'
+            ]),
+            solara.Route(path="advanced")  # matches '/docs/advanced'
+        ],
+    ),
+    solara.Route(
+        path="blog",
+        # route level == 1
+        children=[
+            solara.Route(path="/"),   # matches '/blog'
+            solara.Route(path="foo"), # matches '/blog/foo'
+            solara.Route(path="bar"), # matches '/blog/bar'
+        ],
+    ),
+    solara.Route(path="contact")  # matches '/contact'
+]
+
+# Lets assume our pathname is `/docs/basics/react`,
+@solara.component
+def Page():
+    level = solara.use_route_level()  # returns 0
+    route_current, routes_current_level = solara.use_routes()
+    # route_current is routes[1], i.e. solara.Route(path="docs", children=[...])
+    # routes_current_level is [routes[0], routes[1], routes[2], routes[3]], i.e.:
+    #    [solara.Route(path="/"), solara.Route(path="docs", children=[...]),
+    #     solara.Route(path="blog", children=[...]), solara.Route(path="contact")]
+    if route_current is None: # no matching route
+        return solara.Error("oops, page not found")
+    else:
+        # we could render some top level navigation here based on route_current_level and route_current
+        return MyFirstLevelChildComponent()
+```
+
+Routes are matched by splitting the pathname around the slash ("/") and matching each part to the routes. The level of the depth into the tree is what we call the `route_level`, which starts at 0, the top level.
+Each call to `use_route` will return the current route (if there is a match to the current path) and the list of siblings including itself.
+
+
+Now the `MyFirstLevelChildComponent` component is responsible for rendering the second level navigation:
+
+```python
+@solara.component
+def MyFirstLevelChildComponent():
+    level = solara.use_route_level()  # returns 1
+    route_current, routes_current_level = solara.use_routes()
+    # route_current is routes[1].children[0], i.e. solara.Route(path="basics", children=[...])
+    # routes_current_level is [routes[1].children[0], routes[1].children[1]], i.e.:
+    #    [solara.Route(path="basics", children=[...]), solara.Route(path="advanced")]
+    if route_current is None: # no matching route
+        return solara.Error("oops, page not found")
+    else:
+        # we could render some mid level navigation here based on route_current_level and route_current
+        return MySecondLevelChildComponent()
+
+```
+
+And the `MySecondLevelChildComponent` component is responsible for rendering the third level navigation:
+
+```python
+@solara.component
+def MySecondLevelChildComponent():
+    level = solara.use_route_level()  # returns 2
+    route_current, routes_current_level = solara.use_routes()
+    # route_current is routes[1].children[0].children[0], i.e. solara.Route(path="react")
+    # routes_current_level is [routes[1].children[0].children[0], routes[1].children[0].children[1], routes[1].children[0].children[2]], i.e.
+    #    [solara.Route(path="react"), solara.Route(path="ipywidgets"), solara.Route(path="solara")]
+    if route_current is None: # no matching route
+        return solara.Error("oops, page not found")
+    else:
+        # we could render some mid level navigation here based on route_current_level and route_current
+        if route_current.path == "react":
+            return DocsBasicReact()  # render the actual content
+        elif route_current.path == "ipywidgets":
+            return DocsBasicIpyWidgets()
+        elif route_current.path == "solara":
+            return DocsBasicSolara()
+        else:
+            return solara.Error("oops, not possible!")
+
+```
+
+From this code, we can see we are free how we transform the routes into the state of the UI (i.e. which components are rendered).
+
+## Adding data
+
+Often, your render logic needs some extra data on what to display. For instance, you may want to dynamically render tabs based on the routes,
+which requires you to have a label, and know which component to add.
+For this purposed we added `label: str` and the `component' attributes, so you can defines routes likes:
+
+```python
+routes = [
+    solara.Route("/", component=Home, label="What is Solara ☀️?"),
+    solara.Route("docs", component=docs.App, label="Docs", children=docs.routes),
+    solara.Route(
+        "demo",
+        component=demo.Demo,
+        children=demo.routes,
+        label="Demo",
+    ),
+    ...
+]
+```
+
+In the case where you did not specify a `Page` component, label is used for the [Title](/documentation/components/page/title) component.
+
+If you need to store more data in the route, you are free to put whatever you want in the `data` attribute, see also [Route](/documentation/api/routing/route).
+
+
+
+## Linking
+
+Note that all routes are relative, since a component does not know if it is embedded into a larger application, which may also do routing.
+
+
+Therefore you should never use the `route.path` for navigation since the route object has no knowledge of the full url
+(e.g. `/docs/basics/ipywigets`) but only knows its small piece of the pathname (e.g. `ipywidgets`)
+
+Using [`resolve_path`](/documentation/api/routing/resolve_path) we can request the full url for navigation.
+
+```python
+def resolve_path(path_or_route: Union[str, solara.Route], level=0) -> str:
+    ...
+```
+
+We can pass this full URL to the [`solara.Link`](/documentation/components/advanced/link) component, e.g. like:
+
+```python
+@solara.component
+def LinkToIpywidgets():
+    route_ipywidgets = routes.children[1].children[0].children[1]
+    # route_ipywidgets.path == "ipywidgets"
+    path = solara.resolve_path(route_ipywidgets)
+    # path == '/docs/basics/ipywidgets
+    with solara.Link(path) as main:
+        solara.Button("read about ipywidgets")
+    return main
+```
+
+## Fully manual routing
+
+If you want to do routing fully manually, you can use the [`solara.use_router`](/documentation/api/routing/use_router) hook, and use the `.path` attribute.
+
+```python
+import solara
+
+
+@solara.component
+def Page():
+    router = solara.use_router()
+    path = router.path
+    parts = path.split("/")
+    solara.Markdown(f"Path = {path!r}, and split up into {parts!r}")
+    # now you can do anything with path or parts.
+    # e.g.
+    # if parts[0] == "docs":
+    #   solara.Markdown("You are in the docs section")
+```

solara/website/pages/documentation/advanced/content/20-understanding/50-solara-server.md

@@ -0,0 +1,97 @@
+---
+title: Understanding the way Solara server works
+description: Solara server enables running ipywidgets-based applications as standalone dashboards and apps, allowing multiple "Virtual kernels" to share
+   the same process for better performance and scalability.
+---
+# Solara server
+
+The solara server enables running ipywidgets based applications without a real Jupyter kernel, allowing multiple "Virtual kernels" to share the same process for better performance and scalability.
+
+## Installation
+
+To install the solara server, run:
+
+```bash
+$ pip install "solara-server[starlette]"
+$ # pip install solara # to get all solara packages
+```
+
+See [our installation guide](/documentation/getting_started/installing) for more information.
+
+## WebSocket in Solara
+Solara uses a WebSocket to transmit state and updates directly from the server to the browser. This ensures that the state remains centralized on the server, facilitating state transitions server-side and enabling live updates to be pushed directly to the browser.
+
+
+## Virtual Kernels
+Normally when a browser page connects to a Solara server, a virtual kernel is created and is assigned a unique identifier termed a "Kernel ID." Should a WebSocket disconnection occur, Solara attempts to re-establish the connection, sending the Kernel ID during this process. If the server recognizes this ID (and the requested kernel hasn't expired) the Solara app resumes operations seamlessly.
+
+### Virtual kernel lifecycle
+Closing a browser page will directly shut the virtual kernel down (if this page was the last known page to the Solara server). This ensures that active closing of pages will directly clean up any memory usage on the server side for this kernel.
+
+However, when the websocket between the web page and the server disconnects, the server keeps the kernel alive for 24 hours after the closure of the last WebSocket connection. The duration is customizable through the `SOLARA_KERNEL_CULL_TIMEOUT` environment variable. This feature is particularly handy in scenarios where devices like computers hibernate, leading to WebSocket disconnections. Upon awakening and subsequent WebSocket reconnection, the Solara app picks up right where it left off.
+
+To optimize memory usage or address specific needs, one might opt for a shorter expiration duration. For instance, setting `SOLARA_KERNEL_CULL_TIMEOUT=1m` will cause sessions to expire after just 1 minute. Other possible options are `2d` (2 days), `3h` (3 hours), `30s` (30 seconds), etc. If no units are given, seconds are assumed.
+
+### Maximum number of kernels connected
+
+Each virtual kernel runs in its own thread, this ensures that one particular user (actually browser page) cannot block the execution of another virtual kernel. However, each thread consumes a bit of resources. If you want to limit the number of kernels, this can be done by setting the `SOLARA_KERNELS_MAX_COUNT` environment variable. The default is unlimited (empty string), but you can set it to any number you like. If the limit is reached, the server will refuse new connections until a kernel is closed.
+
+
+## Handling Multiple Workers
+In setups with multiple workers, it's possible for a page to reconnect to a different worker than its original. This would result in a loss of the virtual kernel (since it lives on a different worker), prompting the Solara app to initiate a fresh start. To prevent this scenario, a sticky session configuration is recommended, ensuring consistent client-worker connections. Utilizing a load balancer, such as [nginx](https://www.nginx.com/), can achieve this.
+
+If you have questions about setting this up, or require assistance, please [contact us](https://solara.dev/docs/contact).
+
+## Sessions
+
+Solara uses a browser cookie (named `solara-session-id`) to store a unique session id. This session id is available via [get_session_id()](https://solara.dev/api/get_session_id) and is the same for all
+browser pages. This can be used to store state that outlives a page refresh.
+
+We recommend storing the state in an external database, especially in the case of multiple workers/nodes. If you want to store state associated to a session in-memory, make sure to set up sticky sessions.
+
+
+
+
+## Readiness check
+
+To check if the server is ready to accept request, the `/readyz` endpoint is added, and should return a 200 HTTP status code, e.g.:
+
+```
+$ curl http://localhost:8765/readyz
+curl -I localhost:8765
+
+HTTP/1.1 200 OK
+...
+```
+
+## Live resource information
+
+
+To check resource usage of the server (CPU, memory, etc.), the `/resourcez` endpoint is added, and should return a 200 HTTP status code and include
+various resource information, like threads created and running, number of virtual kernels, etc. in JSON format. To get also memory and cpu usage, you can include
+the `?verbose` query parameter, e.g.:
+
+```
+$ curl http://localhost:8765/resourcez\?verbose
+```
+
+The JSON format may be subject to change.
+
+
+
+## Production mode
+
+By default, solara runs in development mode. This means, it will:
+
+   * Automatically [reload your project files](/documentation/advanced/reference/reloading) by watching files on the filesystemn
+   * Load debug version of the CSS files and JavaScript files for improved error messages (which leads to larger asset files).
+
+To disabled all of these option, pass the `--production` flag, or set the environment variable `SOLARA_MODE=production`.
+
+## Telemetry
+
+Solara uses Mixpanel to collect usage of the solara server. We track when a server is started, stopped and a daily report of the number of unique users and connections made. To opt out of mixpanel telemetry, either:
+
+ * Set the environmental variable `SOLARA_TELEMETRY_MIXPANEL_ENABLE` to `False`.
+ * Install [python-dotenv](https://pypi.org/project/python-dotenv/) and put `SOLARA_TELEMETRY_MIXPANEL_ENABLE=False` in a `.env` file.
+ * Run in auto restart mode (e.g. using `$ solara run sol.py --auto-restart`)

solara/website/pages/documentation/advanced/content/20-understanding/60-voila.md

@@ -0,0 +1,12 @@
+---
+title: Working together with Voilà
+description: Voilà, together with `voila-vuetify` is an alternative to Solara server. The most significant difference is that Voilà will start one kernel/process
+    per page request, while Solara server is more scalable.
+---
+# Voilà
+
+[Voilà](https://voila.readthedocs.io/) allows you to convert a Jupyter Notebook into an interactive dashboard that allows you to share your work with others.
+
+Voilà is Jupyter notebook focused, meaning that it will render all output from your notebook. Using [`voila-vuetify`](https://github.com/voila-dashboards/voila-vuetify) Voilà allows for a more app like experience, showing only the output you want.
+
+Voilà, together with `voila-vuetify` is an alternative to [Solara server](./solara-server). The most significant difference is that Voilà will start one kernel/process per page request, while [Solara server](./solara-server) can serve many more users from a single process. Sharing the same process means Solara apps can share memory among users (e.g. a large dataset), which will usually lead to better performance and less resource usage.