Skip to content

Commit 6907857

Browse files
zoncazonca
committed
Updated the tutorial to Jetstream 2
1 parent 616d69a commit 6907857

File tree

1 file changed

+55
-84
lines changed

1 file changed

+55
-84
lines changed

‎docs/install/jetstream.md‎

Lines changed: 55 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
(install-jetstream)=
22

3-
# Installing on Jetstream
3+
# Installing on Jetstream 2
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+
[Jetstream 2](https://jetstream-cloud.org/).
1010

1111
## Prerequisites
1212

@@ -18,72 +18,40 @@ users and a user environment with packages you want installed running on
1818
Let's create the server on which we can run JupyterHub.
1919

2020
1. Log in to [the Jetstream portal](https://use.jetstream-cloud.org/). You need an allocation
21-
to launch instances.
21+
to launch instances. Click on the allocation you would like to charge the instance to.
2222

23-
2. Select the **Launch New Instance** option to get going.
24-
25-
```{image} ../images/providers/jetstream/launch-instance-first-button.png
26-
:alt: Launch new instance button with description.
27-
```
23+
1. Select **Create**, then **Instance** to get going.
2824

2925
This takes you to a page with a list of base images you can choose for your
3026
server.
3127

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-
```
28+
3. Click on the Ubuntu 24.04 image.
4529

46-
5. A dialog titled **Launch an Instance / Basic Options** pops up, with various
30+
5. A dialog titled **Create Instance** pops up, with various
4731
options for configuring your instance.
4832

49-
```{image} ../images/providers/jetstream/launch-instance-dialog.png
50-
:alt: Launch an Instance / Basic Options dialog box
51-
```
52-
5333
1. Give your server a descriptive **Instance Name**.
5434

55-
2. Select an appropriate **Instance Size**. We suggest m1.medium or larger.
35+
2. Select an appropriate **Instance Size**. We suggest `m3.small` or larger.
5636
Make sure your instance has at least **1GB** of RAM.
5737

5838
Check out our guide on How To [](/howto/admin/resource-estimation) to help pick
5939
how much Memory, CPU & disk space your server needs.
40+
41+
1.
6042

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
43+
6. Click on **Show** under **Advanced Options**. **Boot Script**
6544
lets us configure what the server should do when it starts up. We will use
6645
this to install The Littlest JupyterHub.
6746

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-
```
7347

74-
7. Click the **Create New Script** button. This will open up another dialog
75-
box!
48+
just after the line:
7649

77-
```{image} ../images/providers/jetstream/create-script-dialog.png
78-
:alt: Launch an Instance / Advanced Options dialog box
50+
```bash
51+
if [ $ANSIBLE_RETURN_CODE -eq 0 ]; then STATUS="complete"; else STATUS="error"; fi
7952
```
8053

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**!
54+
Insert:
8755

8856
```bash
8957
#!/bin/bash
@@ -92,61 +60,64 @@ Let's create the server on which we can run JupyterHub.
9260
--admin <admin-user-name>
9361
```
9462

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-
```
63+
You can choose any `<admin-user-name>`, it is just the JupyterHub admin, not an actual Linux user on the server.
11664

11765
14. You'll now be shown a dashboard with all your servers and their states. The
11866
server you just launched will progress through various stages of set up,
11967
and you can see the progress here.
12068
121-
```{image} ../images/providers/jetstream/deployment-in-progress.png
122-
:alt: Instances dashboard showing deployment in progress.
123-
```
69+
15. It will take about 5 minutes for your server to come up. The status will
70+
say **Ready** once the server and your JupyterHub is ready for use!
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+
Copy the **Hostname** under **Credentials** that will be of the form:
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+
yourinstancename.xxx0000000.projects.jetstream-cloud.org
13175
132-
```{image} ../images/first-login.png
133-
:alt: JupyterHub log-in page
134-
```
76+
Where `xxx000000` is the allocation id.
13577
136-
17. Login using the **admin user name** you used in step 8, and a password. Use a
78+
16. Try accessing it from a web
79+
browser. It should give you a JupyterHub login page, your browser will probably
80+
complain about the site being served with no HTTPS, we will fix that next.
81+
82+
17. Login using the **admin user name** you set in the boot script, and choose a password. Use a
13783
strong password & note it down somewhere, since this will be the password for
13884
the admin user account from now on.
13985
14086
18. Congratulations, you have a running working JupyterHub!
14187
142-
## Step 2: Adding more users
88+
## Step 2: Enable HTTPS
14389
144-
```{include} add-users.md
90+
Take a look at the documentation on how to [enable HTTPS on your JupyterHub deployment](https://tljh.jupyter.org/en/latest/howto/admin/https.html)
14591
146-
```
92+
In case you just want to use the default domain provided by Jetstream, in the form:
14793
148-
## Step 3: Install conda / pip packages for all users
94+
yourinstancename.xxx0000000.projects.jetstream-cloud.org
14995
150-
```{include} add-packages.md
96+
where `xxx000000` is the allocation ID, you can SSH into the instance as `exouser` and run:
15197
98+
```bash
99+
sudo tljh-config set https.enabled true
100+
sudo tljh-config set https.letsencrypt.email [email protected]
101+
sudo tljh-config add-item https.letsencrypt.domains yourinstancename.xxx000000.projects.jetstream-cloud.org
152102
```
103+
104+
## Step 3: Customize your JupyterHub deployment
105+
106+
Follow ["The littlest JupyterHub" documentation](/howto/index) for instructions on how to add new users, customize the Python environment, update JupyterHub itself, and more!
107+
108+
## Ask for help
109+
110+
Need a hand?
111+
112+
- For Jetstream 2 specific questions (allocations, quotas, instance lifecycle, networking, etc.), use the Jetstream support resources: <https://docs.jetstream-cloud.org/overview/support/>
113+
- 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>
114+
- 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>
115+
116+
When asking for help about TLJH, it is often useful to provide:
117+
118+
- A short description of what you were trying to do and what happened instead
119+
- Relevant log excerpts (see [](/troubleshooting/logs))
120+
- Your TLJH version (`sudo tljh-config show | grep version` if present in config) and the output of `lsb_release -a` for the OS
121+
- Any custom installer flags or `tljh-config` changes you have applied
122+
123+
This information helps others debug and answer more quickly.

0 commit comments

Comments
 (0)