From 41f1ac2d5f1b63a13df29f546af778113cae833b Mon Sep 17 00:00:00 2001 From: Georgiana Dolocan Date: Thu, 30 Oct 2025 15:28:46 +0200 Subject: [PATCH 1/2] Add faq section --- community-lead/billing/responsiveness.md | 1 + user/faq.md | 21 +++++++++++++++++++++ user/index.md | 10 ++++++++++ 3 files changed, 32 insertions(+) create mode 100644 user/faq.md diff --git a/community-lead/billing/responsiveness.md b/community-lead/billing/responsiveness.md index 9fc3299..99abff2 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. diff --git a/user/faq.md b/user/faq.md new file mode 100644 index 0000000..cdec48a --- /dev/null +++ b/user/faq.md @@ -0,0 +1,21 @@ +# What is a typical hub start-up time that I should expect? + +The time it takes for a user server to start, can be anywhere from a few seconds to 10min. It depends on some factors: + +## The user server can fit on a node/machine that already exists and has enough resources available to serve it. +1. If it can't fit or such a node doesn't exits, then the autoscaler will trigger the creation of a new node. + This can take up from a couple of minutes, to even 10 min or more. When the 10 minutes cap is hit, the server creation will throw a `TimeoutError` and you'll have to re-trigger the server creation process so you'll be assigned to the newly created node. Although not impossible, this is not common and we don't see it happing that often. In practice, we've noticed higher node startup times, with larger machines, like the ones with GPUs. + + The exact time it will take doesn't depend on 2i2c. Usually, it has to do with the cloud provider, machine type availability, etc. +1. If the node is already present and has enough resources, then the server creation will be much faster, taking only a few seconds. + +## The user environment, i.e. the user image chosen from the profile options, is already present on the node. +1. If the image is not present, then it will first need to be pulled on the node. + This can take a couple of minutes also, and is depending on the image size and network conditions. + When a new node has to come up, image pulling will always happen and this will add to the overall time it takes for the server to be ready. + +1. If the image is already present, then the server startup will be much faster, as it won't need to pull the image from the container registry. + +```{important} +The startup time can be reduced though different strategies, like always having a minimum number of nodes available, pre-pulling images on nodes, etc. But this will increase costs, so it's a trade-off that needs to be evaluated on a per-hub basis. More about balancing these trade-offs can be found in [](community-lead:billing:responsiveness). +``` \ No newline at end of file diff --git a/user/index.md b/user/index.md index a10b021..b57ee54 100644 --- a/user/index.md +++ b/user/index.md @@ -58,6 +58,16 @@ Contact 2i2c Support for assistance :::: +:::{grid-item-card} Frequently Asked Questions? +:text-align: center +:link: faq +:link-type: doc + +Contact 2i2c Support for assistance +::: + +:::: + ## All User Topics ```{toctree} From 63dce9e2e9f8fc6c9d511f89863a0192a7ad23fd Mon Sep 17 00:00:00 2001 From: choldgraf Date: Thu, 30 Oct 2025 11:35:49 -0700 Subject: [PATCH 2/2] Streamline the text for server start times and add some cross-refs --- community-lead/billing/responsiveness.md | 6 +++- user/basics/index.md | 8 ++++++ user/basics/startup.md | 35 ++++++++++++++++++++++++ user/environment/choose.md | 4 +++ user/faq.md | 21 -------------- user/get-started.md | 4 +++ user/index.md | 9 +++--- 7 files changed, 60 insertions(+), 27 deletions(-) create mode 100644 user/basics/index.md create mode 100644 user/basics/startup.md delete mode 100644 user/faq.md diff --git a/community-lead/billing/responsiveness.md b/community-lead/billing/responsiveness.md index 99abff2..e4d58de 100644 --- a/community-lead/billing/responsiveness.md +++ b/community-lead/billing/responsiveness.md @@ -35,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/faq.md b/user/faq.md deleted file mode 100644 index cdec48a..0000000 --- a/user/faq.md +++ /dev/null @@ -1,21 +0,0 @@ -# What is a typical hub start-up time that I should expect? - -The time it takes for a user server to start, can be anywhere from a few seconds to 10min. It depends on some factors: - -## The user server can fit on a node/machine that already exists and has enough resources available to serve it. -1. If it can't fit or such a node doesn't exits, then the autoscaler will trigger the creation of a new node. - This can take up from a couple of minutes, to even 10 min or more. When the 10 minutes cap is hit, the server creation will throw a `TimeoutError` and you'll have to re-trigger the server creation process so you'll be assigned to the newly created node. Although not impossible, this is not common and we don't see it happing that often. In practice, we've noticed higher node startup times, with larger machines, like the ones with GPUs. - - The exact time it will take doesn't depend on 2i2c. Usually, it has to do with the cloud provider, machine type availability, etc. -1. If the node is already present and has enough resources, then the server creation will be much faster, taking only a few seconds. - -## The user environment, i.e. the user image chosen from the profile options, is already present on the node. -1. If the image is not present, then it will first need to be pulled on the node. - This can take a couple of minutes also, and is depending on the image size and network conditions. - When a new node has to come up, image pulling will always happen and this will add to the overall time it takes for the server to be ready. - -1. If the image is already present, then the server startup will be much faster, as it won't need to pull the image from the container registry. - -```{important} -The startup time can be reduced though different strategies, like always having a minimum number of nodes available, pre-pulling images on nodes, etc. But this will increase costs, so it's a trade-off that needs to be evaluated on a per-hub basis. More about balancing these trade-offs can be found in [](community-lead:billing:responsiveness). -``` \ No newline at end of file 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 b57ee54..9eb1e15 100644 --- a/user/index.md +++ b/user/index.md @@ -56,14 +56,12 @@ Distribute notebooks and files Contact 2i2c Support for assistance ::: -:::: - -:::{grid-item-card} Frequently Asked Questions? +:::{grid-item-card} Frequently Asked Questions :text-align: center -:link: faq +:link: basics/startup :link-type: doc -Contact 2i2c Support for assistance +Common questions about using your hub ::: :::: @@ -74,6 +72,7 @@ Contact 2i2c Support for assistance :maxdepth: 2 get-started +basics/index data/index environment/index sharing/index