the-littlest-jupyterhub/docs/install/custom-server.md

(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!

   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.

   :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

.. 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.