the-littlest-jupyterhub/docs/contributing/dev-setup.rst

.. _contributing/dev-setup:

==================================
Setting up Development Environment
==================================

The easiest & safest way to develop & test TLJH is with `Docker <https://www.docker.com/>`_.

#. Install Docker Community Edition by following the instructions on
   `their website <https://www.docker.com/community-edition>`_.

#. Clone the git repo (or your fork of it).
#. Build a docker image that has a functional systemd in it.

   .. code-block:: bash

      docker build -t tljh-systemd . -f integration-tests/Dockerfile

#. Run a docker container with the image in the background, while bind mounting
   your TLJH repository under ``/srv/src``.

   .. code-block:: bash

      docker run \
        --privileged \
        --detach \
        --name=tljh-dev \
        --publish 12000:80 \
        --mount type=bind,source=$(pwd),target=/srv/src \
        tljh-systemd

#. Get a shell inside the running docker container.

   .. code-block:: bash

      docker exec -it tljh-dev /bin/bash

#. Run the bootstrapper from inside the container (see step above):
   The container image is already set up to default to a ``dev`` install, so
   it'll install from your local repo rather than from github.

   .. code-block:: console

      python3 /srv/src/bootstrap/bootstrap.py --admin admin

   The primary hub environment will also be in your PATH already for convenience.

#. You should be able to access the JupyterHub from your browser now at
   `http://localhost:12000 <http://localhost:12000>`_. Congratulations, you are
   set up to develop TLJH!

#. Make some changes to the repository. You can test easily depending on what
   you changed.

   * If you changed the ``bootstrap/bootstrap.py`` script or any of its dependencies,
     you can test it by running ``python3 /srv/src/bootstrap/bootstrap.py``.

   * If you changed the ``tljh/installer.py`` code (or any of its dependencies),
     you can test it by running ``python3 -m tljh.installer``.

   * If you changed ``tljh/jupyterhub_config.py``, ``tljh/configurer.py``,
     ``/opt/tljh/config/`` or any of their dependencies, you only need to
     restart jupyterhub for them to take effect. ``tljh-config reload hub``
     should do that.

:ref:`troubleshooting/logs` has information on looking at various logs in the container
to debug issues you might have.