.. _contributing/packages:

=======================
Environments & Packages
=======================

TLJH installs packages from different sources during installation.
This document describes the various sources and how to upgrade
versions of packages installed.

Python Environments
===================

TLJH sets up two python environments during installation.

1. **Hub Environment**. JupyterHub, authenticators, spawners, TLJH plugins
   and the TLJH configuration management code is installed into this
   environment. A `venv <https://docs.python.org/3/library/venv.html>`_ is used,
   primarily since conda does not support ARM CPUs and we'd like to support the
   RaspberryPI someday. Admins generally do not install custom packages
   in this environment.

2. **User Environment**. Jupyter Notebook, JupyterLab, nteract, kernels,
   and packages the users wanna use (such as numpy, scipy, etc) are installed
   here. A `conda <https://conda.io>`_ environment is used here, since
   a lot of scientific packages are available from Conda. ``pip`` is still
   used to install Jupyter specific packages, primarily because most notebook
   extensions are still available only on `PyPI <https://pypi.org>`_.
   Admins can install packages here for use by all users.

Python package versions
=======================

In ``installer.py``, most Python packages have a version specified. This
can be upgraded freely whenever needed. Some of them have version checks
in ``integration-tests/test_extensions.py``, so those might need
updating too.

Apt packages
============

Base operating system packages, including Python itself, are installed
via ``apt`` from the base Ubuntu repositories. The one exception to this
is nodejs, which is installed from the `nodesource <https://github.com/nodesource/distributions>`_
apt repository. The Ubuntu provided version of nodejs is usually too old.

We generally do not pin versions of packages provided by apt, instead
just using the latest versions provided by Ubuntu.