Skip to content

Commit 8b55d5f

Browse files
minrkminrk
authored
Merge pull request #1038 from zonca/update-jetstream-docs
Update jetstream docs
2 parents c9d971b + 79adc7d commit 8b55d5f

File tree

1 file changed

+70
-110
lines changed

1 file changed

+70
-110
lines changed

‎docs/install/jetstream.md‎

Lines changed: 70 additions & 110 deletions
Original file line numberDiff line numberDiff line change
@@ -1,152 +1,112 @@
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

13-
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).
13+
1. An ACCESS ID, and membership in an allocation with access to Jetstream2 resources; for more information,
14+
see the [Jetstream2 Allocations Overview page](https://docs.jetstream-cloud.org/alloc/overview/) and the [Get started with Jetstream2 guide](https://jetstream-cloud.org/get-started/).
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 / 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.
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** button at the bottom of the form).
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-
```
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.
2834

29-
This takes you to a page with a list of base images you can choose for your
30-
server.
35+
3. SSH into the instance with the `exouser` user:
3136

32-
3. Under **Image Search**, search for **Ubuntu 22.04**, and select the
33-
**Ubuntu 22.04 Devel and Docker** image.
37+
```bash
38+
ssh [email protected]
39+
```
3440

35-
```{image} ../images/providers/jetstream/select-image.png
36-
:alt: Select Ubuntu 22.04 x64 image from image list
37-
```
41+
Need the passphrase? In Exosphere, open **Instances**, select your
42+
JupyterHub instance, and expand **Credentials**. Click **Show Passphrase**
43+
next to the `exouser` entry to reveal or copy it before running the
44+
`ssh` command.
3845

39-
4. Once selected, you will see more information about this image. Click the
40-
**Launch** button on the top right.
46+
4. Run the TLJH bootstrap script, replace <admin-user-name> 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.
4147

42-
```{image} ../images/providers/jetstream/launch-instance-second-button.png
43-
:alt: Launch selected image with Launch button on top right
44-
```
48+
```bash
49+
curl -L https://tljh.jupyter.org/bootstrap.py | sudo -E python3 - --admin <admin-user-name>
50+
```
4551

46-
5. A dialog titled **Launch an Instance / Basic Options** pops up, with various
47-
options for configuring your instance.
52+
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.
4853

49-
```{image} ../images/providers/jetstream/launch-instance-dialog.png
50-
:alt: Launch an Instance / Basic Options dialog box
51-
```
54+
## Step 2: Enable HTTPS
5255

53-
1. Give your server a descriptive **Instance Name**.
56+
Encrypted (HTTPS) access is strongly recommended before inviting users.
5457

55-
2. Select an appropriate **Instance Size**. We suggest m1.medium or larger.
56-
Make sure your instance has at least **1GB** of RAM.
58+
See the full guide: [Enable HTTPS](/howto/admin/https). Below is a quick recipe for using the default Jetstream-provided hostname.
5759

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+
1. In the terminal inside the instance, configure Let's Encrypt (replace with a real email you control, and the correct hostname):
61+
```bash
62+
sudo tljh-config set https.enabled true
63+
sudo tljh-config set https.letsencrypt.email [email protected]
64+
sudo tljh-config add-item https.letsencrypt.domains yourinstancename.xxx0000000.projects.jetstream-cloud.org
65+
sudo tljh-config reload proxy
66+
```
67+
2. Wait ~30–60 seconds, then reload the site using https://. If certificate issuance fails, check the logs:
68+
```bash
69+
sudo journalctl -u traefik --since "10 minutes ago" | grep -i acme
70+
```
6071

61-
3. If you have multiple allocations, make sure you are 'charging' this server
62-
to the correct allocation.
72+
Tips:
6373

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.
74+
- 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).
75+
- If you later attach a custom domain, add it with another `add-item` command and reload the proxy again.
6776

68-
A dialog titled **Launch an Instance / Advanced Options** should pop up.
77+
## Step 3: Log in as the administrative user and set a password
6978

70-
```{image} ../images/providers/jetstream/add-deployment-script-dialog.png
71-
:alt: Dialog box allowing you to add a new script.
72-
```
79+
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.
80+
2. Congratulations, you have a running working JupyterHub!
7381

74-
7. Click the **Create New Script** button. This will open up another dialog
75-
box!
82+
## Step 4: Adding more users
7683

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**!
87-
88-
```bash
89-
#!/bin/bash
90-
curl -L https://tljh.jupyter.org/bootstrap.py \
91-
| sudo python3 - \
92-
--admin <admin-user-name>
93-
```
94-
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-
:::
99-
100-
9. Under **Execution Strategy Type**, select **Run script on first boot**.
101-
102-
10. Under **Deployment Type**, select **Wait for script to complete**.
103-
104-
11. Click the **Save and Add Script** button on the bottom right. This should hide
105-
the dialog box.
106-
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.
109-
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!
112-
113-
```{image} ../images/providers/jetstream/launching-spinner.png
114-
:alt: Launch button turns into a spinner
115-
```
116-
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.
120-
121-
```{image} ../images/providers/jetstream/deployment-in-progress.png
122-
:alt: Instances dashboard showing deployment in progress.
123-
```
124-
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!
84+
```{include} add-users.md
12885
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.
13186
132-
```{image} ../images/first-login.png
133-
:alt: JupyterHub log-in page
134-
```
87+
Next common tasks:
13588
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.
89+
- [](howto-admin-admin-users)
90+
- [](howto-user-env-user-environment-apt)
91+
- [](howto-admin-enable-extensions)
92+
- []topic-installer-upgrade-actions)
13993
140-
18. Congratulations, you have a running working JupyterHub!
94+
Browse the full [How-To index](/howto/index) for more.
14195
142-
## Step 2: Adding more users
96+
## Ask for help
14397
144-
```{include} add-users.md
98+
Need a hand?
14599
146-
```
100+
- For Jetstream2 specific questions (allocations, quotas, instance lifecycle, networking, etc.), use the [Jetstream support resources](https://docs.jetstream-cloud.org/overview/support/).
101+
- 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).
102+
- 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).
147103
148-
## Step 3: Install conda / pip packages for all users
104+
When asking for help about TLJH, it is often useful to provide:
149105
150-
```{include} add-packages.md
106+
- A short description of what you were trying to do and what happened instead
107+
- Relevant log excerpts (see [](/troubleshooting/logs))
108+
- Your TLJH version (`sudo tljh-config show | grep version` if present in config) and the output of `lsb_release -a` for the OS
109+
- Any custom installer flags or `tljh-config` changes you have applied
151110
111+
This information helps others debug and answer more quickly.
152112
```

0 commit comments

Comments
 (0)