A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
docs: Add some notes on deploying programmatically (#6217)
Will Lachancecd336790667a
diff --git a/docs/guides/deploying/programmatically.md b/docs/guides/deploying/programmatically.mdindex d84ddc6956..930f5284ba 100644--- a/docs/guides/deploying/programmatically.md+++ b/docs/guides/deploying/programmatically.md@@ -38,6 +38,8 @@ if __name__ == "__main__":For a more complete example, see the [FastAPI example](https://github.com/marimo-team/marimo/tree/main/examples/frameworks/fastapi).+Note that when run in this mode, marimo will serve its static assets under the name of the notebook (in the example above, that would be `http://hostname/<dashboard|sales>/assets/<assetname.css|js|...>`). If you are using custom authorization middleware, skip authentication for these assets to avoid server round-trips. There are _many_ of them.+## Dynamic directoryIf you'd like to create a server to dynamically load marimo notebooks from a directory, you can use the `with_dynamic_directory` method. This is useful if the contents of the directory change often, such as a directory of notebooks for a dashboard, without restarting the server.@@ -122,14 +124,12 @@ The `request` object provides access to:- `request.url`: URL information including path, query parameters- `request.meta`: Metadata added by your custom middleware-### Documenting and Validating Query ParametersWhen mounted apps accept [query parameters](../../api/query_params.md), it can be helpful to declare, validate, and document them with the help of a [Pydantic model](https://fastapi.tiangolo.com/tutorial/query-param-models/).If a marimo app called `notebooks/items.py` is mounted to `/items`, declaring an endpoint with the same route will take the query parameters through Pydantic model validation first, then redirect to the marimo endpoint.-```python# src/main.pyfrom fastapi import FastAPI, Request, Query@@ -169,4 +169,16 @@ for filename in notebooks_dir.iterdir():app.mount("/", server.build())-```\ No newline at end of file+```++## Under the Hood++Behind the scenes, in this mode, marimo is spinning up a new computational kernel+in a separate sub-thread (same process) for each new session / app created.+There are a few implications of this from a performance and reliability perspective:++- If you are running multiple instances of this same server for load balancing, you will need to use sticky sessions in your load balancer to ensure that the same client gets the same kernel each time.+- Similarly, attempting to run multiple instances of the same FastAPI+ process (a common approach with Python web services) on the same node will not work reliably, since only one of them will actually be running the kernel.++In summary, there are limitations to how far the approach described here can horizontally scale, so we recommend scaling vertically first. In other words, increase the container CPU/Memory specs before increasing the number of container instances.