diff --git a/docs/api/config.md b/docs/api/config.md new file mode 100644 index 000000000..57b7c4073 --- /dev/null +++ b/docs/api/config.md @@ -0,0 +1,61 @@ +# Config + +## Overview + +Mesop is configured at the application level using environment variables. + +## Configuration values + +Mesop currently only has one configuration value, but more will be added in the future. + +### MESOP_STATE_SESSION_BACKEND + +Sets the backend to use for caching state data server-side. This makes it so state does +not have to be sent to the server on every request, reducing bandwidth, especially if +you have large state objects. + +The only backend option available at the moment is `memory`. + +Users should be careful when using the `memory` backend. Each Mesop process has their +own RAM, which means cache misses will be common if there is no session affinity. In +addition, the amount of RAM must be carefully specified per machine in accordance with +the expected user traffic and state size. + +The safest option for using the `memory` backend is to use a single a process with a +good amount of RAM. Python is not the most memory efficient, especially data structures +such as dicts. + +The drawback of being limited to a single process is that requests will take longer to +process since only one request can be handled at a time. This is especially problematic +if your application contains long running API calls. + +If session affinity is available, you can scale up multiple machines, each running +single processes. + +**Default:** `none` + +## Usage Examples + +### One-liner + +You can specify the environment variables before the mesop command. + +```sh +MESOP_STATE_SESSION_BACKEND=memory mesop main.py +``` + +### Use a .env file + +Mesop also supports `.env` files. This is nice since you don't have to keep setting +the environment variables. In addition, the variables are only set when the application +is run. + +```sh title=".env" +MESOP_STATE_SESSION_BACKEND=memory +``` + +When you run your Mesop app, the .env file will then be read. + +```sh +mesop main.py +``` diff --git a/docs/guides/deployment.md b/docs/guides/deployment.md index 05d8a0efe..6fe0407fd 100644 --- a/docs/guides/deployment.md +++ b/docs/guides/deployment.md @@ -76,6 +76,20 @@ gcloud run deploy Follow the instructions and then you should be able to access your deployed app. +### Session Affinity + +If you're running Mesop with [MESOP_STATE_SESSION_BACKEND=memory](../api/config.md#mesop_state_session_backend), +then you will want to enable [session affinity](https://cloud.google.com/run/docs/configuring/session-affinity) in order to utilize the `memory` backend efficiently. + +The command should be: + +```sh +gcloud run services update $YOUR_SERVICE --session-affinity +``` + +By default gunicorn allocates one worker, but you should double check that gunicorn is +configured correctly for the `memory` backend. + ## App Engine This section describes deployment to [Google App Engine](https://cloud.google.com/appengine) using diff --git a/docs/guides/state_management.md b/docs/guides/state_management.md index 8fe0bcbc9..9220701a6 100644 --- a/docs/guides/state_management.md +++ b/docs/guides/state_management.md @@ -134,3 +134,11 @@ class State: ### State performance issues Because the state class is serialized and sent back and forth between the client and server, you should try to keep the state class reasonably sized. For example, if you store a very large string (e.g. base64-encoded image) in state, then it will degrade performance of your Mesop app. Instead, you should try to store large data outside of the state class (e.g. in-memory, filesystem, database, external service) and retrieve the data as needed for rendering. + +#### Storing state in memory + +Mesop has a feature that allows you to store state in memory rather than passing the +full state on every request. This may help improve performance when dealing with large +state objects. The caveat is that storing state in memory contains its own set of +problems that you must carefully consider. See the [config section](../api/config.md#mesop_state_session_backend) +for details on how to use this feature. diff --git a/mkdocs.yml b/mkdocs.yml index 763c16ae5..a9ea862d3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -68,6 +68,7 @@ nav: - Commands: - Navigate: api/commands/navigate.md - Scroll into view: api/commands/scroll_into_view.md + - Config: api/config.md - FAQ: faq.md - Demo Gallery 🔗: demo.md - Blog: