Skip to content

Commit a4858da

Browse files
zoncazonca
committed
Update Jetstream tutorial
1 parent 134ddd9 commit a4858da

File tree

1 file changed

+61
-112
lines changed

1 file changed

+61
-112
lines changed

‎docs/install/jetstream.md‎

Lines changed: 61 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -1,152 +1,101 @@
11
(install-jetstream)=
22

3-
# Installing on Jetstream
3+
# Installing on Jetstream2
44

55
## Goal
66

77
By the end of this tutorial, you should have a JupyterHub with some admin
88
users and a user environment with packages you want installed running on
9-
[Jetstream](https://jetstream-cloud.org/).
9+
[Jetstream2](https://jetstream-cloud.org/).
1010

1111
## Prerequisites
1212

1313
1. A Jetstream account with an XSEDE allocation; for more information,
14-
see the [Jetstream Allocations help page](http://wiki.jetstream-cloud.org/Jetstream+Allocations).
14+
see the [Jetstream Allocations help page](https://jetstream-cloud.org/allocations/).
1515

16-
## Step 1: Installing The Littlest JupyterHub
16+
## Step 1: Launch a Jetstream2 instance
1717

18-
Let's create the server on which we can run JupyterHub.
18+
We'll create a new Jetstream2 instance:
1919

20-
1. Log in to [the Jetstream portal](https://use.jetstream-cloud.org/). You need an allocation
21-
to launch instances.
20+
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.
21+
2. Click **Create** ➜ **Instance**.
22+
3. From the list of images, select **Ubuntu 24.04** (Jammy or newer is required for current TLJH releases).
23+
4. In the **Create Instance** dialog:
24+
1. Set a descriptive **Instance Name** (this is used in the default hostname and helps users recognize it).
25+
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.
26+
- See the resource estimation guide: [Choosing resources](/howto/admin/resource-estimation) for help picking CPU, RAM, and disk.
27+
3. (Optional) Increase the **Volume Size** if you expect many users or large datasets. You can not easily shrink later.
28+
5. Launch the instance (click **Create Instance** / **Launch**).
2229

23-
2. Select the **Launch New Instance** option to get going.
30+
## Step 2: Install The Littlest JupyterHub
2431

25-
```{image} ../images/providers/jetstream/launch-instance-first-button.png
26-
:alt: Launch new instance button with description.
27-
```
28-
29-
This takes you to a page with a list of base images you can choose for your
30-
server.
31-
32-
3. Under **Image Search**, search for **Ubuntu 22.04**, and select the
33-
**Ubuntu 22.04 Devel and Docker** image.
34-
35-
```{image} ../images/providers/jetstream/select-image.png
36-
:alt: Select Ubuntu 22.04 x64 image from image list
37-
```
38-
39-
4. Once selected, you will see more information about this image. Click the
40-
**Launch** button on the top right.
41-
42-
```{image} ../images/providers/jetstream/launch-instance-second-button.png
43-
:alt: Launch selected image with Launch button on top right
44-
```
45-
46-
5. A dialog titled **Launch an Instance / Basic Options** pops up, with various
47-
options for configuring your instance.
48-
49-
```{image} ../images/providers/jetstream/launch-instance-dialog.png
50-
:alt: Launch an Instance / Basic Options dialog box
51-
```
52-
53-
1. Give your server a descriptive **Instance Name**.
54-
55-
2. Select an appropriate **Instance Size**. We suggest m1.medium or larger.
56-
Make sure your instance has at least **1GB** of RAM.
32+
1. Wait a few minutes for the instance to show the status "Ready"
33+
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.
5734

58-
Check out our guide on How To [](/howto/admin/resource-estimation) to help pick
59-
how much Memory, CPU & disk space your server needs.
60-
61-
3. If you have multiple allocations, make sure you are 'charging' this server
62-
to the correct allocation.
63-
64-
6. Click the **Advanced Options** link in the bottom left of the popup. This
65-
lets us configure what the server should do when it starts up. We will use
66-
this to install The Littlest JupyterHub.
67-
68-
A dialog titled **Launch an Instance / Advanced Options** should pop up.
69-
70-
```{image} ../images/providers/jetstream/add-deployment-script-dialog.png
71-
:alt: Dialog box allowing you to add a new script.
72-
```
73-
74-
7. Click the **Create New Script** button. This will open up another dialog
75-
box!
76-
77-
```{image} ../images/providers/jetstream/create-script-dialog.png
78-
:alt: Launch an Instance / Advanced Options dialog box
79-
```
80-
81-
8. Under **Input Type**, select **Raw Text**. This should make a text box titled
82-
**Raw Text** visible on the right side of the dialog box.
83-
Copy the text below, and paste it into the **Raw Text** text box. Replace
84-
`<admin-user-name>` with the name of the first **admin user** for this
85-
JupyterHub. This admin user can log in after the JupyterHub is set up, and
86-
can configure it to their needs. **Remember to add your username**!
35+
3. SSH into the instance with the `exouser` user:
8736

8837
```bash
89-
#!/bin/bash
90-
curl -L https://tljh.jupyter.org/bootstrap.py \
91-
| sudo python3 - \
92-
--admin <admin-user-name>
38+
ssh [email protected]
9339
```
9440

95-
:::{note}
96-
See [](/topic/installer-actions) if you want to understand exactly what the installer is doing.
97-
[](/topic/customizing-installer) documents other options that can be passed to the installer.
98-
:::
41+
4. Run the TLJH bootstrap script:
9942

100-
9. Under **Execution Strategy Type**, select **Run script on first boot**.
43+
```bash
44+
curl -L https://tljh.jupyter.org/bootstrap.py | sudo -E python3 - --admin <admin-user-name>
45+
```
10146

102-
10. Under **Deployment Type**, select **Wait for script to complete**.
47+
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.
10348
104-
11. Click the **Save and Add Script** button on the bottom right. This should hide
105-
the dialog box.
49+
## Step 2: Enable HTTPS
10650
107-
12. Click the **Continue to Launch** button on the bottom right. This should put you
108-
back in the **Launch an Instance / Basic Options** dialog box again.
51+
Encrypted (HTTPS) access is strongly recommended before inviting users.
10952
110-
13. Click the **Launch Instance** button on the bottom right. This should turn it
111-
into a spinner, and your server is getting created!
53+
See the full guide: [Enable HTTPS](/howto/admin/https). Below is a quick recipe for using the default Jetstream-provided hostname.
11254
113-
```{image} ../images/providers/jetstream/launching-spinner.png
114-
:alt: Launch button turns into a spinner
115-
```
55+
1. In the terminal inside the instance, configure Let's Encrypt (replace with a real email you control):
56+
```bash
57+
sudo tljh-config set https.enabled true
58+
sudo tljh-config set https.letsencrypt.email [email protected]
59+
sudo tljh-config add-item https.letsencrypt.domains yourinstancename.xxx0000000.projects.jetstream-cloud.org
60+
sudo tljh-config reload proxy
61+
```
62+
2. Wait ~30–60 seconds, then reload the site using https://. If certificate issuance fails, check the logs:
63+
```bash
64+
sudo journalctl -u traefik --since "10 minutes ago" | grep -i acme
65+
```
11666

117-
14. You'll now be shown a dashboard with all your servers and their states. The
118-
server you just launched will progress through various stages of set up,
119-
and you can see the progress here.
67+
Tips:
12068

121-
```{image} ../images/providers/jetstream/deployment-in-progress.png
122-
:alt: Instances dashboard showing deployment in progress.
123-
```
69+
- 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).
70+
- If you later attach a custom domain, add it with another `add-item` command and reload the proxy again.
12471

125-
15. It will take about ten minutes for your server to come up. The status will
126-
say **Active** and the progress bar will be a solid green. At this point,
127-
your JupyterHub is ready for use!
72+
## Step 3: Customize your JupyterHub deployment
12873

129-
16. Copy the **IP Address** of your server, and try accessing it from a web
130-
browser. It should give you a JupyterHub login page.
74+
1. Now log in with the `<admin-user-name>` 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.
13175
132-
```{image} ../images/first-login.png
133-
:alt: JupyterHub log-in page
134-
```
76+
Next common tasks:
13577
136-
17. Login using the **admin user name** you used in step 8, and a password. Use a
137-
strong password & note it down somewhere, since this will be the password for
138-
the admin user account from now on.
78+
- Add additional users or admins: [User management](/howto/admin/add-users)
79+
- Install Python / conda packages for all users: [Customize user environment](/howto/user-env)
80+
- Install optional system packages: `sudo apt install <package>` (restart user servers afterwards)
81+
- Pre-install JupyterLab extensions: see [Enable extensions](/howto/admin/enable-extensions)
82+
- Update TLJH itself: [Upgrading TLJH](/topic/installer-upgrade-actions)
13983
140-
18. Congratulations, you have a running working JupyterHub!
84+
Browse the full How-To index for more: [/howto/index](/howto/index)
14185
142-
## Step 2: Adding more users
86+
## Ask for help
14387
144-
```{include} add-users.md
88+
Need a hand?
14589
146-
```
90+
- For Jetstream2 specific questions (allocations, quotas, instance lifecycle, networking, etc.), use the Jetstream support resources: <https://docs.jetstream-cloud.org/overview/support/>
91+
- 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>
92+
- 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>
14793
148-
## Step 3: Install conda / pip packages for all users
94+
When asking for help about TLJH, it is often useful to provide:
14995
150-
```{include} add-packages.md
96+
- A short description of what you were trying to do and what happened instead
97+
- Relevant log excerpts (see [](/troubleshooting/logs))
98+
- Your TLJH version (`sudo tljh-config show | grep version` if present in config) and the output of `lsb_release -a` for the OS
99+
- Any custom installer flags or `tljh-config` changes you have applied
151100
152-
```
101+
This information helps others debug and answer more quickly.

0 commit comments

Comments
 (0)