diff --git a/community-lead/billing/responsiveness.md b/community-lead/billing/responsiveness.md index 9fc3299..e4d58de 100644 --- a/community-lead/billing/responsiveness.md +++ b/community-lead/billing/responsiveness.md @@ -1,3 +1,4 @@ +(community-lead:billing:responsiveness)= # How to balance cloud responsiveness and cost There is a tradeoff between how responsive a hub is and its cost. This is primarily determined by the **size of the nodes** that are used for user sessions. @@ -34,4 +35,8 @@ Many 2i2c hubs use a **balanced approach**: - Have the ability to provision smaller nodes for quick scaling during peak times - Allow specific high-memory users to request larger dedicated nodes -This provides reasonable responsiveness while keeping costs manageable. The 2i2c engineering team works with communities to find the right balance for their usage patterns. \ No newline at end of file +This provides reasonable responsiveness while keeping costs manageable. The 2i2c engineering team works with communities to find the right balance for their usage patterns. + +```{seealso} +Users may wonder why their server takes time to start. See [](user:faq:startup-time) for a user-friendly explanation of typical startup times. +``` \ No newline at end of file diff --git a/user/basics/index.md b/user/basics/index.md new file mode 100644 index 0000000..05ac2e5 --- /dev/null +++ b/user/basics/index.md @@ -0,0 +1,8 @@ +# Hub basics + +This section covers fundamental information about using your 2i2c JupyterHub. + +```{toctree} +:maxdepth: 1 +startup +``` diff --git a/user/basics/startup.md b/user/basics/startup.md new file mode 100644 index 0000000..c4aeeb8 --- /dev/null +++ b/user/basics/startup.md @@ -0,0 +1,35 @@ +(user:faq:startup-time)= +# What is a typical hub start-up time? + +User server startup time ranges from **a few seconds** to **10 minutes**, depending on two main factors: + +## Factor 1: Resources available on a node + +When a server starts, it requests resources from a node. + +**If a node already exists with sufficient resources:** +- Server creation takes only a few seconds + +**If a suitable node doesn't exist or lacks resources:** +- The autoscaler creates a new node, which takes 2 to 10+ minutes +- Node creation time depends on the cloud provider and machine type (larger machines like GPUs often take longer) +- If startup exceeds 10 minutes, you'll see a `TimeoutError` and need to restart your server to use the newly created node +- This timeout is uncommon but can occur with certain machine types + + +## Factor 2: Environment image availability + +When a user server starts, JupyterHub then finds and loads the **environment image**, which contains all the tools available to the user. + +**If the image is already on the node:** +- Server startup is much faster since no download is needed + +**If the environment image isn't on the node:** +- The image must be pulled from the container registry +- This takes a few minutes depending on image size and network conditions +- Image pulling always happens if a new node was just created + + +```{important} +Startup time can be reduced through strategies like maintaining minimum node counts or pre-pulling images, but these increase costs. Learn more about balancing responsiveness and cost in [](community-lead:billing:responsiveness). +``` \ No newline at end of file diff --git a/user/environment/choose.md b/user/environment/choose.md index 93468f0..8c69779 100644 --- a/user/environment/choose.md +++ b/user/environment/choose.md @@ -51,6 +51,10 @@ We recommend always explicitly specifying a version number in the `TAG` field ra jovyan@user:~$ echo $JUPYTER_IMAGE ``` +```{note} +If the image isn't already cached on a node, it will need to be pulled from the container registry, which can add several minutes to startup time. Learn more about startup times in [](user:faq:startup-time). +``` + ### The "Dynamic Image Building" option This allows users to dynamically build an environment image for their Jupyter server, similar to [mybinder.org](https://mybinder.org). diff --git a/user/get-started.md b/user/get-started.md index e27e065..1554b0f 100644 --- a/user/get-started.md +++ b/user/get-started.md @@ -19,6 +19,10 @@ For other hubs, you will presented with a *Server Options* page where you can se ![JupyterHub server options](/images/server-options.jpeg) +```{seealso} +Learn more about typical server startup times in [](user:faq:startup-time). +``` + It is important to use cloud resources responsibly to maximize efficiency and minimize carbon emissions. Selecting a larger server incurs a larger financial cost, as well as an environmental cost! Best practices for using resources responsibly include diff --git a/user/index.md b/user/index.md index a10b021..9eb1e15 100644 --- a/user/index.md +++ b/user/index.md @@ -56,6 +56,14 @@ Distribute notebooks and files Contact 2i2c Support for assistance ::: +:::{grid-item-card} Frequently Asked Questions +:text-align: center +:link: basics/startup +:link-type: doc + +Common questions about using your hub +::: + :::: ## All User Topics @@ -64,6 +72,7 @@ Contact 2i2c Support for assistance :maxdepth: 2 get-started +basics/index data/index environment/index sharing/index