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).
1. An ACCESS ID, and membership in an allocation with access to Jetstream2 resources; for more information,
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/).
## 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 / 6 GiB RAM) or larger for more than a couple of users. The absolute minimum TLJH can start with is about **1GiB** 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** button at the bottom of the form).
2. Select the **Launch New Instance** option to get going.
:alt: Launch new instance button with description.
```
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.
This takes you to a page with a list of base images you can choose for your
server.
3. SSH into the instance with the `exouser` user:
3. Under **Image Search**, search for **Ubuntu 22.04**, and select the
:alt: Select Ubuntu 22.04 x64 image from image list
```
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. Once selected, you will see more information about this image. Click the
**Launch** button on the top right.
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.
5. A dialog titled **Launch an Instance / Basic Options** pops up, with various
options for configuring your instance.
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.
3. If you have multiple allocations, make sure you are 'charging' this server
to the correct allocation.
Tips:
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.
- 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.
A dialog titled **Launch an Instance / Advanced Options** should pop up.
## Step 3: Log in as the administrative user and set a password
:alt: Dialog box allowing you to add a new script.
```
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.
2. Congratulations, you have a running working JupyterHub!
7. Click the **Create New Script** button. This will open up another dialog
:alt: Instances dashboard showing deployment in progress.
```
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!
16. Copy the **IP Address** of your server, and try accessing it from a web
browser. It should give you a JupyterHub login page.
```{image} ../images/first-login.png
:alt: JupyterHub log-in page
```
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.
18. Congratulations, you have a running working JupyterHub!
## Step 2: Adding more users
## Step 4: Adding more users
```{include} add-users.md
```
## Step 3: Install conda / pip packages for all users
```{include} add-packages.md
Next common tasks:
- [](howto-admin-admin-users)
- [](howto-user-env-user-environment-apt)
- [](howto-admin-enable-extensions)
- []topic-installer-upgrade-actions)
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](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](https://github.com/jupyterhub/the-littlest-jupyterhub).
When asking for help about TLJH, it is often useful to provide:
- 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.
```
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
