docs: add SSH into sessions docs

docs/how-to-guides/renkulab/index.rst

@@ -7,5 +7,6 @@ RenkuLab
     :maxdepth: 1
 
     session-stopping-and-saving
+    ssh-into-sessions
     s3
     collaboration

docs/how-to-guides/renkulab/ssh-into-sessions.rst

@@ -0,0 +1,256 @@
+.. _ssh_into_sessions:
+
+SSH into RenkuLab Sessions
+==========================
+
+Would you prefer to work in a RenkuLab session from your local environment? Do
+you prefer to edit code in your own IDE, rather than in a browser?
+
+You can use the SSH feature of RenkuLab sessions to connect directly to the
+remote session environment and work on it from your local machine. You can even
+open the session with your favorite tools, such as VSCode.
+
+Check if SSH is enabled in your project
+---------------------------------------
+
+You can check if your project supports SSH by clicking the drop down next to the
+Session Start button and seeing if the SSH option is visible and enabled. If you
+see the SSH-enabled icon in the screenshot below, your project is SSH-enabled,
+and you can skip down to the next section!
+
+.. warning::
+    <screenshot of the Session Start drop down menu with SSH enabled>
+
+.. note::
+    **Don't see an SSH option in the Session Start menu?** If you are working on
+    a custom instance of RenkuLab (not renkulab.io), this may be because SSH
+    needs to be enabled by your administrator. Contact your RenkuLab
+    administrator to see if SSH can be enabled.
+
+Enabling SSH for your project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. warning::
+    <screenshot of the Session Start drop down menu with SSH NOT enabled>
+
+If the SSH dialogue says that SSH is not enabled for this project, this likely
+means that your project is using an old project template. To update your project
+template, go to the project "Overview" tab and open the "Status" section. Find
+the "Template Version" section, and click "Update".
+
+.. warning::
+
+    <screenshot of the Status page with a Template Version box that's asking to be updated>
+
+Alternatively, you can manually enable SSH for your project by :ref:`upgrading your
+base image <renku_base_image_upgrade>` to at least version 0.14.0. Then, run
+``renku config set ssh_supported true`` to let Renku know that your project supports
+SSH connections.
+
+.. note::
+
+    **Are you using a custom project template?** If you've updated your project
+    template but your project still doesn't support SSH, ask the template
+    maintainer to enable SSH in the template and perform the update again.
+
+.. note::
+
+    **Note for template maintainers:** See the documentation on the Template
+    :ref:`manifest-yaml` for details on how to enable SSH support in your
+    template, specifically the details on the ``ssh_supported`` flag.
+
+
+Set up your local system for SSH access
+---------------------------------------
+
+Connecting to RenkuLab sessions via SSH requires 3 prerequisites to be setup on
+your local machine (where you want to SSH from):
+
+* OpenSSH is installed
+* the Renku CLI is installed, with version >= <X>
+* your Renku project is cloned
+
+This section will guide you through setting up these prerequisites.
+
+    .. warning::
+        <Enter version number above 1x>
+
+#.  To use the SSH feature, you need to have OpenSSH installed on your system.
+
+    .. warning::
+        <How to check is OpenSSH is installed?!>
+
+#.  Install the Renku CLI version >= <X>.
+
+    If you do not already have the CLI installed, see :ref:`cli_installation`. 
+
+    To check the version of your Renku CLI, run ``renku --version``. If the
+    version is less than <X>, run ``pip install --upgrade renku>=<X>``.
+
+    .. warning::
+        <Enter version number above 3x>
+
+#.  Clone your Renku Project. You can find the :meth:`renku clone <renku.ui.cli.clone>`
+    command under your project's Settings tab. Or, form it yourself in the style
+    of the following URL: 
+
+    .. code-block:: console
+
+        $ renku clone https://renkulab.io/gitlab/user/my-project.git
+
+.. note::
+
+    **Do you want to use password-protected ssh keys for your RenkuLab
+    sessions?** By default, the first time you launch an SSH session, Renku will
+    create a password-less key pair for use in authenticating with RenkuLab
+    sessions. If you would prefer to have a password, you can do so by running
+    (before launching a session) ``renku session ssh-setup -k
+    <path_to_keypair>`` and providing a path to a password protected key of your
+    choice. If you've already launched a session and would like to switch to a
+    different key pair, also include the ``--force`` option.
+
+Launch an SSH-enabled Session
+-----------------------------
+
+#.  Navigate so your current working directory is the project you want to start
+    a session in:
+
+    .. code-block:: console
+
+        $ cd my-project
+
+
+#.  Log in to RenkuLab with :meth:`renku login <renku.ui.cli.login>`: 
+
+    .. code-block:: console
+
+        $ renku login renkulab.io
+
+
+#.  Pull any changes. This makes sure that the session you start is for the
+    latest version of your project.
+
+    .. code-block:: console
+
+        $ git pull
+
+
+#.  Start a session with :meth:`renku session start <renku.ui.cli.session>`,
+    using the ``--ssh`` flag and ``-p renkulab`` to specify running the session
+    remotely on RenkuLab:
+
+    .. code-block:: console
+
+        $ renku session start -p renkulab --ssh Your system is not set up for
+        SSH connections to Renku. Would you like to set it up? [y/N]: y [...]
+        Session user-myproject-02a9e407 successfully started, use 'renku session
+        open --ssh user-myproject-02a9e407' or 'ssh
+        renkulab.io-myproject-02a9e407' to connect to it
+
+    .. note::
+
+        **Curious what's happening under the hood?** This command starts a new
+        session on RenkuLab. But first, it adds your local SSH keys to the
+        ``allowed_keys`` in the project and pushes those changes to RenkuLab. If
+        this is your first time using the SSH feature on RenkuLab, Renku creates
+        an SSH key pair for you. Once the session is started, Renku creates an
+        SSH connection entry in your local SSH config for that session id. This
+        SSH config entry can be used with your SSH client or tools like VSCode.
+
+
+Open an SSH Session via a Shell
+-------------------------------
+
+You can use :meth:`renku session open <renku.ui.cli.session>` to open an SSH
+connection directly. This will open a terminal in your RenkuLab Project session
+environment.
+
+.. code-block:: console
+
+    $ renku session open --ssh <session-id>
+    venv ▶ ~ ▶ $
+
+(If prompted to accept host keys, confirm with ``yes``).
+
+To exit the SSH shell, simply type ``exit``.
+
+.. note::
+
+    **How do I find my Session ID?** The ``id`` of the session is
+    printed when the session is started by :meth:`renku session start
+    <renku.ui.cli.session>` .
+
+    In the example above, the session id is ``user-myproject-02a9e407``, so the
+    command to open the SSH session is: ``renku session open --ssh
+    user-myproject-02a9e407``.
+
+    If you need to find your session id again, use
+    :meth:`renku session ls <renku.ui.cli.session>`.
+
+.. note::
+
+    **Can I use normal the** ``ssh`` **command?** Yes! If you prefer, you can
+    use the ``ssh`` command directly rather than the Renku CLI. The ``ssh``
+    command is printed upon starting an ssh session.
+
+        .. code-block:: console
+
+            $ renku session start -p renkulab --ssh
+            [...]
+            SSH connection successfully configured, use 'ssh renkulab.io-myproject-02a9e407' to connect.
+
+
+Open an SSH Session in VSCode
+------------------------------
+
+After starting an SSH session, follow these steps to open your session in
+VSCode:
+
+#.  Install the `Remote - SSH Extension <https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh>`_
+    in VSCode if you don't have it already.
+
+#.  In VSCode, open the "Remote Explorer" in the left bar and make sure "SSH
+    Targets" is selected. Find the SSH connection for the session, e.g.
+    ``renkulab.io-myproject-02a9e407``, and click the "Connect to Host" button.
+
+    .. image:: ../../_static/images/ssh_from_vscode.png
+        :width: 85%
+        :align: center
+        :alt: Opening a RenkuLab SSH Session in VSCode.
+
+#.  Open the "Explorer" in the left bar, and select "Open Folder". Enter
+    ``/home/jovyan/work``.
+
+You can now browse and edit your Renku Project files in VSCode, and run commands
+in the RenkuLab session via the VSCode terminal!
+
+.. image:: ../../_static/images/ssh_session_in_vscode.png
+    :width: 85%
+    :align: center
+    :alt: A RenkuLab SSH Session open in VSCode.
+
+
+For more details on the VSCode SSH extension see
+`the official documentation <https://code.visualstudio.com/docs/remote/ssh>`_.
+
+FAQ
+---
+
+My environment in an SSH session isn't the same as when I'm in a session on RenkuLab - What's going on?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you've made changes to your session environment via your Dockerfile, you may
+need to change how these changes take effect in order to be consistent between
+SSH and Jupyter terminals.
+
+Since SSH opens a new terminal when connecting, any customization done in the
+Dockerfile, such as adding to the ``$PATH`` environment variable, won't be picked
+up, as those changes only apply to the Jupyter terminal.
+
+To make the Jupyter and SSH terminal consistent, your Dockerfile should apply
+such changes to ``/home/jovyan/.bash_profile`` (or similar, depending on your
+image), where they get picked up when any new shell is opened.
+
+For example, if you would like to modify your ``$PATH``, instead of encoding in
+your Dockerfile ``RUN export $PATH=...``, use ``RUN echo 'export $PATH=...' >>
+~/.bash_profile`` instead.

docs/reference/templates.rst

@@ -334,6 +334,11 @@ repository. Each of them requires an entry with the following parameters:
 * ``name``: a short user-friendly name.
 * ``description``: a brief description of your template. This will be
   presented to the user when choosing between templates.
+* ``ssh_supported``: ``true`` or ``false``, indicating whether the template supports
+  SSH connections. To support SSH, the Dockerfile has to use one of the Renku base
+  images with version 0.14.0 or higher, or have a functioning SSH server running
+  inside the image listening on port 2022 and reading client keys from
+  ``$HOME/.ssh/authorized_keys``.
 * ``variables``: we support the
   `Jinja template engine <https://palletsprojects.com/p/jinja/>`_ in both
   file content and filenames. You can therefore ask users for specific values