mirror of
https://github.com/jupyterhub/the-littlest-jupyterhub.git
synced 2025-12-18 21:54:05 +08:00
adopt myst
run rst2myst, with minimal manual formatting fixes
This commit is contained in:
Min RK
279
docs/install/amazon.md
Normal file
279
docs/install/amazon.md
Normal file
@@ -0,0 +1,279 @@
|
||||
(install-amazon)=
|
||||
|
||||
# Installing on Amazon Web Services
|
||||
|
||||
## Goal
|
||||
|
||||
To have a JupyterHub with admin users and a user environment with conda / pip packages.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. An Amazon Web Services account.
|
||||
|
||||
If asked to choose a default region, choose the one closest to the majority
|
||||
of your users.
|
||||
|
||||
## Step 1: Installing The Littlest JupyterHub
|
||||
|
||||
Let's create the server on which we can run JupyterHub.
|
||||
|
||||
1. Go to [Amazon Web Services](https://aws.amazon.com/) and click the gold
|
||||
button 'Sign In to the Console' in the upper right. Log in with your Amazon Web
|
||||
Services account.
|
||||
|
||||
If you need to adjust your region from your default, there is a drop-down
|
||||
menu between your name and the **Support** menu on the far right of the dark
|
||||
navigation bar across the top of the window. Adjust the region to match the
|
||||
closest one to the majority of your users.
|
||||
|
||||
2. On the screen listing all the available services, pick **EC2** under **Compute**
|
||||
on the left side at the top of the first column.
|
||||
|
||||
```{image} ../images/providers/amazon/compute_services.png
|
||||
:alt: Select EC2
|
||||
```
|
||||
|
||||
This will take you to the **EC2 Management Console**.
|
||||
|
||||
3. From the navigation menu listing on the far left side of the **EC2 Management
|
||||
Console**, choose **Instances** under the light gray **INSTANCES** sub-heading.
|
||||
|
||||
```{image} ../images/providers/amazon/instances_from_console.png
|
||||
:alt: Select Instances from console
|
||||
```
|
||||
|
||||
4. In the main window of the **EC2 Management Console**, towards the top left,
|
||||
click on the bright blue **Launch Instance** button.
|
||||
|
||||
```{image} ../images/providers/amazon/launch_instance_button.png
|
||||
:alt: Click launch instance
|
||||
```
|
||||
|
||||
This will start the 'launch instance wizard' process. This lets you customize
|
||||
the kind of server you want, the resources it will have and its name.
|
||||
|
||||
5. On the page **Step 1: Choose an Amazon Machine Image (AMI)** you are going
|
||||
to pick the base image your remote server will have. The view will
|
||||
default to the 'Quick-start' tab selected and just a few down the page, select
|
||||
**Ubuntu Server 22.04 LTS (HVM), SSD Volume Type - ami-XXXXXXXXXXXXXXXXX**,
|
||||
leaving `64-bit (x86)` toggled.
|
||||
|
||||
```{image} ../images/providers/amazon/select_ubuntu_18.png
|
||||
:alt: Click Ubuntu server 22.04
|
||||
```
|
||||
|
||||
The `ami` alpha-numeric at the end references the specific Amazon machine
|
||||
image, ignore this as Amazon updates them routinely. The
|
||||
**Ubuntu Server 22.04 LTS (HVM)** is the important part.
|
||||
|
||||
6. After selecting the AMI, you'll be at **Step 2: Choose an Instance Type**.
|
||||
|
||||
There will be a long listing of the types and numbers of CPUs that Amazon
|
||||
offers. Select the one you want and then select the button
|
||||
`Next: Configure Instance Details` in the lower right corner.
|
||||
|
||||
Check out our guide on How To {ref}`howto/admin/resource-estimation` to help pick
|
||||
how much Memory / CPU your server needs.
|
||||
We recommend you use a server with at least 2GB of RAM, such as a **t3.small**.
|
||||
However, if you need to minimise costs you can use a server with **1GB** RAM such as a **t2.micro**, but performance will be limited.
|
||||
|
||||
You may wish to consult the listing [here](https://www.ec2instances.info/)
|
||||
because it shows cost per hour. The **On Demand** price is the pertinent cost.
|
||||
|
||||
`GPU graphics` and `GPU compute` products are also available around half way down the page
|
||||
|
||||
7. Under **Step 3: Configure Instance Details**, scroll to the bottom of the page
|
||||
and toggle the arrow next to **Advanced Details**. Scroll down to 'User data'. Copy
|
||||
the text below, and paste it into the **User data** text box. Replace
|
||||
`<admin-user-name>` with the name of the first **admin user** for this
|
||||
JupyterHub. This admin user can log in after the JupyterHub is set up, and
|
||||
configure it. **Remember to add your username**!
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
curl -L https://tljh.jupyter.org/bootstrap.py \
|
||||
| sudo python3 - \
|
||||
--admin <admin-user-name>
|
||||
```
|
||||
|
||||
```{image} ../images/providers/amazon/script_in_user_data.png
|
||||
:alt: Install JupyterHub with the script in the User data textbox
|
||||
```
|
||||
|
||||
:::{note}
|
||||
See {ref}`topic/installer-actions` for a detailed description and
|
||||
{ref}`topic/customizing-installer` for other options that can be used.
|
||||
:::
|
||||
|
||||
8. Under **Step 4: Add Storage**, you can change the **size** and **type of your
|
||||
disk by adjusting the value in \*\*Size (GiB)** and selecting **Volume Type**.
|
||||
|
||||
```{image} ../images/providers/amazon/change_size_type.png
|
||||
:alt: Selecting disk size and type
|
||||
```
|
||||
|
||||
Check out {ref}`howto/admin/resource-estimation` to help pick
|
||||
how much Disk space your server needs.
|
||||
|
||||
Hover over the encircled `i` next to **Volume Type** for an explanation of
|
||||
each. Leaving the default as is is fine. `General Purpose SSD (gp2)` is
|
||||
recommended for most workloads. With `Provisioned IOPS SSD (io1)` being the
|
||||
highest-performance SSD volume. Magnetic (standard) is a previous generation
|
||||
volume and not suited for a hub for multi-users.
|
||||
|
||||
When finished, click **Next: Add Tags** in the bottom right corner.
|
||||
|
||||
9. Under **Step 5: Add Tags**, click **Add Tag** and enter **Name** under the
|
||||
**Key** field. In the **Value** field in the **Name** row, give your new
|
||||
server a memorable name that identifies what purpose this JupyterHub will be
|
||||
used for.
|
||||
|
||||
```{image} ../images/providers/amazon/name_hub.png
|
||||
:alt: Use tags to name the hub.
|
||||
```
|
||||
|
||||
10. Under **Step 6: Configure Security Group**, you'll set the firewall rules
|
||||
that control the traffic for your instance. Specifically you'll want to add
|
||||
rules to allow both **HTTP Traffic** and **HTTPS Traffic**. For
|
||||
advanced troubleshooting, it will be helpful to set rules so you can use
|
||||
SSH to connect (port 22).
|
||||
|
||||
If you have never used your Amazon account before, you'll have to select
|
||||
**Create a new security group**. You should give it a disitnguishing name
|
||||
under **Security group name**
|
||||
such as `ssh_web` for future reference. If you have, one from before you can
|
||||
select it and adjust it to have the rules you need, if you prefer.
|
||||
|
||||
The rules will default to include `SSH`. Leave that there, and then click on
|
||||
the **Add Rule** button. Under **Type** for the new rule, change the field
|
||||
to **HTTP**. The other boxes will get filled in appropritely. Again, click on
|
||||
the **Add Rule** button. This time under **Type** for the new rule, change
|
||||
the field to **HTTPS**.
|
||||
|
||||
The warning is there to remind you this opens things up to some degree but
|
||||
this is necessary in order to let your users connect. However, this warning
|
||||
is a good reminder that you should monitor your server to insure it is
|
||||
available for users who may need it.
|
||||
|
||||
```{image} ../images/providers/amazon/set_security_groups.png
|
||||
:alt: Allow HTTP & HTTPS traffic to your server
|
||||
```
|
||||
|
||||
11. When the security rules are set, click on the blue button in the bottom
|
||||
right **Review and Launch**. This will give you a chance to review things
|
||||
because very soon you'll be launching and start paying for any resources you
|
||||
use.
|
||||
|
||||
Note that you'll see two HTTP listings and two HTTPS listings under
|
||||
**Security Groups** even though you only made one for each. This is normal &
|
||||
necessary to match both IPv4 & IPv6 types of IP addresses.
|
||||
|
||||
When you are happy, press the blue **Launch** button in the bottom right
|
||||
corner to nearly conclude your journey through the instance launch wizard.
|
||||
|
||||
```{image} ../images/providers/amazon/finally_launch.png
|
||||
:alt: Launch your server
|
||||
```
|
||||
|
||||
12. In the dialog box that pops up as the last step before launching is
|
||||
triggered, you need to choose what to do about an identifying key pair and
|
||||
acknowledge your choice in order to proceed. If you already have a key pair you
|
||||
can select to associate it with this instance, otherwise you need to
|
||||
**Create a new key pair**. Choosing to `Proceed without a key pair` is not
|
||||
recommended as you'll have no way to access your server via SSH if anything
|
||||
goes wrong with the Jupyterhub and have no way to recover files via download.
|
||||
|
||||
Download and keep the key pair file unless you are associating one you already
|
||||
have.
|
||||
|
||||
```{image} ../images/providers/amazon/create_key_pair.png
|
||||
:alt: Associate key pair
|
||||
```
|
||||
|
||||
13. With the key pair associated, click the **Launch instances** button to
|
||||
start creating the server that'll run TLJH.
|
||||
|
||||
```{image} ../images/providers/amazon/launch_now.png
|
||||
:alt: Trigger actual launch
|
||||
```
|
||||
|
||||
14. Following the launch initiation, you'll be taken to a **Launch Status**
|
||||
notification screen. You can see more information about the details if you
|
||||
click on the alphanumeric link to the launching instance following the text,
|
||||
"`The following instance launches have been initiated:`".
|
||||
|
||||
```{image} ../images/providers/amazon/launch_status_screen.png
|
||||
:alt: Launch status notice
|
||||
```
|
||||
|
||||
15. That link will take you back to the **EC2 Management Console** with settings
|
||||
that will limit the view in the console to just that instance. (Delete the
|
||||
filter in the search bar if you want to see any other instances you may
|
||||
have.) At first the server will be starting up, and then when the
|
||||
**Instance state** is green the server is running.
|
||||
|
||||
```{image} ../images/providers/amazon/running_server.png
|
||||
:alt: Server is running.
|
||||
```
|
||||
|
||||
If you already have instances running in your account, the screen will look
|
||||
different if you disable that filter. But you want to pay attention to the
|
||||
row with the name of the server you made.
|
||||
|
||||
16. In a few seconds your server will be created, and you can see the
|
||||
**Public IP** used to access it in the panel at the bottom of the console.
|
||||
If it isn't displayed, click on the row for that instance in the console. It
|
||||
will look like a pattern similar to **12.30.230.127**.
|
||||
|
||||
```{image} ../images/providers/amazon/public_ip.png
|
||||
:alt: public IP
|
||||
```
|
||||
|
||||
17. The Littlest JupyterHub is now installing in the background on your new
|
||||
server. It takes around 10 minutes for this installation to complete.
|
||||
|
||||
18. Check if the installation is complete by copying the **Public IP**
|
||||
of your server, and trying to access it from within a browser. If it has been
|
||||
10 minutes, paste the public IP into the URL bar of your browser and hit
|
||||
return to try to connect.
|
||||
|
||||
Accessing the JupyterHub will fail until the installation is complete,
|
||||
so be patient. The next step below this one shows the login window you are
|
||||
expecting to see when trying the URL and things work.
|
||||
While waiting until the appropriate time to try, another way to check if
|
||||
things are churning away, is to open the **System Log**. To do this, go to
|
||||
the **EC2 Management Console** & highlight the instance by clicking on that
|
||||
row and then right-click **Monitor and troubleshoot** > **Get system log**.
|
||||
|
||||
19. When the Jupyterhub creation process finishes and the hub is ready to show
|
||||
the login, the **System Log** should look similar to the image below. Scroll to
|
||||
the bottom of your output from the previous step.
|
||||
Note the line **Starting TLJH installer**, you may also see **Started jupyterhub.service**
|
||||
|
||||
```{image} ../images/providers/amazon/completed_system_log.png
|
||||
:alt: Completed system log
|
||||
```
|
||||
|
||||
20. When the installation is complete, it should give you a JupyterHub login page.
|
||||
|
||||
```{image} ../images/first-login.png
|
||||
:alt: JupyterHub log-in page
|
||||
```
|
||||
|
||||
21. Login using the **admin user name** you used in step 7, 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.
|
||||
|
||||
22. Congratulations, you have a running working JupyterHub!
|
||||
|
||||
## Step 2: Adding more users
|
||||
|
||||
```{eval-rst}
|
||||
.. include:: add_users.txt
|
||||
```
|
||||
|
||||
## Step 3: Install conda / pip packages for all users
|
||||
|
||||
```{eval-rst}
|
||||
.. include:: add_packages.txt
|
||||
```
|
||||
@@ -1,269 +0,0 @@
|
||||
.. _install/amazon:
|
||||
|
||||
=================================
|
||||
Installing on Amazon Web Services
|
||||
=================================
|
||||
|
||||
Goal
|
||||
====
|
||||
|
||||
To have a JupyterHub with admin users and a user environment with conda / pip packages.
|
||||
|
||||
Prerequisites
|
||||
=============
|
||||
|
||||
#. An Amazon Web Services account.
|
||||
|
||||
If asked to choose a default region, choose the one closest to the majority
|
||||
of your users.
|
||||
|
||||
Step 1: Installing The Littlest JupyterHub
|
||||
==========================================
|
||||
|
||||
Let's create the server on which we can run JupyterHub.
|
||||
|
||||
#. Go to `Amazon Web Services <https://aws.amazon.com/>`_ and click the gold
|
||||
button 'Sign In to the Console' in the upper right. Log in with your Amazon Web
|
||||
Services account.
|
||||
|
||||
If you need to adjust your region from your default, there is a drop-down
|
||||
menu between your name and the **Support** menu on the far right of the dark
|
||||
navigation bar across the top of the window. Adjust the region to match the
|
||||
closest one to the majority of your users.
|
||||
|
||||
#. On the screen listing all the available services, pick **EC2** under **Compute**
|
||||
on the left side at the top of the first column.
|
||||
|
||||
.. image:: ../images/providers/amazon/compute_services.png
|
||||
:alt: Select EC2
|
||||
|
||||
This will take you to the **EC2 Management Console**.
|
||||
|
||||
#. From the navigation menu listing on the far left side of the **EC2 Management
|
||||
Console**, choose **Instances** under the light gray **INSTANCES** sub-heading.
|
||||
|
||||
.. image:: ../images/providers/amazon/instances_from_console.png
|
||||
:alt: Select Instances from console
|
||||
|
||||
#. In the main window of the **EC2 Management Console**, towards the top left,
|
||||
click on the bright blue **Launch Instance** button.
|
||||
|
||||
.. image:: ../images/providers/amazon/launch_instance_button.png
|
||||
:alt: Click launch instance
|
||||
|
||||
This will start the 'launch instance wizard' process. This lets you customize
|
||||
the kind of server you want, the resources it will have and its name.
|
||||
|
||||
|
||||
#. On the page **Step 1: Choose an Amazon Machine Image (AMI)** you are going
|
||||
to pick the base image your remote server will have. The view will
|
||||
default to the 'Quick-start' tab selected and just a few down the page, select
|
||||
**Ubuntu Server 22.04 LTS (HVM), SSD Volume Type - ami-XXXXXXXXXXXXXXXXX**,
|
||||
leaving `64-bit (x86)` toggled.
|
||||
|
||||
.. image:: ../images/providers/amazon/select_ubuntu_18.png
|
||||
:alt: Click Ubuntu server 22.04
|
||||
|
||||
The `ami` alpha-numeric at the end references the specific Amazon machine
|
||||
image, ignore this as Amazon updates them routinely. The
|
||||
**Ubuntu Server 22.04 LTS (HVM)** is the important part.
|
||||
|
||||
|
||||
#. After selecting the AMI, you'll be at **Step 2: Choose an Instance Type**.
|
||||
|
||||
There will be a long listing of the types and numbers of CPUs that Amazon
|
||||
offers. Select the one you want and then select the button
|
||||
`Next: Configure Instance Details` in the lower right corner.
|
||||
|
||||
Check out our guide on How To :ref:`howto/admin/resource-estimation` to help pick
|
||||
how much Memory / CPU your server needs.
|
||||
We recommend you use a server with at least 2GB of RAM, such as a **t3.small**.
|
||||
However, if you need to minimise costs you can use a server with **1GB** RAM such as a **t2.micro**, but performance will be limited.
|
||||
|
||||
You may wish to consult the listing `here <https://www.ec2instances.info/>`_
|
||||
because it shows cost per hour. The **On Demand** price is the pertinent cost.
|
||||
|
||||
``GPU graphics`` and ``GPU compute`` products are also available around half way down the page
|
||||
|
||||
#. Under **Step 3: Configure Instance Details**, scroll to the bottom of the page
|
||||
and toggle the arrow next to **Advanced Details**. Scroll down to 'User data'. Copy
|
||||
the text below, and paste it into the **User data** text box. Replace
|
||||
``<admin-user-name>`` with the name of the first **admin user** for this
|
||||
JupyterHub. This admin user can log in after the JupyterHub is set up, and
|
||||
configure it. **Remember to add your username**!
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
#!/bin/bash
|
||||
curl -L https://tljh.jupyter.org/bootstrap.py \
|
||||
| sudo python3 - \
|
||||
--admin <admin-user-name>
|
||||
|
||||
.. image:: ../images/providers/amazon/script_in_user_data.png
|
||||
:alt: Install JupyterHub with the script in the User data textbox
|
||||
|
||||
.. note::
|
||||
|
||||
See :ref:`topic/installer-actions` for a detailed description and
|
||||
:ref:`topic/customizing-installer` for other options that can be used.
|
||||
|
||||
#. Under **Step 4: Add Storage**, you can change the **size** and **type of your
|
||||
disk by adjusting the value in **Size (GiB)** and selecting **Volume Type**.
|
||||
|
||||
.. image:: ../images/providers/amazon/change_size_type.png
|
||||
:alt: Selecting disk size and type
|
||||
|
||||
Check out :ref:`howto/admin/resource-estimation` to help pick
|
||||
how much Disk space your server needs.
|
||||
|
||||
Hover over the encircled `i` next to **Volume Type** for an explanation of
|
||||
each. Leaving the default as is is fine. `General Purpose SSD (gp2)` is
|
||||
recommended for most workloads. With `Provisioned IOPS SSD (io1)` being the
|
||||
highest-performance SSD volume. Magnetic (standard) is a previous generation
|
||||
volume and not suited for a hub for multi-users.
|
||||
|
||||
When finished, click **Next: Add Tags** in the bottom right corner.
|
||||
|
||||
#. Under **Step 5: Add Tags**, click **Add Tag** and enter **Name** under the
|
||||
**Key** field. In the **Value** field in the **Name** row, give your new
|
||||
server a memorable name that identifies what purpose this JupyterHub will be
|
||||
used for.
|
||||
|
||||
.. image:: ../images/providers/amazon/name_hub.png
|
||||
:alt: Use tags to name the hub.
|
||||
|
||||
#. Under **Step 6: Configure Security Group**, you'll set the firewall rules
|
||||
that control the traffic for your instance. Specifically you'll want to add
|
||||
rules to allow both **HTTP Traffic** and **HTTPS Traffic**. For
|
||||
advanced troubleshooting, it will be helpful to set rules so you can use
|
||||
SSH to connect (port 22).
|
||||
|
||||
If you have never used your Amazon account before, you'll have to select
|
||||
**Create a new security group**. You should give it a disitnguishing name
|
||||
under **Security group name**
|
||||
such as `ssh_web` for future reference. If you have, one from before you can
|
||||
select it and adjust it to have the rules you need, if you prefer.
|
||||
|
||||
The rules will default to include `SSH`. Leave that there, and then click on
|
||||
the **Add Rule** button. Under **Type** for the new rule, change the field
|
||||
to **HTTP**. The other boxes will get filled in appropritely. Again, click on
|
||||
the **Add Rule** button. This time under **Type** for the new rule, change
|
||||
the field to **HTTPS**.
|
||||
|
||||
The warning is there to remind you this opens things up to some degree but
|
||||
this is necessary in order to let your users connect. However, this warning
|
||||
is a good reminder that you should monitor your server to insure it is
|
||||
available for users who may need it.
|
||||
|
||||
.. image:: ../images/providers/amazon/set_security_groups.png
|
||||
:alt: Allow HTTP & HTTPS traffic to your server
|
||||
|
||||
#. When the security rules are set, click on the blue button in the bottom
|
||||
right **Review and Launch**. This will give you a chance to review things
|
||||
because very soon you'll be launching and start paying for any resources you
|
||||
use.
|
||||
|
||||
Note that you'll see two HTTP listings and two HTTPS listings under
|
||||
**Security Groups** even though you only made one for each. This is normal &
|
||||
necessary to match both IPv4 & IPv6 types of IP addresses.
|
||||
|
||||
When you are happy, press the blue **Launch** button in the bottom right
|
||||
corner to nearly conclude your journey through the instance launch wizard.
|
||||
|
||||
.. image:: ../images/providers/amazon/finally_launch.png
|
||||
:alt: Launch your server
|
||||
|
||||
#. In the dialog box that pops up as the last step before launching is
|
||||
triggered, you need to choose what to do about an identifying key pair and
|
||||
acknowledge your choice in order to proceed. If you already have a key pair you
|
||||
can select to associate it with this instance, otherwise you need to
|
||||
**Create a new key pair**. Choosing to `Proceed without a key pair` is not
|
||||
recommended as you'll have no way to access your server via SSH if anything
|
||||
goes wrong with the Jupyterhub and have no way to recover files via download.
|
||||
|
||||
Download and keep the key pair file unless you are associating one you already
|
||||
have.
|
||||
|
||||
.. image:: ../images/providers/amazon/create_key_pair.png
|
||||
:alt: Associate key pair
|
||||
|
||||
#. With the key pair associated, click the **Launch instances** button to
|
||||
start creating the server that'll run TLJH.
|
||||
|
||||
.. image:: ../images/providers/amazon/launch_now.png
|
||||
:alt: Trigger actual launch
|
||||
|
||||
|
||||
#. Following the launch initiation, you'll be taken to a **Launch Status**
|
||||
notification screen. You can see more information about the details if you
|
||||
click on the alphanumeric link to the launching instance following the text,
|
||||
"`The following instance launches have been initiated:`".
|
||||
|
||||
.. image:: ../images/providers/amazon/launch_status_screen.png
|
||||
:alt: Launch status notice
|
||||
|
||||
#. That link will take you back to the **EC2 Management Console** with settings
|
||||
that will limit the view in the console to just that instance. (Delete the
|
||||
filter in the search bar if you want to see any other instances you may
|
||||
have.) At first the server will be starting up, and then when the
|
||||
**Instance state** is green the server is running.
|
||||
|
||||
.. image:: ../images/providers/amazon/running_server.png
|
||||
:alt: Server is running.
|
||||
|
||||
If you already have instances running in your account, the screen will look
|
||||
different if you disable that filter. But you want to pay attention to the
|
||||
row with the name of the server you made.
|
||||
|
||||
#. In a few seconds your server will be created, and you can see the
|
||||
**Public IP** used to access it in the panel at the bottom of the console.
|
||||
If it isn't displayed, click on the row for that instance in the console. It
|
||||
will look like a pattern similar to **12.30.230.127**.
|
||||
|
||||
.. image:: ../images/providers/amazon/public_ip.png
|
||||
:alt: public IP
|
||||
|
||||
#. The Littlest JupyterHub is now installing in the background on your new
|
||||
server. It takes around 10 minutes for this installation to complete.
|
||||
|
||||
#. Check if the installation is complete by copying the **Public IP**
|
||||
of your server, and trying to access it from within a browser. If it has been
|
||||
10 minutes, paste the public IP into the URL bar of your browser and hit
|
||||
return to try to connect.
|
||||
|
||||
Accessing the JupyterHub will fail until the installation is complete,
|
||||
so be patient. The next step below this one shows the login window you are
|
||||
expecting to see when trying the URL and things work.
|
||||
While waiting until the appropriate time to try, another way to check if
|
||||
things are churning away, is to open the **System Log**. To do this, go to
|
||||
the **EC2 Management Console** & highlight the instance by clicking on that
|
||||
row and then right-click **Monitor and troubleshoot** > **Get system log**.
|
||||
|
||||
#. When the Jupyterhub creation process finishes and the hub is ready to show
|
||||
the login, the **System Log** should look similar to the image below. Scroll to
|
||||
the bottom of your output from the previous step.
|
||||
Note the line **Starting TLJH installer**, you may also see **Started jupyterhub.service**
|
||||
|
||||
.. image:: ../images/providers/amazon/completed_system_log.png
|
||||
:alt: Completed system log
|
||||
|
||||
#. When the installation is complete, it should give you a JupyterHub login page.
|
||||
|
||||
.. image:: ../images/first-login.png
|
||||
:alt: JupyterHub log-in page
|
||||
|
||||
#. Login using the **admin user name** you used in step 7, 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.
|
||||
|
||||
#. Congratulations, you have a running working JupyterHub!
|
||||
|
||||
Step 2: Adding more users
|
||||
==========================
|
||||
|
||||
.. include:: add_users.txt
|
||||
|
||||
Step 3: Install conda / pip packages for all users
|
||||
==================================================
|
||||
|
||||
.. include:: add_packages.txt
|
||||
218
docs/install/azure.md
Normal file
218
docs/install/azure.md
Normal file
@@ -0,0 +1,218 @@
|
||||
(install-azure)=
|
||||
|
||||
# Installing on Azure
|
||||
|
||||
## Goal
|
||||
|
||||
By the end of this tutorial, you should have a JupyterHub with some admin
|
||||
users and a user environment with packages you want to be installed running on
|
||||
[Microsoft Azure](https://azure.microsoft.com).
|
||||
|
||||
This tutorial leads you step-by-step for you to manually deploy your own JupyterHub on Azure cloud.
|
||||
|
||||
:::{note}
|
||||
✨ The `Deploy to Azure button` project allows you to deploy your own JupyterHub with minimal manual configuration steps. The deploy to Azure button allows you to have a vanilla configuration in just one-click and by assigning some variables.
|
||||
|
||||
Check it out at [https://github.com/trallard/TLJH-azure-button](https://github.com/trallard/TLJH-azure-button).
|
||||
:::
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A Microsoft Azure account.
|
||||
- To get started you can get a free account which includes 150 dollars worth of Azure credits ([get a free account here](https://azure.microsoft.com/en-us/free//?wt.mc_id=TLJH-github-taallard))
|
||||
|
||||
These instructions cover how to set up a Virtual Machine
|
||||
on Microsoft Azure. For subsequent information about creating
|
||||
your JupyterHub and configuring it, see [The Littlest JupyterHub guide](https://the-littlest-jupyterhub.readthedocs.io/en/latest/).
|
||||
|
||||
## Step 1: Installing The Littlest JupyterHub
|
||||
|
||||
We start by creating the Virtual Machine in which we can run TLJH (The Littlest JupyterHub).
|
||||
|
||||
1. Go to [Azure portal](https://portal.azure.com/) and login with your Azure account.
|
||||
2. Expand the left-hand panel by clicking on the ">>" button on the top left corner of your dashboard. Find the Virtual Machines tab and click on it.
|
||||
|
||||
```{image} ../images/providers/azure/azure-vms.png
|
||||
:alt: Virtual machines on Azure portal
|
||||
```
|
||||
|
||||
1. Click **+ add** to create a new Virtual Machine
|
||||
|
||||
> ```{image} ../images/providers/azure/add-vm.png
|
||||
> :alt: Add a new virtual machine
|
||||
> ```
|
||||
|
||||
#. Select **Create VM from Marketplace** in the next screen.
|
||||
A new screen with all the options for Virtual Machines in Azure will displayed.
|
||||
|
||||
> ```{image} ../images/providers/azure/create-vm.png
|
||||
> :alt: Create VM from the marketplace
|
||||
> ```
|
||||
|
||||
1. **Choose an Ubuntu server for your VM**:
|
||||
: - Click `Ubuntu Server 22.04 LTS.`
|
||||
|
||||
- Make sure `Resource Manager` is selected in the next screen and click **Create**
|
||||
|
||||
```{image} ../images/providers/azure/ubuntu-vm.png
|
||||
:alt: Ubuntu VM
|
||||
```
|
||||
|
||||
2. Customise the Virtual Machine basics:
|
||||
: - **Subscription**. Choose the "Free Trial" if this is what you're using. Otherwise, choose a different plan. This is the billing account that will be charged.
|
||||
|
||||
- **Resource group**. Resource groups let you keep your Azure tools/resources together in an availability region (e.g. WestEurope). If you already have one you'd like to use it select that resource.
|
||||
|
||||
:::{note}
|
||||
If you have never created a Resource Group, click on **Create new**
|
||||
:::
|
||||
|
||||
```{image} ../images/providers/azure/new-rg.png
|
||||
:alt: Create a new resource group
|
||||
```
|
||||
|
||||
- **Name**. Use a descriptive name for your virtual machine (note that you cannot use spaces or special characters).
|
||||
- **Region**. Choose a location near where you expect your users to be located.
|
||||
- **Availability options**. Choose "No infrastructure redundancy required".
|
||||
- **Image**. Make sure "Ubuntu Server 22.04 LTS" is selected (from the previous step).
|
||||
- **Authentication type**. Change authentication type to "password".
|
||||
- **Username**. Choose a memorable username, this will be your "root" user, and you'll need it later on.
|
||||
- **Password**. Type in a password, this will be used later for admin access so make sure it is something memorable.
|
||||
|
||||
```{image} ../images/providers/azure/password-vm.png
|
||||
:alt: Add password to VM
|
||||
```
|
||||
|
||||
- **Login with Azure Active Directory**. Choose "Off" (usually the default)
|
||||
- **Inbound port rules**. Leave the defaults for now, and we will update these later on in the Network configuration step.
|
||||
|
||||
3. Before clicking on "Next" we need to select the RAM size for the image.
|
||||
: - For this we need to make sure we have enough RAM to accommodate your users. For example, if each user needs 2GB of RAM, and you have 10 total users, you need at least 20GB of RAM on the machine. It's also good to have a few GB of "buffer" RAM beyond what you think you'll need.
|
||||
|
||||
- Click on **Change size** (see image below)
|
||||
|
||||
```{image} ../images/providers/azure/size-vm.png
|
||||
:alt: Choose vm size
|
||||
```
|
||||
|
||||
:::{note}
|
||||
For more information about estimating memory, CPU and disk needs check [The memory section in the TLJH documentation](https://tljh.jupyter.org/en/latest/howto/admin/resource-estimation.html)
|
||||
:::
|
||||
|
||||
- Select a suitable image (to check available images and prices in your region [click on this link](https://azuremarketplace.microsoft.com/en-gb/marketplace/apps/Canonical.UbuntuServer?tab=PlansAndPrice/?wt.mc_id=TLJH-github-taallard)).
|
||||
|
||||
4. Disks (Storage):
|
||||
: - **Disk options**: select the OS disk type there are options for SDD and HDD. **SSD persistent disk** gives you a faster but more expensive disk than HDD.
|
||||
|
||||
- **Data disk**. Click on create and attach a new disk. Select an appropriate type and size and click ok.
|
||||
- Click "Next".
|
||||
|
||||
```{image} ../images/providers/azure/create-disk.png
|
||||
:alt: Create and attach disk
|
||||
```
|
||||
|
||||
```{image} ../images/providers/azure/disk-vm.png
|
||||
:alt: Choose a disk size
|
||||
```
|
||||
|
||||
5. Networking
|
||||
: - **Virtual network**. Leave the default values selected.
|
||||
|
||||
- **Subnet**. Leave the default values selected.
|
||||
- **Public IP address**.Leave the default values selected. This will make your server accessible from a browser.
|
||||
- **Network Security Group**. Choose "Basic"
|
||||
- **Public inbound ports**. Check **HTTP**, **HTTPS**, and **SSH**.
|
||||
|
||||
```{image} ../images/providers/azure/networking-vm.png
|
||||
:alt: Choose networking ports
|
||||
```
|
||||
|
||||
6. Management
|
||||
: - Monitoring
|
||||
: - **Boot diagnostics**. Choose "On". - **OS guest diagnostics**. Choose "Off". - **Diagnostics storage account**. Leave as the default.
|
||||
|
||||
- Auto-Shutdown
|
||||
: - **Enable auto-shutdown**. Choose "Off".
|
||||
- Backup
|
||||
: - **Backup**. Choose "Off".
|
||||
- System assigned managed identity Select "Off"
|
||||
|
||||
```{image} ../images/providers/azure/backup-vm.png
|
||||
:alt: Choose VM Backup
|
||||
```
|
||||
|
||||
7. Advanced settings
|
||||
: - **Extensions**. Make sure there are no extensions listed
|
||||
|
||||
- **Cloud init**. We are going to use this section to install TLJH directly into our Virtual Machine.
|
||||
Copy the code snippet below:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
curl -L https://tljh.jupyter.org/bootstrap.py \
|
||||
| sudo python3 - \
|
||||
--admin <admin-user-name>
|
||||
```
|
||||
|
||||
where the `username` is the root username you chose for your Virtual Machine.
|
||||
|
||||
```{image} ../images/providers/azure/cloudinit-vm.png
|
||||
:alt: Install TLJH
|
||||
```
|
||||
|
||||
:::{note}
|
||||
See {ref}`topic/installer-actions` if you want to understand exactly what the installer is doing.
|
||||
{ref}`topic/customizing-installer` documents other options that can be passed to the installer.
|
||||
:::
|
||||
|
||||
8. Check the summary and confirm the creation of your Virtual Machine.
|
||||
|
||||
9. Check that the creation of your Virtual Machine worked.
|
||||
: - Wait for the virtual machine to be created. This might take about 5-10 minutes.
|
||||
|
||||
- After completion, you should see a similar screen to the one below:
|
||||
|
||||
```{image} ../images/providers/azure/deployed-vm.png
|
||||
:alt: Deployed VM
|
||||
```
|
||||
|
||||
10. Note that the Littlest JupyterHub should be installing in the background on your new server.
|
||||
: It takes around 5-10 minutes for this installation to complete.
|
||||
|
||||
11. Click on the **Go to resource button**
|
||||
: ```{image} ../images/providers/azure/goto-vm.png
|
||||
:alt: Go to VM
|
||||
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
12. Check if the installation is completed by **copying** the **Public IP address** of your virtual machine, and trying to access it with a browser.
|
||||
|
||||
> ```{image} ../images/providers/azure/ip-vm.png
|
||||
> :alt: Public IP address
|
||||
> ```
|
||||
>
|
||||
> Note that accessing the JupyterHub will fail until the installation is complete, so be patient.
|
||||
|
||||
13. When the installation is complete, it should give you a JupyterHub login page.
|
||||
|
||||
> ```{image} ../images/first-login.png
|
||||
> :alt: JupyterHub log-in page
|
||||
> ```
|
||||
|
||||
14. Login using the **admin user name** you used in step 6, 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.
|
||||
|
||||
15. Congratulations, you have a running working JupyterHub! 🎉
|
||||
|
||||
## Step 2: Adding more users
|
||||
|
||||
```{eval-rst}
|
||||
.. include:: add_users.txt
|
||||
```
|
||||
|
||||
## Step 3: Install conda / pip packages for all users
|
||||
|
||||
```{eval-rst}
|
||||
.. include:: add_packages.txt
|
||||
```
|
||||
@@ -1,192 +0,0 @@
|
||||
.. _install/azure:
|
||||
|
||||
====================
|
||||
Installing on Azure
|
||||
====================
|
||||
|
||||
Goal
|
||||
====
|
||||
|
||||
By the end of this tutorial, you should have a JupyterHub with some admin
|
||||
users and a user environment with packages you want to be installed running on
|
||||
`Microsoft Azure <https://azure.microsoft.com>`_.
|
||||
|
||||
This tutorial leads you step-by-step for you to manually deploy your own JupyterHub on Azure cloud.
|
||||
|
||||
.. note:: ✨ The ``Deploy to Azure button`` project allows you to deploy your own JupyterHub with minimal manual configuration steps. The deploy to Azure button allows you to have a vanilla configuration in just one-click and by assigning some variables.
|
||||
|
||||
Check it out at `https://github.com/trallard/TLJH-azure-button <https://github.com/trallard/TLJH-azure-button>`_.
|
||||
|
||||
Prerequisites
|
||||
==============
|
||||
|
||||
* A Microsoft Azure account.
|
||||
|
||||
* To get started you can get a free account which includes 150 dollars worth of Azure credits (`get a free account here <https://azure.microsoft.com/en-us/free//?wt.mc_id=TLJH-github-taallard>`_)
|
||||
|
||||
These instructions cover how to set up a Virtual Machine
|
||||
on Microsoft Azure. For subsequent information about creating
|
||||
your JupyterHub and configuring it, see `The Littlest JupyterHub guide <https://the-littlest-jupyterhub.readthedocs.io/en/latest/>`_.
|
||||
|
||||
|
||||
Step 1: Installing The Littlest JupyterHub
|
||||
==========================================
|
||||
|
||||
We start by creating the Virtual Machine in which we can run TLJH (The Littlest JupyterHub).
|
||||
|
||||
#. Go to `Azure portal <https://portal.azure.com/>`_ and login with your Azure account.
|
||||
#. Expand the left-hand panel by clicking on the ">>" button on the top left corner of your dashboard. Find the Virtual Machines tab and click on it.
|
||||
|
||||
.. image:: ../images/providers/azure/azure-vms.png
|
||||
:alt: Virtual machines on Azure portal
|
||||
|
||||
#. Click **+ add** to create a new Virtual Machine
|
||||
|
||||
.. image:: ../images/providers/azure/add-vm.png
|
||||
:alt: Add a new virtual machine
|
||||
|
||||
#. Select **Create VM from Marketplace** in the next screen.
|
||||
A new screen with all the options for Virtual Machines in Azure will displayed.
|
||||
|
||||
.. image:: ../images/providers/azure/create-vm.png
|
||||
:alt: Create VM from the marketplace
|
||||
|
||||
#. **Choose an Ubuntu server for your VM**:
|
||||
* Click `Ubuntu Server 22.04 LTS.`
|
||||
* Make sure `Resource Manager` is selected in the next screen and click **Create**
|
||||
|
||||
.. image:: ../images/providers/azure/ubuntu-vm.png
|
||||
:alt: Ubuntu VM
|
||||
|
||||
#. Customise the Virtual Machine basics:
|
||||
* **Subscription**. Choose the "Free Trial" if this is what you're using. Otherwise, choose a different plan. This is the billing account that will be charged.
|
||||
* **Resource group**. Resource groups let you keep your Azure tools/resources together in an availability region (e.g. WestEurope). If you already have one you'd like to use it select that resource.
|
||||
|
||||
.. note:: If you have never created a Resource Group, click on **Create new**
|
||||
|
||||
.. image:: ../images/providers/azure/new-rg.png
|
||||
:alt: Create a new resource group
|
||||
|
||||
* **Name**. Use a descriptive name for your virtual machine (note that you cannot use spaces or special characters).
|
||||
* **Region**. Choose a location near where you expect your users to be located.
|
||||
* **Availability options**. Choose "No infrastructure redundancy required".
|
||||
* **Image**. Make sure "Ubuntu Server 22.04 LTS" is selected (from the previous step).
|
||||
* **Authentication type**. Change authentication type to "password".
|
||||
* **Username**. Choose a memorable username, this will be your "root" user, and you'll need it later on.
|
||||
* **Password**. Type in a password, this will be used later for admin access so make sure it is something memorable.
|
||||
|
||||
.. image:: ../images/providers/azure/password-vm.png
|
||||
:alt: Add password to VM
|
||||
|
||||
* **Login with Azure Active Directory**. Choose "Off" (usually the default)
|
||||
* **Inbound port rules**. Leave the defaults for now, and we will update these later on in the Network configuration step.
|
||||
|
||||
#. Before clicking on "Next" we need to select the RAM size for the image.
|
||||
* For this we need to make sure we have enough RAM to accommodate your users. For example, if each user needs 2GB of RAM, and you have 10 total users, you need at least 20GB of RAM on the machine. It's also good to have a few GB of "buffer" RAM beyond what you think you'll need.
|
||||
* Click on **Change size** (see image below)
|
||||
|
||||
.. image:: ../images/providers/azure/size-vm.png
|
||||
:alt: Choose vm size
|
||||
|
||||
.. note:: For more information about estimating memory, CPU and disk needs check `The memory section in the TLJH documentation <https://tljh.jupyter.org/en/latest/howto/admin/resource-estimation.html>`_
|
||||
|
||||
* Select a suitable image (to check available images and prices in your region `click on this link <https://azuremarketplace.microsoft.com/en-gb/marketplace/apps/Canonical.UbuntuServer?tab=PlansAndPrice/?wt.mc_id=TLJH-github-taallard>`_).
|
||||
|
||||
#. Disks (Storage):
|
||||
* **Disk options**: select the OS disk type there are options for SDD and HDD. **SSD persistent disk** gives you a faster but more expensive disk than HDD.
|
||||
* **Data disk**. Click on create and attach a new disk. Select an appropriate type and size and click ok.
|
||||
* Click "Next".
|
||||
|
||||
.. image:: ../images/providers/azure/create-disk.png
|
||||
:alt: Create and attach disk
|
||||
|
||||
.. image:: ../images/providers/azure/disk-vm.png
|
||||
:alt: Choose a disk size
|
||||
|
||||
#. Networking
|
||||
* **Virtual network**. Leave the default values selected.
|
||||
* **Subnet**. Leave the default values selected.
|
||||
* **Public IP address**.Leave the default values selected. This will make your server accessible from a browser.
|
||||
* **Network Security Group**. Choose "Basic"
|
||||
* **Public inbound ports**. Check **HTTP**, **HTTPS**, and **SSH**.
|
||||
|
||||
.. image:: ../images/providers/azure/networking-vm.png
|
||||
:alt: Choose networking ports
|
||||
|
||||
#. Management
|
||||
* Monitoring
|
||||
* **Boot diagnostics**. Choose "On".
|
||||
* **OS guest diagnostics**. Choose "Off".
|
||||
* **Diagnostics storage account**. Leave as the default.
|
||||
* Auto-Shutdown
|
||||
* **Enable auto-shutdown**. Choose "Off".
|
||||
* Backup
|
||||
* **Backup**. Choose "Off".
|
||||
* System assigned managed identity Select "Off"
|
||||
|
||||
.. image:: ../images/providers/azure/backup-vm.png
|
||||
:alt: Choose VM Backup
|
||||
|
||||
#. Advanced settings
|
||||
* **Extensions**. Make sure there are no extensions listed
|
||||
* **Cloud init**. We are going to use this section to install TLJH directly into our Virtual Machine.
|
||||
Copy the code snippet below:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
#!/bin/bash
|
||||
curl -L https://tljh.jupyter.org/bootstrap.py \
|
||||
| sudo python3 - \
|
||||
--admin <admin-user-name>
|
||||
|
||||
where the ``username`` is the root username you chose for your Virtual Machine.
|
||||
|
||||
.. image:: ../images/providers/azure/cloudinit-vm.png
|
||||
:alt: Install TLJH
|
||||
|
||||
.. note::
|
||||
|
||||
See :ref:`topic/installer-actions` if you want to understand exactly what the installer is doing.
|
||||
:ref:`topic/customizing-installer` documents other options that can be passed to the installer.
|
||||
|
||||
#. Check the summary and confirm the creation of your Virtual Machine.
|
||||
|
||||
#. Check that the creation of your Virtual Machine worked.
|
||||
* Wait for the virtual machine to be created. This might take about 5-10 minutes.
|
||||
* After completion, you should see a similar screen to the one below:
|
||||
|
||||
.. image:: ../images/providers/azure/deployed-vm.png
|
||||
:alt: Deployed VM
|
||||
|
||||
#. Note that the Littlest JupyterHub should be installing in the background on your new server.
|
||||
It takes around 5-10 minutes for this installation to complete.
|
||||
|
||||
#. Click on the **Go to resource button**
|
||||
.. image:: ../images/providers/azure/goto-vm.png
|
||||
:alt: Go to VM
|
||||
|
||||
#. Check if the installation is completed by **copying** the **Public IP address** of your virtual machine, and trying to access it with a browser.
|
||||
|
||||
.. image:: ../images/providers/azure/ip-vm.png
|
||||
:alt: Public IP address
|
||||
|
||||
Note that accessing the JupyterHub will fail until the installation is complete, so be patient.
|
||||
|
||||
#. When the installation is complete, it should give you a JupyterHub login page.
|
||||
|
||||
.. image:: ../images/first-login.png
|
||||
:alt: JupyterHub log-in page
|
||||
|
||||
#. Login using the **admin user name** you used in step 6, 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.
|
||||
|
||||
#. Congratulations, you have a running working JupyterHub! 🎉
|
||||
|
||||
Step 2: Adding more users
|
||||
==========================
|
||||
|
||||
.. include:: add_users.txt
|
||||
|
||||
Step 3: Install conda / pip packages for all users
|
||||
==================================================
|
||||
|
||||
.. include:: add_packages.txt
|
||||
95
docs/install/custom-server.md
Normal file
95
docs/install/custom-server.md
Normal file
@@ -0,0 +1,95 @@
|
||||
(install-custom)=
|
||||
|
||||
# Installing on your own server
|
||||
|
||||
Follow this guide if your cloud provider doesn't have a direct tutorial, or
|
||||
you are setting this up on a bare metal server.
|
||||
|
||||
:::{warning}
|
||||
Do **not** install TLJH directly on your laptop or personal computer!
|
||||
It will most likely open up exploitable security holes when run directly
|
||||
on your personal computer.
|
||||
:::
|
||||
|
||||
:::{note}
|
||||
Running TLJH _inside_ a docker container is not supported, since we depend
|
||||
on systemd. If you want to run TLJH locally for development, see
|
||||
{ref}`contributing/dev-setup`.
|
||||
:::
|
||||
|
||||
## Goal
|
||||
|
||||
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
|
||||
a server you have access to.
|
||||
|
||||
## Pre-requisites
|
||||
|
||||
1. Some familiarity with the command line.
|
||||
2. A server running Ubuntu 20.04+ where you have root access (Ubuntu 22.04 LTS recommended).
|
||||
3. At least **1GB** of RAM on your server.
|
||||
4. Ability to `ssh` into the server & run commands from the prompt.
|
||||
5. An **IP address** where the server can be reached from the browsers of your target audience.
|
||||
|
||||
If you run into issues, look at the specific {ref}`troubleshooting guide <troubleshooting/providers/custom>`
|
||||
for custom server installations.
|
||||
|
||||
## Step 1: Installing The Littlest JupyterHub
|
||||
|
||||
1. Using a terminal program, SSH into your server. This should give you a prompt where you can
|
||||
type commands.
|
||||
|
||||
2. Make sure you have `python3`, `python3-dev`, `curl` and `git` installed.
|
||||
|
||||
```
|
||||
sudo apt install python3 python3-dev git curl
|
||||
```
|
||||
|
||||
3. Copy the text below, and paste it into the terminal. 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. **Remember to add your username**!
|
||||
|
||||
```bash
|
||||
curl -L https://tljh.jupyter.org/bootstrap.py | sudo -E python3 - --admin <admin-user-name>
|
||||
```
|
||||
|
||||
:::{note}
|
||||
See {ref}`topic/installer-actions` if you want to understand exactly what the installer is doing.
|
||||
{ref}`topic/customizing-installer` documents other options that can be passed to the installer.
|
||||
:::
|
||||
|
||||
4. Press `Enter` to start the installation process. This will take 5-10 minutes,
|
||||
and will say `Done!` when the installation process is complete.
|
||||
|
||||
5. Copy the **Public IP** of your server, and try accessing `http://<public-ip>` from
|
||||
your browser. If everything went well, this should give you a JupyterHub login page.
|
||||
|
||||
```{image} ../images/first-login.png
|
||||
:alt: JupyterHub log-in page
|
||||
```
|
||||
|
||||
6. Login using the **admin user name** you used in step 3. You can choose any
|
||||
password that you wish. Use a
|
||||
strong password & note it down somewhere, since this will be the password for
|
||||
the admin user account from now on.
|
||||
|
||||
7. Congratulations, you have a running working JupyterHub!
|
||||
|
||||
## Step 2: Adding more users
|
||||
|
||||
```{eval-rst}
|
||||
.. include:: add_users.txt
|
||||
```
|
||||
|
||||
## Step 3: Install conda / pip packages for all users
|
||||
|
||||
```{eval-rst}
|
||||
.. include:: add_packages.txt
|
||||
```
|
||||
|
||||
## Step 4: Setup HTTPS
|
||||
|
||||
Once you are ready to run your server for real, and have a domain, it's a good
|
||||
idea to proceed directly to {ref}`howto/admin/https`.
|
||||
@@ -1,99 +0,0 @@
|
||||
.. _install/custom:
|
||||
|
||||
=============================
|
||||
Installing on your own server
|
||||
=============================
|
||||
|
||||
|
||||
Follow this guide if your cloud provider doesn't have a direct tutorial, or
|
||||
you are setting this up on a bare metal server.
|
||||
|
||||
.. warning::
|
||||
|
||||
Do **not** install TLJH directly on your laptop or personal computer!
|
||||
It will most likely open up exploitable security holes when run directly
|
||||
on your personal computer.
|
||||
|
||||
.. note::
|
||||
|
||||
Running TLJH *inside* a docker container is not supported, since we depend
|
||||
on systemd. If you want to run TLJH locally for development, see
|
||||
:ref:`contributing/dev-setup`.
|
||||
|
||||
Goal
|
||||
====
|
||||
|
||||
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
|
||||
a server you have access to.
|
||||
|
||||
Pre-requisites
|
||||
==============
|
||||
|
||||
#. Some familiarity with the command line.
|
||||
#. A server running Ubuntu 20.04+ where you have root access (Ubuntu 22.04 LTS recommended).
|
||||
#. At least **1GB** of RAM on your server.
|
||||
#. Ability to ``ssh`` into the server & run commands from the prompt.
|
||||
#. An **IP address** where the server can be reached from the browsers of your target audience.
|
||||
|
||||
If you run into issues, look at the specific :ref:`troubleshooting guide <troubleshooting/providers/custom>`
|
||||
for custom server installations.
|
||||
|
||||
Step 1: Installing The Littlest JupyterHub
|
||||
==========================================
|
||||
|
||||
#. Using a terminal program, SSH into your server. This should give you a prompt where you can
|
||||
type commands.
|
||||
|
||||
#. Make sure you have ``python3``, ``python3-dev``, ``curl`` and ``git`` installed.
|
||||
|
||||
.. code::
|
||||
|
||||
sudo apt install python3 python3-dev git curl
|
||||
|
||||
#. Copy the text below, and paste it into the terminal. 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. **Remember to add your username**!
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
curl -L https://tljh.jupyter.org/bootstrap.py | sudo -E python3 - --admin <admin-user-name>
|
||||
|
||||
.. note::
|
||||
|
||||
See :ref:`topic/installer-actions` if you want to understand exactly what the installer is doing.
|
||||
:ref:`topic/customizing-installer` documents other options that can be passed to the installer.
|
||||
|
||||
#. Press ``Enter`` to start the installation process. This will take 5-10 minutes,
|
||||
and will say ``Done!`` when the installation process is complete.
|
||||
|
||||
#. Copy the **Public IP** of your server, and try accessing ``http://<public-ip>`` from
|
||||
your browser. If everything went well, this should give you a JupyterHub login page.
|
||||
|
||||
.. image:: ../images/first-login.png
|
||||
:alt: JupyterHub log-in page
|
||||
|
||||
#. Login using the **admin user name** you used in step 3. You can choose any
|
||||
password that you wish. Use a
|
||||
strong password & note it down somewhere, since this will be the password for
|
||||
the admin user account from now on.
|
||||
|
||||
#. Congratulations, you have a running working JupyterHub!
|
||||
|
||||
Step 2: Adding more users
|
||||
==========================
|
||||
|
||||
.. include:: add_users.txt
|
||||
|
||||
Step 3: Install conda / pip packages for all users
|
||||
==================================================
|
||||
|
||||
.. include:: add_packages.txt
|
||||
|
||||
Step 4: Setup HTTPS
|
||||
===================
|
||||
|
||||
Once you are ready to run your server for real, and have a domain, it's a good
|
||||
idea to proceed directly to :ref:`howto/admin/https`.
|
||||
123
docs/install/digitalocean.md
Normal file
123
docs/install/digitalocean.md
Normal file
@@ -0,0 +1,123 @@
|
||||
(insatll-digitalocean)=
|
||||
|
||||
# Installing on Digital Ocean
|
||||
|
||||
## Goal
|
||||
|
||||
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
|
||||
[DigitalOcean](https://digitalocean.com).
|
||||
|
||||
## Pre-requisites
|
||||
|
||||
1. A DigitalOcean account with a payment method attached.
|
||||
|
||||
## Step 1: Installing The Littlest JupyterHub
|
||||
|
||||
Let's create the server on which we can run JupyterHub.
|
||||
|
||||
1. Log in to [DigitalOcean](https://digitalocean.com). You might need to
|
||||
attach a credit card or other payment method to your account before you
|
||||
can proceed with the tutorial.
|
||||
|
||||
2. Click the **Create** button on the top right, and select **Droplets** from
|
||||
the dropdown menu. DigitalOcean calls servers **droplets**.
|
||||
|
||||
```{image} ../images/providers/digitalocean/create-menu.png
|
||||
:alt: Dropdown menu on clicking 'create' in top right corner
|
||||
```
|
||||
|
||||
This takes you to a page titled **Create Droplets** that lets you configure
|
||||
your server.
|
||||
|
||||
3. Under **Choose an image**, select **22.04 x64** under **Ubuntu**.
|
||||
|
||||
```{image} ../images/providers/digitalocean/select-image.png
|
||||
:alt: Select 22.04 x64 image under Ubuntu
|
||||
```
|
||||
|
||||
4. Under **Choose a size**, select the size of the server you want. The default
|
||||
(4GB RAM, 2CPUs, 20 USD / month) is not a bad start. You can resize your server
|
||||
later if you need.
|
||||
|
||||
Check out our guide on How To {ref}`howto/admin/resource-estimation` to help pick
|
||||
how much Memory, CPU & disk space your server needs.
|
||||
|
||||
5. Scroll down to **Select additional options**, and select **User data**.
|
||||
|
||||
```{image} ../images/providers/digitalocean/additional-options.png
|
||||
:alt: Turn on User Data in additional options
|
||||
```
|
||||
|
||||
This opens up a textbox where you can enter a script that will be run
|
||||
when the server is created. We will use this to set up The Littlest JupyterHub
|
||||
on this server.
|
||||
|
||||
6. Copy the text below, and paste it into the user data text box. Replace
|
||||
`<admin-user-name>` with the name of the first **admin user** for this
|
||||
JupyterHub. This admin user can log in after the JupyterHub is set up, and
|
||||
can configure it to their needs. **Remember to add your username**!
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
curl -L https://tljh.jupyter.org/bootstrap.py \
|
||||
| sudo python3 - \
|
||||
--admin <admin-user-name>
|
||||
```
|
||||
|
||||
:::{note}
|
||||
See {ref}`topic/installer-actions` if you want to understand exactly what the installer is doing.
|
||||
{ref}`topic/customizing-installer` documents other options that can be passed to the installer.
|
||||
:::
|
||||
|
||||
7. Under the **Finalize and create** section, enter a `hostname` that descriptively
|
||||
identifies this server for you.
|
||||
|
||||
```{image} ../images/providers/digitalocean/hostname.png
|
||||
:alt: Select suitable hostname for your server
|
||||
```
|
||||
|
||||
8. Click the **Create** button! You will be taken to a different screen,
|
||||
where you can see progress of your server being created.
|
||||
|
||||
```{image} ../images/providers/digitalocean/server-create-wait.png
|
||||
:alt: Server being created
|
||||
```
|
||||
|
||||
9. In a few seconds your server will be created, and you can see the **public IP**
|
||||
used to access it.
|
||||
|
||||
```{image} ../images/providers/digitalocean/server-create-done.png
|
||||
:alt: Server finished creating, public IP available
|
||||
```
|
||||
|
||||
10. The Littlest JupyterHub is now installing in the background on your new server.
|
||||
It takes around 5-10 minutes for this installation to complete.
|
||||
|
||||
11. Check if the installation is complete by copying the **public ip**
|
||||
of your server, and trying to access it with a browser. This will fail until
|
||||
the installation is complete, so be patient.
|
||||
|
||||
12. When the installation is complete, it should give you a JupyterHub login page.
|
||||
|
||||
```{image} ../images/first-login.png
|
||||
:alt: JupyterHub log-in page
|
||||
```
|
||||
|
||||
13. Login using the **admin user name** you used in step 6, 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.
|
||||
|
||||
14. Congratulations, you have a running working JupyterHub!
|
||||
|
||||
## Step 2: Adding more users
|
||||
|
||||
```{eval-rst}
|
||||
.. include:: add_users.txt
|
||||
```
|
||||
|
||||
## Step 3: Install conda / pip packages for all users
|
||||
|
||||
```{eval-rst}
|
||||
.. include:: add_packages.txt
|
||||
```
|
||||
@@ -1,119 +0,0 @@
|
||||
.. _insatll/digitalocean:
|
||||
|
||||
===========================
|
||||
Installing on Digital Ocean
|
||||
===========================
|
||||
|
||||
Goal
|
||||
====
|
||||
|
||||
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
|
||||
`DigitalOcean <https://digitalocean.com>`_.
|
||||
|
||||
Pre-requisites
|
||||
==============
|
||||
|
||||
#. A DigitalOcean account with a payment method attached.
|
||||
|
||||
Step 1: Installing The Littlest JupyterHub
|
||||
==========================================
|
||||
|
||||
Let's create the server on which we can run JupyterHub.
|
||||
|
||||
#. Log in to `DigitalOcean <https://digitalocean.com>`_. You might need to
|
||||
attach a credit card or other payment method to your account before you
|
||||
can proceed with the tutorial.
|
||||
|
||||
#. Click the **Create** button on the top right, and select **Droplets** from
|
||||
the dropdown menu. DigitalOcean calls servers **droplets**.
|
||||
|
||||
.. image:: ../images/providers/digitalocean/create-menu.png
|
||||
:alt: Dropdown menu on clicking 'create' in top right corner
|
||||
|
||||
This takes you to a page titled **Create Droplets** that lets you configure
|
||||
your server.
|
||||
|
||||
#. Under **Choose an image**, select **22.04 x64** under **Ubuntu**.
|
||||
|
||||
.. image:: ../images/providers/digitalocean/select-image.png
|
||||
:alt: Select 22.04 x64 image under Ubuntu
|
||||
|
||||
#. Under **Choose a size**, select the size of the server you want. The default
|
||||
(4GB RAM, 2CPUs, 20 USD / month) is not a bad start. You can resize your server
|
||||
later if you need.
|
||||
|
||||
Check out our guide on How To :ref:`howto/admin/resource-estimation` to help pick
|
||||
how much Memory, CPU & disk space your server needs.
|
||||
|
||||
#. Scroll down to **Select additional options**, and select **User data**.
|
||||
|
||||
.. image:: ../images/providers/digitalocean/additional-options.png
|
||||
:alt: Turn on User Data in additional options
|
||||
|
||||
This opens up a textbox where you can enter a script that will be run
|
||||
when the server is created. We will use this to set up The Littlest JupyterHub
|
||||
on this server.
|
||||
|
||||
#. Copy the text below, and paste it into the user data text box. Replace
|
||||
``<admin-user-name>`` with the name of the first **admin user** for this
|
||||
JupyterHub. This admin user can log in after the JupyterHub is set up, and
|
||||
can configure it to their needs. **Remember to add your username**!
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
#!/bin/bash
|
||||
curl -L https://tljh.jupyter.org/bootstrap.py \
|
||||
| sudo python3 - \
|
||||
--admin <admin-user-name>
|
||||
|
||||
.. note::
|
||||
|
||||
See :ref:`topic/installer-actions` if you want to understand exactly what the installer is doing.
|
||||
:ref:`topic/customizing-installer` documents other options that can be passed to the installer.
|
||||
|
||||
#. Under the **Finalize and create** section, enter a ``hostname`` that descriptively
|
||||
identifies this server for you.
|
||||
|
||||
.. image:: ../images/providers/digitalocean/hostname.png
|
||||
:alt: Select suitable hostname for your server
|
||||
|
||||
#. Click the **Create** button! You will be taken to a different screen,
|
||||
where you can see progress of your server being created.
|
||||
|
||||
.. image:: ../images/providers/digitalocean/server-create-wait.png
|
||||
:alt: Server being created
|
||||
|
||||
#. In a few seconds your server will be created, and you can see the **public IP**
|
||||
used to access it.
|
||||
|
||||
.. image:: ../images/providers/digitalocean/server-create-done.png
|
||||
:alt: Server finished creating, public IP available
|
||||
|
||||
#. The Littlest JupyterHub is now installing in the background on your new server.
|
||||
It takes around 5-10 minutes for this installation to complete.
|
||||
|
||||
#. Check if the installation is complete by copying the **public ip**
|
||||
of your server, and trying to access it with a browser. This will fail until
|
||||
the installation is complete, so be patient.
|
||||
|
||||
#. When the installation is complete, it should give you a JupyterHub login page.
|
||||
|
||||
.. image:: ../images/first-login.png
|
||||
:alt: JupyterHub log-in page
|
||||
|
||||
#. Login using the **admin user name** you used in step 6, 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.
|
||||
|
||||
#. Congratulations, you have a running working JupyterHub!
|
||||
|
||||
Step 2: Adding more users
|
||||
==========================
|
||||
|
||||
.. include:: add_users.txt
|
||||
|
||||
Step 3: Install conda / pip packages for all users
|
||||
==================================================
|
||||
|
||||
.. include:: add_packages.txt
|
||||
219
docs/install/google.md
Normal file
219
docs/install/google.md
Normal file
@@ -0,0 +1,219 @@
|
||||
(install-google)=
|
||||
|
||||
# Installing on Google Cloud
|
||||
|
||||
## Goal
|
||||
|
||||
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
|
||||
[Google Cloud](https://cloud.google.com/).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. A Google Cloud account. You might use the free credits for trying it out!
|
||||
|
||||
## Step 1: Installing The Littlest JupyterHub
|
||||
|
||||
Let's create the server on which we can run JupyterHub.
|
||||
|
||||
1. Log in to [Google Cloud Console](https://console.cloud.google.com) with
|
||||
your Google Account.
|
||||
|
||||
2. Open the navigation menu by clicking the button with three lines on the top
|
||||
left corner of the page.
|
||||
|
||||
```{image} ../images/providers/google/left-menu-button.png
|
||||
:alt: Button to open the menu
|
||||
```
|
||||
|
||||
This opens a menu with all the cloud products Google Cloud offers.
|
||||
|
||||
3. Under **Compute Engine**, select **VM Instances**.
|
||||
|
||||
```{image} ../images/providers/google/vm-instances-menu.png
|
||||
:alt: Navigation Menu -> Compute Engine -> VM Instances
|
||||
```
|
||||
|
||||
4. If you are using Google Cloud for the first time, you might have to
|
||||
enable billing. Google will present a screen asking you to enable billing
|
||||
to proceed. Click the **Enable Billing** button and follow any prompts
|
||||
that appear.
|
||||
|
||||
```{image} ../images/providers/google/enable-billing.png
|
||||
:alt: Enable billing if needed.
|
||||
```
|
||||
|
||||
It might take a few minutes for your account to be set up.
|
||||
|
||||
5. Once Compute Engine is ready, click the **Create** button to start
|
||||
creating the server that'll run TLJH.
|
||||
|
||||
```{image} ../images/providers/google/create-vm-first.png
|
||||
:alt: Create VM page when using it for the first time.
|
||||
```
|
||||
|
||||
If you already have VMs running in your project, the screen will look
|
||||
different. But you can find the **Create** button still!
|
||||
|
||||
6. This shows you a page titled **Create an instance**. This lets you customize
|
||||
the kind of server you want, the resources it will have & what it'll be called.
|
||||
|
||||
7. Under **Name**, give it a memorable name that identifies what purpose this
|
||||
JupyterHub will be used for.
|
||||
|
||||
8. **Region** specifies the physical location where this server will be hosted.
|
||||
Generally, pick something close to where most of your users are. Note that
|
||||
it might increase the cost of your server in some cases!
|
||||
|
||||
9. For **Zone**, pick any of the options. Leaving the default as is is fine.
|
||||
|
||||
10. Under **Machine** type, select the amount of CPU / RAM / GPU you want for your
|
||||
server. You need at least **1GB** of RAM.
|
||||
|
||||
You can select a preset combination in the default **basic view**.
|
||||
|
||||
```{image} ../images/providers/google/machine-type-basic.png
|
||||
:alt: Select a preset VM type
|
||||
```
|
||||
|
||||
If you want to add **GPUs**, you should click the **Customize** button &
|
||||
use the **Advanced View**. You need to request [a quota increase](https://cloud.google.com/compute/quotas#gpus)
|
||||
before you can use GPUs.
|
||||
|
||||
```{image} ../images/providers/google/machine-type-advanced.png
|
||||
:alt: Select a customized VM size
|
||||
```
|
||||
|
||||
Check out our guide on How To {ref}`howto/admin/resource-estimation` to help pick
|
||||
how much Memory / CPU your server needs.
|
||||
|
||||
11. Under **Boot Disk**, click the **Change** button. This lets us change the
|
||||
operating system and the size of your disk.
|
||||
|
||||
```{image} ../images/providers/google/boot-disk-button.png
|
||||
:alt: Changing Boot Disk & disk size
|
||||
```
|
||||
|
||||
This should open a **Boot disk** popup.
|
||||
|
||||
12. Select **Ubuntu 22.04 LTS** from the list of operating system images.
|
||||
|
||||
```{image} ../images/providers/google/boot-disk-ubuntu.png
|
||||
:alt: Selecting Ubuntu 22.04 for OS
|
||||
```
|
||||
|
||||
13. You can also change the **type** and **size** of your disk at the bottom
|
||||
of this popup.
|
||||
|
||||
```{image} ../images/providers/google/boot-disk-size.png
|
||||
:alt: Selecting Boot disk type & size
|
||||
```
|
||||
|
||||
**Standard persistent disk** type gives you a slower but cheaper disk, similar
|
||||
to a hard drive. **SSD persistent disk** gives you a faster but more expensive
|
||||
disk, similar to an SSD.
|
||||
|
||||
Check out our guide on How To {ref}`howto/admin/resource-estimation` to help pick
|
||||
how much Disk space your server needs.
|
||||
|
||||
14. Click the **Select** button to dismiss the Boot disk popup and go back to the
|
||||
Create an instance screen.
|
||||
|
||||
15. Under **Identity and API access**, select **No service account** for the
|
||||
**Service account** field. This prevents your JupyterHub users from automatically
|
||||
accessing other cloud services, increasing security.
|
||||
|
||||
```{image} ../images/providers/google/no-service-account.png
|
||||
:alt: Disable service accounts for the server
|
||||
```
|
||||
|
||||
16. Under **Firewall**, check both **Allow HTTP Traffic** and **Allow HTTPS Traffic**
|
||||
checkboxes.
|
||||
|
||||
```{image} ../images/providers/google/firewall.png
|
||||
:alt: Allow HTTP & HTTPS traffic to your server
|
||||
```
|
||||
|
||||
17. Click the **Management, disks, networking, SSH keys** link to expand more
|
||||
options.
|
||||
|
||||
```{image} ../images/providers/google/management-button.png
|
||||
:alt: Expand management options by clicking link.
|
||||
```
|
||||
|
||||
This displays a lot of advanced options, but we'll be only using one of them.
|
||||
|
||||
18. Copy the text below, and paste it into the **Startup script** text box. Replace
|
||||
`<admin-user-name>` with the name of the first **admin user** for this
|
||||
JupyterHub. This admin user can log in after the JupyterHub is set up, and
|
||||
can configure it to their needs. **Remember to add your username**!
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
curl -L https://tljh.jupyter.org/bootstrap.py \
|
||||
| sudo python3 - \
|
||||
--admin <admin-user-name>
|
||||
```
|
||||
|
||||
```{image} ../images/providers/google/startup-script.png
|
||||
:alt: Install JupyterHub with the Startup script textbox
|
||||
```
|
||||
|
||||
:::{note}
|
||||
See {ref}`topic/installer-actions` if you want to understand exactly what the installer is doing.
|
||||
{ref}`topic/customizing-installer` documents other options that can be passed to the installer.
|
||||
:::
|
||||
|
||||
19. Click the **Create** button at the bottom to start your server!
|
||||
|
||||
```{image} ../images/providers/google/create-vm-button.png
|
||||
:alt: Launch an Instance / Advanced Options dialog box
|
||||
```
|
||||
|
||||
20. We'll be sent to the **VM instances** page, where we can see that our server
|
||||
is being created.
|
||||
|
||||
```{image} ../images/providers/google/vm-creating.png
|
||||
:alt: Spinner with vm creating
|
||||
```
|
||||
|
||||
21. In a few seconds your server will be created, and you can see the **External IP**
|
||||
used to access it.
|
||||
|
||||
```{image} ../images/providers/google/vm-created.png
|
||||
:alt: VM created, external IP available
|
||||
```
|
||||
|
||||
22. The Littlest JupyterHub is now installing in the background on your new server.
|
||||
It takes around 5-10 minutes for this installation to complete.
|
||||
|
||||
23. Check if the installation is complete by **copying** the **External IP**
|
||||
of your server, and trying to access it with a browser. Do **not click** on the
|
||||
IP - this will open the link with HTTPS, and will not work.
|
||||
|
||||
Accessing the JupyterHub will also fail until the installation is complete,
|
||||
so be patient.
|
||||
|
||||
24. When the installation is complete, it should give you a JupyterHub login page.
|
||||
|
||||
```{image} ../images/first-login.png
|
||||
:alt: JupyterHub log-in page
|
||||
```
|
||||
|
||||
25. Login using the **admin user name** you used in step 6, 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.
|
||||
|
||||
26. Congratulations, you have a running working JupyterHub!
|
||||
|
||||
## Step 2: Adding more users
|
||||
|
||||
```{eval-rst}
|
||||
.. include:: add_users.txt
|
||||
```
|
||||
|
||||
## Step 3: Install conda / pip packages for all users
|
||||
|
||||
```{eval-rst}
|
||||
.. include:: add_packages.txt
|
||||
```
|
||||
@@ -1,205 +0,0 @@
|
||||
.. _install/google:
|
||||
|
||||
==========================
|
||||
Installing on Google Cloud
|
||||
==========================
|
||||
|
||||
Goal
|
||||
====
|
||||
|
||||
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
|
||||
`Google Cloud <https://cloud.google.com/>`_.
|
||||
|
||||
Prerequisites
|
||||
=============
|
||||
|
||||
#. A Google Cloud account. You might use the free credits for trying it out!
|
||||
|
||||
Step 1: Installing The Littlest JupyterHub
|
||||
==========================================
|
||||
|
||||
Let's create the server on which we can run JupyterHub.
|
||||
|
||||
#. Log in to `Google Cloud Console <https://console.cloud.google.com>`_ with
|
||||
your Google Account.
|
||||
|
||||
#. Open the navigation menu by clicking the button with three lines on the top
|
||||
left corner of the page.
|
||||
|
||||
.. image:: ../images/providers/google/left-menu-button.png
|
||||
:alt: Button to open the menu
|
||||
|
||||
This opens a menu with all the cloud products Google Cloud offers.
|
||||
|
||||
#. Under **Compute Engine**, select **VM Instances**.
|
||||
|
||||
.. image:: ../images/providers/google/vm-instances-menu.png
|
||||
:alt: Navigation Menu -> Compute Engine -> VM Instances
|
||||
|
||||
#. If you are using Google Cloud for the first time, you might have to
|
||||
enable billing. Google will present a screen asking you to enable billing
|
||||
to proceed. Click the **Enable Billing** button and follow any prompts
|
||||
that appear.
|
||||
|
||||
.. image:: ../images/providers/google/enable-billing.png
|
||||
:alt: Enable billing if needed.
|
||||
|
||||
It might take a few minutes for your account to be set up.
|
||||
|
||||
#. Once Compute Engine is ready, click the **Create** button to start
|
||||
creating the server that'll run TLJH.
|
||||
|
||||
.. image:: ../images/providers/google/create-vm-first.png
|
||||
:alt: Create VM page when using it for the first time.
|
||||
|
||||
If you already have VMs running in your project, the screen will look
|
||||
different. But you can find the **Create** button still!
|
||||
|
||||
#. This shows you a page titled **Create an instance**. This lets you customize
|
||||
the kind of server you want, the resources it will have & what it'll be called.
|
||||
|
||||
#. Under **Name**, give it a memorable name that identifies what purpose this
|
||||
JupyterHub will be used for.
|
||||
|
||||
#. **Region** specifies the physical location where this server will be hosted.
|
||||
Generally, pick something close to where most of your users are. Note that
|
||||
it might increase the cost of your server in some cases!
|
||||
|
||||
#. For **Zone**, pick any of the options. Leaving the default as is is fine.
|
||||
|
||||
#. Under **Machine** type, select the amount of CPU / RAM / GPU you want for your
|
||||
server. You need at least **1GB** of RAM.
|
||||
|
||||
You can select a preset combination in the default **basic view**.
|
||||
|
||||
.. image:: ../images/providers/google/machine-type-basic.png
|
||||
:alt: Select a preset VM type
|
||||
|
||||
If you want to add **GPUs**, you should click the **Customize** button &
|
||||
use the **Advanced View**. You need to request `a quota increase <https://cloud.google.com/compute/quotas#gpus>`_
|
||||
before you can use GPUs.
|
||||
|
||||
.. image:: ../images/providers/google/machine-type-advanced.png
|
||||
:alt: Select a customized VM size
|
||||
|
||||
Check out our guide on How To :ref:`howto/admin/resource-estimation` to help pick
|
||||
how much Memory / CPU your server needs.
|
||||
|
||||
#. Under **Boot Disk**, click the **Change** button. This lets us change the
|
||||
operating system and the size of your disk.
|
||||
|
||||
.. image:: ../images/providers/google/boot-disk-button.png
|
||||
:alt: Changing Boot Disk & disk size
|
||||
|
||||
This should open a **Boot disk** popup.
|
||||
|
||||
#. Select **Ubuntu 22.04 LTS** from the list of operating system images.
|
||||
|
||||
.. image:: ../images/providers/google/boot-disk-ubuntu.png
|
||||
:alt: Selecting Ubuntu 22.04 for OS
|
||||
|
||||
#. You can also change the **type** and **size** of your disk at the bottom
|
||||
of this popup.
|
||||
|
||||
.. image:: ../images/providers/google/boot-disk-size.png
|
||||
:alt: Selecting Boot disk type & size
|
||||
|
||||
**Standard persistent disk** type gives you a slower but cheaper disk, similar
|
||||
to a hard drive. **SSD persistent disk** gives you a faster but more expensive
|
||||
disk, similar to an SSD.
|
||||
|
||||
Check out our guide on How To :ref:`howto/admin/resource-estimation` to help pick
|
||||
how much Disk space your server needs.
|
||||
|
||||
#. Click the **Select** button to dismiss the Boot disk popup and go back to the
|
||||
Create an instance screen.
|
||||
|
||||
#. Under **Identity and API access**, select **No service account** for the
|
||||
**Service account** field. This prevents your JupyterHub users from automatically
|
||||
accessing other cloud services, increasing security.
|
||||
|
||||
.. image:: ../images/providers/google/no-service-account.png
|
||||
:alt: Disable service accounts for the server
|
||||
|
||||
#. Under **Firewall**, check both **Allow HTTP Traffic** and **Allow HTTPS Traffic**
|
||||
checkboxes.
|
||||
|
||||
.. image:: ../images/providers/google/firewall.png
|
||||
:alt: Allow HTTP & HTTPS traffic to your server
|
||||
|
||||
#. Click the **Management, disks, networking, SSH keys** link to expand more
|
||||
options.
|
||||
|
||||
.. image:: ../images/providers/google/management-button.png
|
||||
:alt: Expand management options by clicking link.
|
||||
|
||||
This displays a lot of advanced options, but we'll be only using one of them.
|
||||
|
||||
#. Copy the text below, and paste it into the **Startup script** text box. Replace
|
||||
``<admin-user-name>`` with the name of the first **admin user** for this
|
||||
JupyterHub. This admin user can log in after the JupyterHub is set up, and
|
||||
can configure it to their needs. **Remember to add your username**!
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
#!/bin/bash
|
||||
curl -L https://tljh.jupyter.org/bootstrap.py \
|
||||
| sudo python3 - \
|
||||
--admin <admin-user-name>
|
||||
|
||||
.. image:: ../images/providers/google/startup-script.png
|
||||
:alt: Install JupyterHub with the Startup script textbox
|
||||
|
||||
.. note::
|
||||
|
||||
See :ref:`topic/installer-actions` if you want to understand exactly what the installer is doing.
|
||||
:ref:`topic/customizing-installer` documents other options that can be passed to the installer.
|
||||
|
||||
#. Click the **Create** button at the bottom to start your server!
|
||||
|
||||
.. image:: ../images/providers/google/create-vm-button.png
|
||||
:alt: Launch an Instance / Advanced Options dialog box
|
||||
|
||||
#. We'll be sent to the **VM instances** page, where we can see that our server
|
||||
is being created.
|
||||
|
||||
.. image:: ../images/providers/google/vm-creating.png
|
||||
:alt: Spinner with vm creating
|
||||
|
||||
#. In a few seconds your server will be created, and you can see the **External IP**
|
||||
used to access it.
|
||||
|
||||
.. image:: ../images/providers/google/vm-created.png
|
||||
:alt: VM created, external IP available
|
||||
|
||||
#. The Littlest JupyterHub is now installing in the background on your new server.
|
||||
It takes around 5-10 minutes for this installation to complete.
|
||||
|
||||
#. Check if the installation is complete by **copying** the **External IP**
|
||||
of your server, and trying to access it with a browser. Do **not click** on the
|
||||
IP - this will open the link with HTTPS, and will not work.
|
||||
|
||||
Accessing the JupyterHub will also fail until the installation is complete,
|
||||
so be patient.
|
||||
|
||||
#. When the installation is complete, it should give you a JupyterHub login page.
|
||||
|
||||
.. image:: ../images/first-login.png
|
||||
:alt: JupyterHub log-in page
|
||||
|
||||
#. Login using the **admin user name** you used in step 6, 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.
|
||||
|
||||
#. Congratulations, you have a running working JupyterHub!
|
||||
|
||||
Step 2: Adding more users
|
||||
==========================
|
||||
|
||||
.. include:: add_users.txt
|
||||
|
||||
Step 3: Install conda / pip packages for all users
|
||||
==================================================
|
||||
|
||||
.. include:: add_packages.txt
|
||||
@@ -1,8 +1,6 @@
|
||||
.. _install/installing:
|
||||
(install-installing)=
|
||||
|
||||
==========
|
||||
Installing
|
||||
==========
|
||||
# Installing
|
||||
|
||||
The Littlest JupyterHub (TLJH) can run on any server that is running **Debian 11** or **Ubuntu 20.04** or **22.04** on a amd64 or arm64 CPU architecture.
|
||||
Earlier versions of Ubuntu and Debian are not supported, nor are other Linux distributions.
|
||||
@@ -12,13 +10,14 @@ Tutorials to create a new server from scratch on a cloud provider & run TLJH
|
||||
on it. These are **recommended** if you do not have much experience setting up
|
||||
servers.
|
||||
|
||||
.. toctree::
|
||||
:titlesonly:
|
||||
|
||||
digitalocean
|
||||
ovh
|
||||
jetstream
|
||||
google
|
||||
amazon
|
||||
azure
|
||||
custom-server
|
||||
> ```{toctree}
|
||||
> :titlesonly: true
|
||||
>
|
||||
> digitalocean
|
||||
> ovh
|
||||
> jetstream
|
||||
> google
|
||||
> amazon
|
||||
> azure
|
||||
> custom-server
|
||||
> ```
|
||||
152
docs/install/jetstream.md
Normal file
152
docs/install/jetstream.md
Normal file
@@ -0,0 +1,152 @@
|
||||
(install-jetstream)=
|
||||
|
||||
# Installing on Jetstream
|
||||
|
||||
## Goal
|
||||
|
||||
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/).
|
||||
|
||||
## 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).
|
||||
|
||||
## Step 1: Installing The Littlest JupyterHub
|
||||
|
||||
Let's create the server on which we can run JupyterHub.
|
||||
|
||||
1. Log in to [the Jetstream portal](https://use.jetstream-cloud.org/). You need an allocation
|
||||
to launch instances.
|
||||
|
||||
2. Select the **Launch New Instance** option to get going.
|
||||
|
||||
```{image} ../images/providers/jetstream/launch-instance-first-button.png
|
||||
:alt: Launch new instance button with description.
|
||||
```
|
||||
|
||||
This takes you to a page with a list of base images you can choose for your
|
||||
server.
|
||||
|
||||
3. Under **Image Search**, search for **Ubuntu 22.04**, and select the
|
||||
**Ubuntu 22.04 Devel and Docker** image.
|
||||
|
||||
```{image} ../images/providers/jetstream/select-image.png
|
||||
:alt: Select Ubuntu 22.04 x64 image from image list
|
||||
```
|
||||
|
||||
4. Once selected, you will see more information about this image. Click the
|
||||
**Launch** button on the top right.
|
||||
|
||||
```{image} ../images/providers/jetstream/launch-instance-second-button.png
|
||||
:alt: Launch selected image with Launch button on top right
|
||||
```
|
||||
|
||||
5. A dialog titled **Launch an Instance / Basic Options** pops up, with various
|
||||
options for configuring your instance.
|
||||
|
||||
```{image} ../images/providers/jetstream/launch-instance-dialog.png
|
||||
:alt: Launch an Instance / Basic Options dialog box
|
||||
```
|
||||
|
||||
1. Give your server a descriptive **Instance Name**.
|
||||
|
||||
2. Select an appropriate **Instance Size**. We suggest m1.medium or larger.
|
||||
Make sure your instance has at least **1GB** of RAM.
|
||||
|
||||
Check out our guide on How To {ref}`howto/admin/resource-estimation` to help pick
|
||||
how much Memory, CPU & disk space your server needs.
|
||||
|
||||
3. If you have multiple allocations, make sure you are 'charging' this server
|
||||
to the correct allocation.
|
||||
|
||||
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.
|
||||
|
||||
A dialog titled **Launch an Instance / Advanced Options** should pop up.
|
||||
|
||||
```{image} ../images/providers/jetstream/add-deployment-script-dialog.png
|
||||
:alt: Dialog box allowing you to add a new script.
|
||||
```
|
||||
|
||||
7. Click the **Create New Script** button. This will open up another dialog
|
||||
box!
|
||||
|
||||
```{image} ../images/providers/jetstream/create-script-dialog.png
|
||||
:alt: Launch an Instance / Advanced Options dialog box
|
||||
```
|
||||
|
||||
8. Under **Input Type**, select **Raw Text**. This should make a text box titled
|
||||
**Raw Text** visible on the right side of the dialog box.
|
||||
Copy the text below, and paste it into the **Raw Text** text box. Replace
|
||||
`<admin-user-name>` with the name of the first **admin user** for this
|
||||
JupyterHub. This admin user can log in after the JupyterHub is set up, and
|
||||
can configure it to their needs. **Remember to add your username**!
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
curl -L https://tljh.jupyter.org/bootstrap.py \
|
||||
| sudo python3 - \
|
||||
--admin <admin-user-name>
|
||||
```
|
||||
|
||||
:::{note}
|
||||
See {ref}`topic/installer-actions` if you want to understand exactly what the installer is doing.
|
||||
{ref}`topic/customizing-installer` documents other options that can be passed to the installer.
|
||||
:::
|
||||
|
||||
9. Under **Execution Strategy Type**, select **Run script on first boot**.
|
||||
|
||||
10. Under **Deployment Type**, select **Wait for script to complete**.
|
||||
|
||||
11. Click the **Save and Add Script** button on the bottom right. This should hide
|
||||
the dialog box.
|
||||
|
||||
12. Click the **Continue to Launch** button on the bottom right. This should put you
|
||||
back in the **Launch an Instance / Basic Options** dialog box again.
|
||||
|
||||
13. Click the **Launch Instance** button on the bottom right. This should turn it
|
||||
into a spinner, and your server is getting created!
|
||||
|
||||
```{image} ../images/providers/jetstream/launching-spinner.png
|
||||
:alt: Launch button turns into a spinner
|
||||
```
|
||||
|
||||
14. You'll now be shown a dashboard with all your servers and their states. The
|
||||
server you just launched will progress through various stages of set up,
|
||||
and you can see the progress here.
|
||||
|
||||
```{image} ../images/providers/jetstream/deployment-in-progress.png
|
||||
: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
|
||||
|
||||
```{eval-rst}
|
||||
.. include:: add_users.txt
|
||||
```
|
||||
|
||||
## Step 3: Install conda / pip packages for all users
|
||||
|
||||
```{eval-rst}
|
||||
.. include:: add_packages.txt
|
||||
```
|
||||
@@ -1,145 +0,0 @@
|
||||
.. _install/jetstream:
|
||||
|
||||
=======================
|
||||
Installing on Jetstream
|
||||
=======================
|
||||
|
||||
Goal
|
||||
====
|
||||
|
||||
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/>`_.
|
||||
|
||||
Prerequisites
|
||||
=============
|
||||
|
||||
#. A Jetstream account with an XSEDE allocation; for more information,
|
||||
see the `Jetstream Allocations help page <http://wiki.jetstream-cloud.org/Jetstream+Allocations>`_.
|
||||
|
||||
Step 1: Installing The Littlest JupyterHub
|
||||
==========================================
|
||||
|
||||
Let's create the server on which we can run JupyterHub.
|
||||
|
||||
#. Log in to `the Jetstream portal <https://use.jetstream-cloud.org/>`_. You need an allocation
|
||||
to launch instances.
|
||||
|
||||
#. Select the **Launch New Instance** option to get going.
|
||||
|
||||
.. image:: ../images/providers/jetstream/launch-instance-first-button.png
|
||||
:alt: Launch new instance button with description.
|
||||
|
||||
This takes you to a page with a list of base images you can choose for your
|
||||
server.
|
||||
|
||||
#. Under **Image Search**, search for **Ubuntu 22.04**, and select the
|
||||
**Ubuntu 22.04 Devel and Docker** image.
|
||||
|
||||
.. image:: ../images/providers/jetstream/select-image.png
|
||||
:alt: Select Ubuntu 22.04 x64 image from image list
|
||||
|
||||
#. Once selected, you will see more information about this image. Click the
|
||||
**Launch** button on the top right.
|
||||
|
||||
.. image:: ../images/providers/jetstream/launch-instance-second-button.png
|
||||
:alt: Launch selected image with Launch button on top right
|
||||
|
||||
#. A dialog titled **Launch an Instance / Basic Options** pops up, with various
|
||||
options for configuring your instance.
|
||||
|
||||
.. image:: ../images/providers/jetstream/launch-instance-dialog.png
|
||||
:alt: Launch an Instance / Basic Options dialog box
|
||||
|
||||
#. Give your server a descriptive **Instance Name**.
|
||||
#. Select an appropriate **Instance Size**. We suggest m1.medium or larger.
|
||||
Make sure your instance has at least **1GB** of RAM.
|
||||
|
||||
Check out our guide on How To :ref:`howto/admin/resource-estimation` to help pick
|
||||
how much Memory, CPU & disk space your server needs.
|
||||
|
||||
#. If you have multiple allocations, make sure you are 'charging' this server
|
||||
to the correct allocation.
|
||||
|
||||
#. 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.
|
||||
|
||||
A dialog titled **Launch an Instance / Advanced Options** should pop up.
|
||||
|
||||
.. image:: ../images/providers/jetstream/add-deployment-script-dialog.png
|
||||
:alt: Dialog box allowing you to add a new script.
|
||||
|
||||
#. Click the **Create New Script** button. This will open up another dialog
|
||||
box!
|
||||
|
||||
.. image:: ../images/providers/jetstream/create-script-dialog.png
|
||||
:alt: Launch an Instance / Advanced Options dialog box
|
||||
|
||||
#. Under **Input Type**, select **Raw Text**. This should make a text box titled
|
||||
**Raw Text** visible on the right side of the dialog box.
|
||||
Copy the text below, and paste it into the **Raw Text** text box. Replace
|
||||
``<admin-user-name>`` with the name of the first **admin user** for this
|
||||
JupyterHub. This admin user can log in after the JupyterHub is set up, and
|
||||
can configure it to their needs. **Remember to add your username**!
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
#!/bin/bash
|
||||
curl -L https://tljh.jupyter.org/bootstrap.py \
|
||||
| sudo python3 - \
|
||||
--admin <admin-user-name>
|
||||
|
||||
.. note::
|
||||
|
||||
See :ref:`topic/installer-actions` if you want to understand exactly what the installer is doing.
|
||||
:ref:`topic/customizing-installer` documents other options that can be passed to the installer.
|
||||
|
||||
#. Under **Execution Strategy Type**, select **Run script on first boot**.
|
||||
|
||||
#. Under **Deployment Type**, select **Wait for script to complete**.
|
||||
|
||||
#. Click the **Save and Add Script** button on the bottom right. This should hide
|
||||
the dialog box.
|
||||
|
||||
#. Click the **Continue to Launch** button on the bottom right. This should put you
|
||||
back in the **Launch an Instance / Basic Options** dialog box again.
|
||||
|
||||
#. Click the **Launch Instance** button on the bottom right. This should turn it
|
||||
into a spinner, and your server is getting created!
|
||||
|
||||
.. image:: ../images/providers/jetstream/launching-spinner.png
|
||||
:alt: Launch button turns into a spinner
|
||||
|
||||
#. You'll now be shown a dashboard with all your servers and their states. The
|
||||
server you just launched will progress through various stages of set up,
|
||||
and you can see the progress here.
|
||||
|
||||
.. image:: ../images/providers/jetstream/deployment-in-progress.png
|
||||
:alt: Instances dashboard showing deployment in progress.
|
||||
|
||||
#. 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!
|
||||
|
||||
#. 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
|
||||
|
||||
#. 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.
|
||||
|
||||
#. Congratulations, you have a running working JupyterHub!
|
||||
|
||||
Step 2: Adding more users
|
||||
==========================
|
||||
|
||||
.. include:: add_users.txt
|
||||
|
||||
Step 3: Install conda / pip packages for all users
|
||||
==================================================
|
||||
|
||||
.. include:: add_packages.txt
|
||||
133
docs/install/ovh.md
Normal file
133
docs/install/ovh.md
Normal file
@@ -0,0 +1,133 @@
|
||||
(install-ovh)=
|
||||
|
||||
# Installing on OVH
|
||||
|
||||
## Goal
|
||||
|
||||
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
|
||||
[OVH](https://www.ovh.com).
|
||||
|
||||
## Pre-requisites
|
||||
|
||||
1. An OVH account.
|
||||
|
||||
## Step 1: Installing The Littlest JupyterHub
|
||||
|
||||
Let's create the server on which we can run JupyterHub.
|
||||
|
||||
1. Log in to the [OVH Control Panel](https://www.ovh.com/auth/).
|
||||
|
||||
2. Click the **Public Cloud** button in the navigation bar.
|
||||
|
||||
```{image} ../images/providers/ovh/public-cloud.png
|
||||
:alt: Public Cloud entry in the navigation bar
|
||||
```
|
||||
|
||||
3. If you don't have an OVH Stack, you can create one by clicking on the following button:
|
||||
|
||||
```{image} ../images/providers/ovh/create-ovh-stack.png
|
||||
:alt: Button to create an OVH stack
|
||||
```
|
||||
|
||||
4. Select a name for the project:
|
||||
|
||||
```{image} ../images/providers/ovh/project-name.png
|
||||
:alt: Select a name for the project
|
||||
```
|
||||
|
||||
5. If you don't have a payment method yet, select one and click on "Create my project":
|
||||
|
||||
```{image} ../images/providers/ovh/payment.png
|
||||
:alt: Select a payment method
|
||||
```
|
||||
|
||||
6. Using the **Public Cloud interface**, click on **Create an instance**:
|
||||
|
||||
```{image} ../images/providers/ovh/create-instance.png
|
||||
:alt: Create a new instance
|
||||
```
|
||||
|
||||
7. **Select a model** for the instance. A good start is the **S1-4** model under **Shared resources** which comes with 4GB RAM, 1 vCores and 20GB SSD.
|
||||
|
||||
8. **Select a region**.
|
||||
|
||||
9. Select **Ubuntu 22.04** as the image:
|
||||
|
||||
```{image} ../images/providers/ovh/distribution.png
|
||||
:alt: Select Ubuntu 22.04 as the image
|
||||
```
|
||||
|
||||
10. OVH requires setting an SSH key to be able to connect to the instance.
|
||||
You can create a new SSH by following
|
||||
[these instructions](https://help.github.com/en/enterprise/2.16/user/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
|
||||
Be sure to copy the content of the `~/.ssh/id_rsa.pub` file, which corresponds to the **public part** of the SSH key.
|
||||
|
||||
11. Select **Configure your instance**, and select a name for the instance.
|
||||
Under **Post-installation script**, copy the text below and paste it in the text box.
|
||||
Replace `<admin-user-name>` with the name of the first **admin user** for this
|
||||
JupyterHub. This admin user can log in after the JupyterHub is set up, and
|
||||
can configure it to their needs. **Remember to add your username**!
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
curl -L https://tljh.jupyter.org/bootstrap.py \
|
||||
| sudo python3 - \
|
||||
--admin <admin-user-name>
|
||||
```
|
||||
|
||||
:::{note}
|
||||
See {ref}`topic/installer-actions` if you want to understand exactly what the installer is doing.
|
||||
{ref}`topic/customizing-installer` documents other options that can be passed to the installer.
|
||||
:::
|
||||
|
||||
```{image} ../images/providers/ovh/configuration.png
|
||||
:alt: Add post-installation script
|
||||
```
|
||||
|
||||
12. Select a billing period: monthly or hourly.
|
||||
|
||||
13. Click the **Create an instance** button! You will be taken to a different screen,
|
||||
where you can see progress of your server being created.
|
||||
|
||||
```{image} ../images/providers/ovh/create-instance.png
|
||||
:alt: Select suitable hostname for your server
|
||||
```
|
||||
|
||||
14. In a few seconds your server will be created, and you can see the **public IP**
|
||||
used to access it.
|
||||
|
||||
```{image} ../images/providers/ovh/public-ip.png
|
||||
:alt: Server finished creating, public IP available
|
||||
```
|
||||
|
||||
15. The Littlest JupyterHub is now installing in the background on your new server.
|
||||
It takes around 5-10 minutes for this installation to complete.
|
||||
|
||||
16. Check if the installation is complete by copying the **public ip**
|
||||
of your server, and trying to access it with a browser. This will fail until
|
||||
the installation is complete, so be patient.
|
||||
|
||||
17. When the installation is complete, it should give you a JupyterHub login page.
|
||||
|
||||
```{image} ../images/first-login.png
|
||||
:alt: JupyterHub log-in page
|
||||
```
|
||||
|
||||
18. Login using the **admin user name** you used in step 6, 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.
|
||||
|
||||
19. Congratulations, you have a running working JupyterHub!
|
||||
|
||||
## Step 2: Adding more users
|
||||
|
||||
```{eval-rst}
|
||||
.. include:: add_users.txt
|
||||
```
|
||||
|
||||
## Step 3: Install conda / pip packages for all users
|
||||
|
||||
```{eval-rst}
|
||||
.. include:: add_packages.txt
|
||||
```
|
||||
@@ -1,127 +0,0 @@
|
||||
.. _install/ovh:
|
||||
|
||||
=================
|
||||
Installing on OVH
|
||||
=================
|
||||
|
||||
Goal
|
||||
====
|
||||
|
||||
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
|
||||
`OVH <https://www.ovh.com>`_.
|
||||
|
||||
Pre-requisites
|
||||
==============
|
||||
|
||||
#. An OVH account.
|
||||
|
||||
Step 1: Installing The Littlest JupyterHub
|
||||
==========================================
|
||||
|
||||
Let's create the server on which we can run JupyterHub.
|
||||
|
||||
#. Log in to the `OVH Control Panel <https://www.ovh.com/auth/>`_.
|
||||
|
||||
#. Click the **Public Cloud** button in the navigation bar.
|
||||
|
||||
.. image:: ../images/providers/ovh/public-cloud.png
|
||||
:alt: Public Cloud entry in the navigation bar
|
||||
|
||||
#. If you don't have an OVH Stack, you can create one by clicking on the following button:
|
||||
|
||||
.. image:: ../images/providers/ovh/create-ovh-stack.png
|
||||
:alt: Button to create an OVH stack
|
||||
|
||||
#. Select a name for the project:
|
||||
|
||||
.. image:: ../images/providers/ovh/project-name.png
|
||||
:alt: Select a name for the project
|
||||
|
||||
#. If you don't have a payment method yet, select one and click on "Create my project":
|
||||
|
||||
.. image:: ../images/providers/ovh/payment.png
|
||||
:alt: Select a payment method
|
||||
|
||||
#. Using the **Public Cloud interface**, click on **Create an instance**:
|
||||
|
||||
.. image:: ../images/providers/ovh/create-instance.png
|
||||
:alt: Create a new instance
|
||||
|
||||
#. **Select a model** for the instance. A good start is the **S1-4** model under **Shared resources** which comes with 4GB RAM, 1 vCores and 20GB SSD.
|
||||
|
||||
#. **Select a region**.
|
||||
|
||||
#. Select **Ubuntu 22.04** as the image:
|
||||
|
||||
.. image:: ../images/providers/ovh/distribution.png
|
||||
:alt: Select Ubuntu 22.04 as the image
|
||||
|
||||
#. OVH requires setting an SSH key to be able to connect to the instance.
|
||||
You can create a new SSH by following
|
||||
`these instructions <https://help.github.com/en/enterprise/2.16/user/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent>`_.
|
||||
Be sure to copy the content of the ``~/.ssh/id_rsa.pub`` file, which corresponds to the **public part** of the SSH key.
|
||||
|
||||
#. Select **Configure your instance**, and select a name for the instance.
|
||||
Under **Post-installation script**, copy the text below and paste it in the text box.
|
||||
Replace ``<admin-user-name>`` with the name of the first **admin user** for this
|
||||
JupyterHub. This admin user can log in after the JupyterHub is set up, and
|
||||
can configure it to their needs. **Remember to add your username**!
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
#!/bin/bash
|
||||
curl -L https://tljh.jupyter.org/bootstrap.py \
|
||||
| sudo python3 - \
|
||||
--admin <admin-user-name>
|
||||
|
||||
.. note::
|
||||
|
||||
See :ref:`topic/installer-actions` if you want to understand exactly what the installer is doing.
|
||||
:ref:`topic/customizing-installer` documents other options that can be passed to the installer.
|
||||
|
||||
|
||||
.. image:: ../images/providers/ovh/configuration.png
|
||||
:alt: Add post-installation script
|
||||
|
||||
#. Select a billing period: monthly or hourly.
|
||||
|
||||
#. Click the **Create an instance** button! You will be taken to a different screen,
|
||||
where you can see progress of your server being created.
|
||||
|
||||
.. image:: ../images/providers/ovh/create-instance.png
|
||||
:alt: Select suitable hostname for your server
|
||||
|
||||
#. In a few seconds your server will be created, and you can see the **public IP**
|
||||
used to access it.
|
||||
|
||||
.. image:: ../images/providers/ovh/public-ip.png
|
||||
:alt: Server finished creating, public IP available
|
||||
|
||||
#. The Littlest JupyterHub is now installing in the background on your new server.
|
||||
It takes around 5-10 minutes for this installation to complete.
|
||||
|
||||
#. Check if the installation is complete by copying the **public ip**
|
||||
of your server, and trying to access it with a browser. This will fail until
|
||||
the installation is complete, so be patient.
|
||||
|
||||
#. When the installation is complete, it should give you a JupyterHub login page.
|
||||
|
||||
.. image:: ../images/first-login.png
|
||||
:alt: JupyterHub log-in page
|
||||
|
||||
#. Login using the **admin user name** you used in step 6, 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.
|
||||
|
||||
#. Congratulations, you have a running working JupyterHub!
|
||||
|
||||
Step 2: Adding more users
|
||||
==========================
|
||||
|
||||
.. include:: add_users.txt
|
||||
|
||||
Step 3: Install conda / pip packages for all users
|
||||
==================================================
|
||||
|
||||
.. include:: add_packages.txt
|
||||
Reference in New Issue
Block a user