You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/install/jetstream.md
+63-72Lines changed: 63 additions & 72 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,97 +13,87 @@ users and a user environment with packages you want installed running on
13
13
1. A Jetstream account with an XSEDE allocation; for more information,
14
14
see the [Jetstream Allocations help page](https://jetstream-cloud.org/allocations/).
15
15
16
-
## Step 1: Installing The Littlest JupyterHub
16
+
## Step 1: Launch a Jetstream 2 instance and install TLJH
17
17
18
-
Let's create the server on which we can run JupyterHub.
18
+
We'll create a new Jetstream 2 virtual machine and have it automatically install The Littlest JupyterHub (TLJH) at first boot.
19
19
20
-
1. Log in to [the Jetstream portal](https://use.jetstream-cloud.org/). You need an allocation
21
-
to launch instances. Click on the allocation you would like to charge the instance to.
22
-
23
-
1. Select **Create**, then **Instance** to get going.
24
-
25
-
This takes you to a page with a list of base images you can choose for your
26
-
server.
27
-
28
-
3. Click on the Ubuntu 24.04 image.
29
-
30
-
5. A dialog titled **Create Instance** pops up, with various
31
-
options for configuring your instance.
32
-
33
-
1. Give your server a descriptive **Instance Name**.
34
-
35
-
2. Select an appropriate **Instance Size**. We suggest `m3.small` or larger.
36
-
Make sure your instance has at least **1GB** of RAM.
37
-
38
-
Check out our guide on How To [](/howto/admin/resource-estimation) to help pick
39
-
how much Memory, CPU & disk space your server needs.
40
-
41
-
1.
42
-
43
-
6. Click on **Show** under **Advanced Options**. **Boot Script**
44
-
lets us configure what the server should do when it starts up. We will use
45
-
this to install The Littlest JupyterHub.
46
-
47
-
48
-
just after the line:
49
-
50
-
```bash
51
-
if [ $ANSIBLE_RETURN_CODE-eq 0 ];then STATUS="complete";else STATUS="error";fi
52
-
```
53
-
54
-
Insert:
20
+
1. Log in to the [Jetstream 2 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. Expand **Advanced Options**, then locate the **Boot Script** field. Replace any placeholder content with the following script (the whole content should just be this):
55
29
56
30
```bash
57
31
#!/bin/bash
32
+
# Install The Littlest JupyterHub at first boot
58
33
curl -L https://tljh.jupyter.org/bootstrap.py \
59
-
| sudo python3 - \
60
-
--admin <admin-user-name>
34
+
| sudo -E python3 - \
35
+
--admin <admin-user-name>
61
36
```
62
37
63
-
You can choose any `<admin-user-name>`, it is just the JupyterHub admin, not an actual Linux user on the server.
38
+
Replace `<admin-user-name>` with the name you want forthe first JupyterHub admin user (this creates a JupyterHub user; a matching Linux user is created automatically). You can add more admins later.
64
39
65
-
14. You'll now be shown a dashboard with all your servers and their states. The
66
-
server you just launched will progress through various stages of set up,
67
-
and you can see the progress here.
40
+
Notes:
41
+
- The script runs only once, during the initial boot.
42
+
- Keep it minimal—adding extra commands often slows install or causes failures if something prompts for input.
43
+
6. Launch the instance (click **Create Instance** / **Launch**).
44
+
7. You'll return to the instances dashboard. Your new instance will transition through provisioning states. It generally takes about 5 minutes for the TLJH install to finish after the VM first reports as active.
45
+
8. Once the status shows **Ready** (or the VM indicates it is running), copy the displayed **Hostname**. It looks like:
68
46
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!
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
83
-
strong password & note it down somewhere, since this will be the password for
84
-
the admin user account from now on.
85
-
86
-
18. Congratulations, you have a running working JupyterHub!
49
+
Here `xxx0000000` is your allocation ID.
50
+
9. Open that 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.
51
+
10. Log in with the `<admin-user-name>` you used in the boot script. 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.
52
+
11. (Optional) Verify the install by SSHing to the instance as `exouser` (Jetstream's default user):
* 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).
84
+
* If you later attach a custom domain, add it with another `add-item` command and reload the proxy again.
103
85
104
86
## Step 3: Customize your JupyterHub deployment
105
87
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!
88
+
Next common tasks:
89
+
90
+
* Add additional users or admins: [User management](/howto/admin/add-users)
91
+
* Install Python / conda packages for all users: [Customize user environment](/howto/user-env)
92
+
* Install optional system packages: `sudo apt install <package>` (restart user servers afterwards)
93
+
* Pre-install JupyterLab extensions: see [Enable extensions](/howto/admin/enable-extensions)
0 commit comments