From a4858da9787fba73bd9d39599221f0ea93235cb4 Mon Sep 17 00:00:00 2001 From: Andrea Zonca Date: Tue, 26 Aug 2025 17:12:01 -0700 Subject: [PATCH 01/14] Update Jetstream tutorial --- docs/install/jetstream.md | 173 ++++++++++++++------------------------ 1 file changed, 61 insertions(+), 112 deletions(-) diff --git a/docs/install/jetstream.md b/docs/install/jetstream.md index b068ca12..ae9060c5 100644 --- a/docs/install/jetstream.md +++ b/docs/install/jetstream.md @@ -1,152 +1,101 @@ (install-jetstream)= -# Installing on Jetstream +# Installing on Jetstream2 ## Goal By the end of this tutorial, you should have a JupyterHub with some admin users and a user environment with packages you want installed running on -[Jetstream](https://jetstream-cloud.org/). +[Jetstream2](https://jetstream-cloud.org/). ## Prerequisites 1. A Jetstream account with an XSEDE allocation; for more information, - see the [Jetstream Allocations help page](http://wiki.jetstream-cloud.org/Jetstream+Allocations). + see the [Jetstream Allocations help page](https://jetstream-cloud.org/allocations/). -## Step 1: Installing The Littlest JupyterHub +## Step 1: Launch a Jetstream2 instance -Let's create the server on which we can run JupyterHub. +We'll create a new Jetstream2 instance: -1. Log in to [the Jetstream portal](https://use.jetstream-cloud.org/). You need an allocation - to launch instances. +1. Log in to the [Jetstream2 portal](https://use.jetstream-cloud.org/). You must have (and select) an allocation in order to launch instances. Click the allocation you want to charge. +2. Click **Create** ➜ **Instance**. +3. From the list of images, select **Ubuntu 24.04** (Jammy or newer is required for current TLJH releases). +4. In the **Create Instance** dialog: + 1. Set a descriptive **Instance Name** (this is used in the default hostname and helps users recognize it). + 2. Choose an **Instance Size**. We suggest `m3.small` (2 vCPUs / 8 GiB RAM) or larger for more than a couple of users. The absolute minimum TLJH can start with is about **1 GiB** RAM, but you'll quickly run out with real workloads. + - See the resource estimation guide: [Choosing resources](/howto/admin/resource-estimation) for help picking CPU, RAM, and disk. + 3. (Optional) Increase the **Volume Size** if you expect many users or large datasets. You can not easily shrink later. +5. Launch the instance (click **Create Instance** / **Launch**). -2. Select the **Launch New Instance** option to get going. +## Step 2: Install The Littlest JupyterHub - ```{image} ../images/providers/jetstream/launch-instance-first-button.png - :alt: Launch new instance button with description. - ``` - - This takes you to a page with a list of base images you can choose for your - server. - -3. Under **Image Search**, search for **Ubuntu 22.04**, and select the - **Ubuntu 22.04 Devel and Docker** image. - - ```{image} ../images/providers/jetstream/select-image.png - :alt: Select Ubuntu 22.04 x64 image from image list - ``` - -4. Once selected, you will see more information about this image. Click the - **Launch** button on the top right. - - ```{image} ../images/providers/jetstream/launch-instance-second-button.png - :alt: Launch selected image with Launch button on top right - ``` - -5. A dialog titled **Launch an Instance / Basic Options** pops up, with various - options for configuring your instance. - - ```{image} ../images/providers/jetstream/launch-instance-dialog.png - :alt: Launch an Instance / Basic Options dialog box - ``` - - 1. Give your server a descriptive **Instance Name**. - - 2. Select an appropriate **Instance Size**. We suggest m1.medium or larger. - Make sure your instance has at least **1GB** of RAM. +1. Wait a few minutes for the instance to show the status "Ready" +2. Copy the **Hostname** under **Credentials**, it will be of the form: `yourinstancename.xxx0000000.projects.jetstream-cloud.org`, where `xxx000000` is the allocation ID. Keep it handy, we will use it multiple times in the next steps. - Check out our guide on How To [](/howto/admin/resource-estimation) to help pick - how much Memory, CPU & disk space your server needs. - - 3. If you have multiple allocations, make sure you are 'charging' this server - to the correct allocation. - -6. Click the **Advanced Options** link in the bottom left of the popup. This - lets us configure what the server should do when it starts up. We will use - this to install The Littlest JupyterHub. - - A dialog titled **Launch an Instance / Advanced Options** should pop up. - - ```{image} ../images/providers/jetstream/add-deployment-script-dialog.png - :alt: Dialog box allowing you to add a new script. - ``` - -7. Click the **Create New Script** button. This will open up another dialog - box! - - ```{image} ../images/providers/jetstream/create-script-dialog.png - :alt: Launch an Instance / Advanced Options dialog box - ``` - -8. Under **Input Type**, select **Raw Text**. This should make a text box titled - **Raw Text** visible on the right side of the dialog box. - Copy the text below, and paste it into the **Raw Text** text box. Replace - `` with the name of the first **admin user** for this - JupyterHub. This admin user can log in after the JupyterHub is set up, and - can configure it to their needs. **Remember to add your username**! +3. SSH into the instance with the `exouser` user: ```bash - #!/bin/bash - curl -L https://tljh.jupyter.org/bootstrap.py \ - | sudo python3 - \ - --admin + ssh exouser@yourinstancename.xxx0000000.projects.jetstream-cloud.org ``` - :::{note} - See [](/topic/installer-actions) if you want to understand exactly what the installer is doing. - [](/topic/customizing-installer) documents other options that can be passed to the installer. - ::: +4. Run the TLJH bootstrap script: -9. Under **Execution Strategy Type**, select **Run script on first boot**. + ```bash + curl -L https://tljh.jupyter.org/bootstrap.py | sudo -E python3 - --admin + ``` -10. Under **Deployment Type**, select **Wait for script to complete**. +5. Open the Hostname in a web browser (http on port 80). You should see the JupyterHub login page. Your browser will warn about the site not being secure (no HTTPS)—we'll enable HTTPS in the next step. Do not login yet, first setup HTTPS, so we avoid transmitting the password in clear text. -11. Click the **Save and Add Script** button on the bottom right. This should hide - the dialog box. +## Step 2: Enable HTTPS -12. Click the **Continue to Launch** button on the bottom right. This should put you - back in the **Launch an Instance / Basic Options** dialog box again. +Encrypted (HTTPS) access is strongly recommended before inviting users. -13. Click the **Launch Instance** button on the bottom right. This should turn it - into a spinner, and your server is getting created! +See the full guide: [Enable HTTPS](/howto/admin/https). Below is a quick recipe for using the default Jetstream-provided hostname. - ```{image} ../images/providers/jetstream/launching-spinner.png - :alt: Launch button turns into a spinner - ``` +1. In the terminal inside the instance, configure Let's Encrypt (replace with a real email you control): + ```bash + sudo tljh-config set https.enabled true + sudo tljh-config set https.letsencrypt.email you@example.com + sudo tljh-config add-item https.letsencrypt.domains yourinstancename.xxx0000000.projects.jetstream-cloud.org + sudo tljh-config reload proxy + ``` +2. Wait ~30–60 seconds, then reload the site using https://. If certificate issuance fails, check the logs: + ```bash + sudo journalctl -u traefik --since "10 minutes ago" | grep -i acme + ``` -14. You'll now be shown a dashboard with all your servers and their states. The - server you just launched will progress through various stages of set up, - and you can see the progress here. +Tips: - ```{image} ../images/providers/jetstream/deployment-in-progress.png - :alt: Instances dashboard showing deployment in progress. - ``` +- Make sure ports 80 and 443 are open in your Jetstream security group (they are open by default for new projects; adjust only if you customized network policies). +- If you later attach a custom domain, add it with another `add-item` command and reload the proxy again. -15. It will take about ten minutes for your server to come up. The status will - say **Active** and the progress bar will be a solid green. At this point, - your JupyterHub is ready for use! +## Step 3: Customize your JupyterHub deployment -16. Copy the **IP Address** of your server, and try accessing it from a web - browser. It should give you a JupyterHub login page. +1. Now log in with the `` at https://yourinstancename.xxx000000.projects.jetstream-cloud.org. Since this is the first login, you'll be prompted to set a password. Choose a strong password and store it safely. This password is now the credential for that admin user. - ```{image} ../images/first-login.png - :alt: JupyterHub log-in page - ``` +Next common tasks: -17. Login using the **admin user name** you used in step 8, and a password. Use a - strong password & note it down somewhere, since this will be the password for - the admin user account from now on. +- Add additional users or admins: [User management](/howto/admin/add-users) +- Install Python / conda packages for all users: [Customize user environment](/howto/user-env) +- Install optional system packages: `sudo apt install ` (restart user servers afterwards) +- Pre-install JupyterLab extensions: see [Enable extensions](/howto/admin/enable-extensions) +- Update TLJH itself: [Upgrading TLJH](/topic/installer-upgrade-actions) -18. Congratulations, you have a running working JupyterHub! +Browse the full How-To index for more: [/howto/index](/howto/index) -## Step 2: Adding more users +## Ask for help -```{include} add-users.md +Need a hand? -``` +- For Jetstream2 specific questions (allocations, quotas, instance lifecycle, networking, etc.), use the Jetstream support resources: +- For The Littlest JupyterHub usage, configuration, or upgrade questions, search or post in the Jupyter forum TLJH category: +- If you believe you have found a TLJH bug or have a clear documentation improvement, open an issue (or pull request if you have a proposed fix) in the TLJH GitHub repository: -## Step 3: Install conda / pip packages for all users +When asking for help about TLJH, it is often useful to provide: -```{include} add-packages.md +- A short description of what you were trying to do and what happened instead +- Relevant log excerpts (see [](/troubleshooting/logs)) +- Your TLJH version (`sudo tljh-config show | grep version` if present in config) and the output of `lsb_release -a` for the OS +- Any custom installer flags or `tljh-config` changes you have applied -``` +This information helps others debug and answer more quickly. From 512935abb777535c3ade219835a59872ab233721 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 27 Aug 2025 00:14:44 +0000 Subject: [PATCH 02/14] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- README.md | 1 - docs/contributing/dev-setup.md | 1 - docs/howto/auth/awscognito.md | 1 - docs/howto/auth/github.md | 1 - docs/howto/auth/google.md | 1 - docs/howto/user-env/user-environment.md | 1 - docs/install/azure.md | 9 --------- docs/install/jetstream.md | 8 ++++---- docs/topic/whentouse.md | 2 -- docs/troubleshooting/logs.md | 1 - 10 files changed, 4 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index a8e2d0b7..beca9083 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,6 @@ We have several tutorials to get you started. - Tutorials to create a new server from scratch on a cloud provider & run TLJH on it. These are **recommended** if you do not have much experience setting up servers. - - [Digital Ocean](https://the-littlest-jupyterhub.readthedocs.io/en/latest/install/digitalocean.html) - [OVH](https://the-littlest-jupyterhub.readthedocs.io/en/latest/install/ovh.html) - [Google Cloud](https://the-littlest-jupyterhub.readthedocs.io/en/latest/install/google.html) diff --git a/docs/contributing/dev-setup.md b/docs/contributing/dev-setup.md index 33367238..ff1b6f1d 100644 --- a/docs/contributing/dev-setup.md +++ b/docs/contributing/dev-setup.md @@ -61,7 +61,6 @@ The easiest & safest way to develop & test TLJH is with [Docker](https://www.doc 8. Make some changes to the repository. You can test easily depending on what you changed. - - If you changed the `bootstrap/bootstrap.py` script or any of its dependencies, you can test it by running `python3 /srv/src/bootstrap/bootstrap.py`. - If you changed the `tljh/installer.py` code (or any of its dependencies), diff --git a/docs/howto/auth/awscognito.md b/docs/howto/auth/awscognito.md index 2e89fa4c..4d39f53a 100644 --- a/docs/howto/auth/awscognito.md +++ b/docs/howto/auth/awscognito.md @@ -24,7 +24,6 @@ application to your `tljh` configuration. 1. Create a user pool [Getting Started with User Pool](https://docs.aws.amazon.com/cognito/latest/developerguide/getting-started-with-cognito-user-pools.html). When you have completed creating a user pool, app, and domain you should have the following settings available to you: - - **App client id**: From the App client page - **App client secret** From the App client page diff --git a/docs/howto/auth/github.md b/docs/howto/auth/github.md index 2e5baf5a..70487385 100644 --- a/docs/howto/auth/github.md +++ b/docs/howto/auth/github.md @@ -26,7 +26,6 @@ You'll need a GitHub account in order to complete these steps. ## Step 1: Create a GitHub application 1. Go to the [GitHub OAuth app creation page](https://github.com/settings/applications/new). - - **Application name**: Choose a descriptive application name (e.g. `tljh`) - **Homepage URL**: Use the IP address or URL of your JupyterHub. e.g. `` http(s)://` ``. diff --git a/docs/howto/auth/google.md b/docs/howto/auth/google.md index 2d74893a..e7637493 100644 --- a/docs/howto/auth/google.md +++ b/docs/howto/auth/google.md @@ -51,7 +51,6 @@ and create a new project: ``` - You will have to fill a form with: - - **Application type**: Choose _Web application_ - **Name**: A descriptive name for your OAuth client ID (e.g. `tljh-client`) diff --git a/docs/howto/user-env/user-environment.md b/docs/howto/user-env/user-environment.md index 74b72856..41c25451 100644 --- a/docs/howto/user-env/user-environment.md +++ b/docs/howto/user-env/user-environment.md @@ -180,7 +180,6 @@ To upgrade the Python version of the user environment, one can: environment, but you may do so manually. **Steps:** - 1. Activate the user environment, if using ssh. If the terminal was started with JupyterHub, this step can be skipped: diff --git a/docs/install/azure.md b/docs/install/azure.md index a9f862f2..752cf8fd 100644 --- a/docs/install/azure.md +++ b/docs/install/azure.md @@ -51,7 +51,6 @@ We start by creating the Virtual Machine in which we can run TLJH (The Littlest ``` 5. **Choose an Ubuntu server for your VM**: - - Click `Ubuntu Server 22.04 LTS.` - Make sure `Resource Manager` is selected in the next screen and click **Create** @@ -61,7 +60,6 @@ We start by creating the Virtual Machine in which we can run TLJH (The Littlest ``` 6. Customise the Virtual Machine basics: - - **Subscription**. Choose the "Free Trial" if this is what you're using. Otherwise, choose a different plan. This is the billing account that will be charged. - **Resource group**. Resource groups let you keep your Azure tools/resources together in an availability region (e.g. WestEurope). If you already have one you'd like to use it select that resource. @@ -89,7 +87,6 @@ We start by creating the Virtual Machine in which we can run TLJH (The Littlest - **Inbound port rules**. Leave the defaults for now, and we will update these later on in the Network configuration step. 7. Before clicking on "Next" we need to select the RAM size for the image. - - For this we need to make sure we have enough RAM to accommodate your users. For example, if each user needs 2GB of RAM, and you have 10 total users, you need at least 20GB of RAM on the machine. It's also good to have a few GB of "buffer" RAM beyond what you think you'll need. - Click on **Change size** (see image below) @@ -105,7 +102,6 @@ We start by creating the Virtual Machine in which we can run TLJH (The Littlest - Select a suitable image (to check available images and prices in your region [click on this link](https://azuremarketplace.microsoft.com/en-gb/marketplace/apps/Canonical.UbuntuServer?tab=PlansAndPrice/?wt.mc_id=TLJH-github-taallard)). 8. Disks (Storage): - - **Disk options**: select the OS disk type there are options for SDD and HDD. **SSD persistent disk** gives you a faster but more expensive disk than HDD. - **Data disk**. Click on create and attach a new disk. Select an appropriate type and size and click ok. @@ -120,7 +116,6 @@ We start by creating the Virtual Machine in which we can run TLJH (The Littlest ``` 9. Networking - - **Virtual network**. Leave the default values selected. - **Subnet**. Leave the default values selected. - **Public IP address**.Leave the default values selected. This will make your server accessible from a browser. @@ -132,9 +127,7 @@ We start by creating the Virtual Machine in which we can run TLJH (The Littlest ``` 10. Management - - Monitoring - - **Boot diagnostics**. Choose "On". - **OS guest diagnostics**. Choose "Off". - **Diagnostics storage account**. Leave as the default. @@ -150,7 +143,6 @@ We start by creating the Virtual Machine in which we can run TLJH (The Littlest ``` 11. Advanced settings - - **Extensions**. Make sure there are no extensions listed - **Cloud init**. We are going to use this section to install TLJH directly into our Virtual Machine. @@ -177,7 +169,6 @@ We start by creating the Virtual Machine in which we can run TLJH (The Littlest 12. Check the summary and confirm the creation of your Virtual Machine. 13. Check that the creation of your Virtual Machine worked. - - Wait for the virtual machine to be created. This might take about 5-10 minutes. - After completion, you should see a similar screen to the one below: diff --git a/docs/install/jetstream.md b/docs/install/jetstream.md index ae9060c5..9d5223b5 100644 --- a/docs/install/jetstream.md +++ b/docs/install/jetstream.md @@ -34,9 +34,9 @@ We'll create a new Jetstream2 instance: 3. SSH into the instance with the `exouser` user: - ```bash - ssh exouser@yourinstancename.xxx0000000.projects.jetstream-cloud.org - ``` + ```bash + ssh exouser@yourinstancename.xxx0000000.projects.jetstream-cloud.org + ``` 4. Run the TLJH bootstrap script: @@ -44,7 +44,7 @@ We'll create a new Jetstream2 instance: curl -L https://tljh.jupyter.org/bootstrap.py | sudo -E python3 - --admin ``` -5. Open the Hostname in a web browser (http on port 80). You should see the JupyterHub login page. Your browser will warn about the site not being secure (no HTTPS)—we'll enable HTTPS in the next step. Do not login yet, first setup HTTPS, so we avoid transmitting the password in clear text. +5. Open the Hostname in a web browser (http on port 80). You should see the JupyterHub login page. Your browser will warn about the site not being secure (no HTTPS)—we'll enable HTTPS in the next step. Do not login yet, first setup HTTPS, so we avoid transmitting the password in clear text. ## Step 2: Enable HTTPS diff --git a/docs/topic/whentouse.md b/docs/topic/whentouse.md index d404da36..010c5dc8 100644 --- a/docs/topic/whentouse.md +++ b/docs/topic/whentouse.md @@ -22,11 +22,9 @@ container technology in administering user sessions. The choice between TLJH and Z2JH ultimately comes down to only a few questions: 1. Do you want your hub and all users to live on a **single, larger machine** vs. spreading users on a **cluster of smaller machines** that are scaled up or down? - - If you can use a single machine, we recommend **The Littlest JupyterHub**. - If you wish to use multiple machines, we recommend **Zero to JupyterHub for Kubernetes**. 2. Do you **need to use container technology**? - - If no, we recommend **The Littlest JupyterHub**. - If yes, we recommend **Zero to JupyterHub for Kubernetes**. diff --git a/docs/troubleshooting/logs.md b/docs/troubleshooting/logs.md index b4884942..e7c968dc 100644 --- a/docs/troubleshooting/logs.md +++ b/docs/troubleshooting/logs.md @@ -81,7 +81,6 @@ easier. Here are some very basic tips on effective `journalctl` usage. [less](). This allows you to scroll up / down, search for specific words, etc. Some common keyboard shortcuts are: - - Arrow keys to move up / down / left / right - `G` to navigate to the end of the logs - `g` to navigate to the start of the logs From ae503c30962f28afc6470efb82a7f852d950cdac Mon Sep 17 00:00:00 2001 From: Andrea Zonca Date: Tue, 26 Aug 2025 17:16:55 -0700 Subject: [PATCH 03/14] Clarify instructions for running the TLJH bootstrap script in the Jetstream installation guide --- docs/install/jetstream.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/install/jetstream.md b/docs/install/jetstream.md index 9d5223b5..9bb2a1b3 100644 --- a/docs/install/jetstream.md +++ b/docs/install/jetstream.md @@ -38,13 +38,13 @@ We'll create a new Jetstream2 instance: ssh exouser@yourinstancename.xxx0000000.projects.jetstream-cloud.org ``` -4. Run the TLJH bootstrap script: +4. Run the TLJH bootstrap script, replace with the name of the first admin user for this JupyterHub. Choose any name you like (don’t forget to remove the brackets!). This admin user can log in after the JupyterHub is set up, and can configure it to their needs. ```bash curl -L https://tljh.jupyter.org/bootstrap.py | sudo -E python3 - --admin ``` -5. Open the Hostname in a web browser (http on port 80). You should see the JupyterHub login page. Your browser will warn about the site not being secure (no HTTPS)—we'll enable HTTPS in the next step. Do not login yet, first setup HTTPS, so we avoid transmitting the password in clear text. +5. Open the Hostname in a web browser (http on port 80). You should see the JupyterHub login page. Your browser will warn about the site not being secure (no HTTPS)—we'll enable HTTPS in the next step. Do not login yet, first setup HTTPS, so we avoid transmitting the password in clear text. ## Step 2: Enable HTTPS From 4807b7da8943da3ad7ac5f3fdce90540298df3cc Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 27 Aug 2025 00:18:19 +0000 Subject: [PATCH 04/14] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/install/jetstream.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/jetstream.md b/docs/install/jetstream.md index 9bb2a1b3..6a81a53e 100644 --- a/docs/install/jetstream.md +++ b/docs/install/jetstream.md @@ -44,7 +44,7 @@ We'll create a new Jetstream2 instance: curl -L https://tljh.jupyter.org/bootstrap.py | sudo -E python3 - --admin ``` -5. Open the Hostname in a web browser (http on port 80). You should see the JupyterHub login page. Your browser will warn about the site not being secure (no HTTPS)—we'll enable HTTPS in the next step. Do not login yet, first setup HTTPS, so we avoid transmitting the password in clear text. +5. Open the Hostname in a web browser (http on port 80). You should see the JupyterHub login page. Your browser will warn about the site not being secure (no HTTPS)—we'll enable HTTPS in the next step. Do not login yet, first setup HTTPS, so we avoid transmitting the password in clear text. ## Step 2: Enable HTTPS From e6851d946d66ef54aaea8dcf0c95d892ba5210ba Mon Sep 17 00:00:00 2001 From: Andrea Zonca Date: Tue, 23 Sep 2025 22:05:19 -0700 Subject: [PATCH 05/14] Apply suggestions from code review Co-authored-by: Julian Pistorius --- docs/install/jetstream.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/install/jetstream.md b/docs/install/jetstream.md index 6a81a53e..1f0754a4 100644 --- a/docs/install/jetstream.md +++ b/docs/install/jetstream.md @@ -75,20 +75,19 @@ Tips: Next common tasks: -- Add additional users or admins: [User management](/howto/admin/add-users) -- Install Python / conda packages for all users: [Customize user environment](/howto/user-env) -- Install optional system packages: `sudo apt install ` (restart user servers afterwards) -- Pre-install JupyterLab extensions: see [Enable extensions](/howto/admin/enable-extensions) -- Update TLJH itself: [Upgrading TLJH](/topic/installer-upgrade-actions) +- [](howto-admin-admin-users) +- [](howto-user-env-user-environment-apt) +- [](howto-admin-enable-extensions) +- [][topic-installer-upgrade-actions) -Browse the full How-To index for more: [/howto/index](/howto/index) +Browse the full [How-To index](/howto/index) for more. ## Ask for help Need a hand? -- For Jetstream2 specific questions (allocations, quotas, instance lifecycle, networking, etc.), use the Jetstream support resources: -- For The Littlest JupyterHub usage, configuration, or upgrade questions, search or post in the Jupyter forum TLJH category: +- For Jetstream2 specific questions (allocations, quotas, instance lifecycle, networking, etc.), use the [Jetstream support resources](https://docs.jetstream-cloud.org/overview/support/). +- For The Littlest JupyterHub usage, configuration, or upgrade questions, search or post in the [Jupyter forum TLJH category](https://discourse.jupyter.org/c/jupyterhub/tljh). - If you believe you have found a TLJH bug or have a clear documentation improvement, open an issue (or pull request if you have a proposed fix) in the TLJH GitHub repository: When asking for help about TLJH, it is often useful to provide: From c3703985ee64010a9014c112b0c9b491703be982 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 24 Sep 2025 05:05:29 +0000 Subject: [PATCH 06/14] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/install/jetstream.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/jetstream.md b/docs/install/jetstream.md index 1f0754a4..921bc08b 100644 --- a/docs/install/jetstream.md +++ b/docs/install/jetstream.md @@ -78,7 +78,7 @@ Next common tasks: - [](howto-admin-admin-users) - [](howto-user-env-user-environment-apt) - [](howto-admin-enable-extensions) -- [][topic-installer-upgrade-actions) +- []topic-installer-upgrade-actions) Browse the full [How-To index](/howto/index) for more. From 519415395f39aeae7b1c144bcc06c807c29d271e Mon Sep 17 00:00:00 2001 From: Andrea Zonca Date: Tue, 23 Sep 2025 22:06:52 -0700 Subject: [PATCH 07/14] Apply suggestion from @julianpistorius Co-authored-by: Julian Pistorius --- docs/install/jetstream.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/jetstream.md b/docs/install/jetstream.md index 921bc08b..5eb75b1b 100644 --- a/docs/install/jetstream.md +++ b/docs/install/jetstream.md @@ -88,7 +88,7 @@ Need a hand? - For Jetstream2 specific questions (allocations, quotas, instance lifecycle, networking, etc.), use the [Jetstream support resources](https://docs.jetstream-cloud.org/overview/support/). - For The Littlest JupyterHub usage, configuration, or upgrade questions, search or post in the [Jupyter forum TLJH category](https://discourse.jupyter.org/c/jupyterhub/tljh). -- If you believe you have found a TLJH bug or have a clear documentation improvement, open an issue (or pull request if you have a proposed fix) in the TLJH GitHub repository: +- If you believe you have found a TLJH bug or have a clear documentation improvement, open an issue (or pull request if you have a proposed fix) in the [TLJH GitHub repository](https://github.com/jupyterhub/the-littlest-jupyterhub). When asking for help about TLJH, it is often useful to provide: From 45bec8e9f83945e0734c9d4f42ce4930c520bacb Mon Sep 17 00:00:00 2001 From: Andrea Zonca Date: Tue, 23 Sep 2025 22:07:13 -0700 Subject: [PATCH 08/14] Apply suggestion from @julianpistorius Co-authored-by: Julian Pistorius --- docs/install/jetstream.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/jetstream.md b/docs/install/jetstream.md index 5eb75b1b..b1b6caa3 100644 --- a/docs/install/jetstream.md +++ b/docs/install/jetstream.md @@ -22,7 +22,7 @@ We'll create a new Jetstream2 instance: 3. From the list of images, select **Ubuntu 24.04** (Jammy or newer is required for current TLJH releases). 4. In the **Create Instance** dialog: 1. Set a descriptive **Instance Name** (this is used in the default hostname and helps users recognize it). - 2. Choose an **Instance Size**. We suggest `m3.small` (2 vCPUs / 8 GiB RAM) or larger for more than a couple of users. The absolute minimum TLJH can start with is about **1 GiB** RAM, but you'll quickly run out with real workloads. + 2. Choose an **Instance Size**. We suggest `m3.small` (2 vCPUs / 6 GiB RAM) or larger for more than a couple of users. The absolute minimum TLJH can start with is about **1 GiB** RAM, but you'll quickly run out with real workloads. - See the resource estimation guide: [Choosing resources](/howto/admin/resource-estimation) for help picking CPU, RAM, and disk. 3. (Optional) Increase the **Volume Size** if you expect many users or large datasets. You can not easily shrink later. 5. Launch the instance (click **Create Instance** / **Launch**). From c639c75637e9b452553421d28c4ced1cc01b05da Mon Sep 17 00:00:00 2001 From: Andrea Zonca Date: Tue, 23 Sep 2025 22:07:20 -0700 Subject: [PATCH 09/14] Apply suggestion from @julianpistorius Co-authored-by: Julian Pistorius --- docs/install/jetstream.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/jetstream.md b/docs/install/jetstream.md index b1b6caa3..eb95e4dd 100644 --- a/docs/install/jetstream.md +++ b/docs/install/jetstream.md @@ -25,7 +25,7 @@ We'll create a new Jetstream2 instance: 2. Choose an **Instance Size**. We suggest `m3.small` (2 vCPUs / 6 GiB RAM) or larger for more than a couple of users. The absolute minimum TLJH can start with is about **1 GiB** RAM, but you'll quickly run out with real workloads. - See the resource estimation guide: [Choosing resources](/howto/admin/resource-estimation) for help picking CPU, RAM, and disk. 3. (Optional) Increase the **Volume Size** if you expect many users or large datasets. You can not easily shrink later. -5. Launch the instance (click **Create Instance** / **Launch**). +5. Launch the instance (click **Create** button at the bottom of the form). ## Step 2: Install The Littlest JupyterHub From 684481fd5de0e634f8da5a512e81e39083020f0a Mon Sep 17 00:00:00 2001 From: Andrea Zonca Date: Tue, 23 Sep 2025 22:07:32 -0700 Subject: [PATCH 10/14] Apply suggestion from @julianpistorius Co-authored-by: Julian Pistorius --- docs/install/jetstream.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/install/jetstream.md b/docs/install/jetstream.md index eb95e4dd..029a5a32 100644 --- a/docs/install/jetstream.md +++ b/docs/install/jetstream.md @@ -72,6 +72,12 @@ Tips: ## Step 3: Customize your JupyterHub deployment 1. Now log in with the `` at https://yourinstancename.xxx000000.projects.jetstream-cloud.org. Since this is the first login, you'll be prompted to set a password. Choose a strong password and store it safely. This password is now the credential for that admin user. +2. Congratulations, you have a running working JupyterHub! + +## Step 4: Adding more users + +```{include} add-users.md + Next common tasks: From 0cd259b6a119a187fb5faeda2ea345a34126ee68 Mon Sep 17 00:00:00 2001 From: Andrea Zonca Date: Tue, 23 Sep 2025 22:07:42 -0700 Subject: [PATCH 11/14] Apply suggestion from @julianpistorius Co-authored-by: Julian Pistorius --- docs/install/jetstream.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/jetstream.md b/docs/install/jetstream.md index 029a5a32..4ec5b223 100644 --- a/docs/install/jetstream.md +++ b/docs/install/jetstream.md @@ -69,7 +69,7 @@ Tips: - Make sure ports 80 and 443 are open in your Jetstream security group (they are open by default for new projects; adjust only if you customized network policies). - If you later attach a custom domain, add it with another `add-item` command and reload the proxy again. -## Step 3: Customize your JupyterHub deployment +## Step 3: Log in as the administrative user and set a password 1. Now log in with the `` at https://yourinstancename.xxx000000.projects.jetstream-cloud.org. Since this is the first login, you'll be prompted to set a password. Choose a strong password and store it safely. This password is now the credential for that admin user. 2. Congratulations, you have a running working JupyterHub! From 752f605c53b62fc2de36ac1fbf029e47369811f8 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 24 Sep 2025 05:07:43 +0000 Subject: [PATCH 12/14] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/install/jetstream.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/install/jetstream.md b/docs/install/jetstream.md index 4ec5b223..b028cdae 100644 --- a/docs/install/jetstream.md +++ b/docs/install/jetstream.md @@ -104,3 +104,4 @@ When asking for help about TLJH, it is often useful to provide: - Any custom installer flags or `tljh-config` changes you have applied This information helps others debug and answer more quickly. +``` From 6b2d93aacf4275ad828ac8f7d93e9af7c4330cf9 Mon Sep 17 00:00:00 2001 From: Andrea Zonca Date: Tue, 23 Sep 2025 22:09:31 -0700 Subject: [PATCH 13/14] Apply suggestion from @julianpistorius Co-authored-by: Julian Pistorius --- docs/install/jetstream.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/jetstream.md b/docs/install/jetstream.md index b028cdae..ffb9c1f5 100644 --- a/docs/install/jetstream.md +++ b/docs/install/jetstream.md @@ -52,7 +52,7 @@ Encrypted (HTTPS) access is strongly recommended before inviting users. See the full guide: [Enable HTTPS](/howto/admin/https). Below is a quick recipe for using the default Jetstream-provided hostname. -1. In the terminal inside the instance, configure Let's Encrypt (replace with a real email you control): +1. In the terminal inside the instance, configure Let's Encrypt (replace with a real email you control, and the correct hostname): ```bash sudo tljh-config set https.enabled true sudo tljh-config set https.letsencrypt.email you@example.com From 72967f2b17ff0f8c9330921cd492919c0a54fcb8 Mon Sep 17 00:00:00 2001 From: Andrea Zonca Date: Tue, 23 Sep 2025 22:21:09 -0700 Subject: [PATCH 14/14] Document how to reveal exouser passphrase in Exosphere --- docs/install/jetstream.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/install/jetstream.md b/docs/install/jetstream.md index ffb9c1f5..6378868a 100644 --- a/docs/install/jetstream.md +++ b/docs/install/jetstream.md @@ -38,6 +38,11 @@ We'll create a new Jetstream2 instance: ssh exouser@yourinstancename.xxx0000000.projects.jetstream-cloud.org ``` + Need the passphrase? In Exosphere, open **Instances**, select your + JupyterHub instance, and expand **Credentials**. Click **Show Passphrase** + next to the `exouser` entry to reveal or copy it before running the + `ssh` command. + 4. Run the TLJH bootstrap script, replace with the name of the first admin user for this JupyterHub. Choose any name you like (don’t forget to remove the brackets!). This admin user can log in after the JupyterHub is set up, and can configure it to their needs. ```bash