diff --git a/docs/_static/images/ssh_from_vscode.png b/docs/_static/images/ssh_from_vscode.png new file mode 100644 index 0000000000..64146ff2fa Binary files /dev/null and b/docs/_static/images/ssh_from_vscode.png differ diff --git a/docs/_static/images/ssh_session_in_vscode.png b/docs/_static/images/ssh_session_in_vscode.png new file mode 100644 index 0000000000..e06e558c84 Binary files /dev/null and b/docs/_static/images/ssh_session_in_vscode.png differ diff --git a/docs/_static/images/ui_ssh_activate.png b/docs/_static/images/ui_ssh_activate.png new file mode 100644 index 0000000000..f2d4e2a0ad Binary files /dev/null and b/docs/_static/images/ui_ssh_activate.png differ diff --git a/docs/_static/images/ui_ssh_dropdown.png b/docs/_static/images/ui_ssh_dropdown.png new file mode 100644 index 0000000000..1cccd29e2d Binary files /dev/null and b/docs/_static/images/ui_ssh_dropdown.png differ diff --git a/docs/_static/images/ui_ssh_modal.png b/docs/_static/images/ui_ssh_modal.png new file mode 100644 index 0000000000..44606b9f1b Binary files /dev/null and b/docs/_static/images/ui_ssh_modal.png differ diff --git a/docs/_static/images/ui_ssh_update_template.png b/docs/_static/images/ui_ssh_update_template.png new file mode 100644 index 0000000000..2848e07056 Binary files /dev/null and b/docs/_static/images/ui_ssh_update_template.png differ diff --git a/docs/how-to-guides/renkulab/index.rst b/docs/how-to-guides/renkulab/index.rst index 5d3718747e..407f2def81 100644 --- a/docs/how-to-guides/renkulab/index.rst +++ b/docs/how-to-guides/renkulab/index.rst @@ -7,5 +7,6 @@ RenkuLab :maxdepth: 1 session-stopping-and-saving + ssh-into-sessions s3 collaboration diff --git a/docs/how-to-guides/renkulab/ssh-into-sessions.rst b/docs/how-to-guides/renkulab/ssh-into-sessions.rst new file mode 100644 index 0000000000..8ae0a108f5 --- /dev/null +++ b/docs/how-to-guides/renkulab/ssh-into-sessions.rst @@ -0,0 +1,260 @@ +.. _ssh_into_sessions: + +Connect to RenkuLab Sessions with SSH & Local IDE +================================================= + +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 easily connect to the +remote session environment directly using SSH 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 "Connect with SSH" option is available, +and the dialog says your project supports SSH. + +.. image:: ../../_static/images/ui_ssh_dropdown.png + :width: 85% + :align: center + :alt: Dropdown menu with SSH entry. + +If you see "Your project supports SSH" as in the screenshot below, your project +is SSH-enabled, and you can skip down to the next section! + +.. image:: ../../_static/images/ui_ssh_modal.png + :width: 85% + :align: center + :alt: SSH modal for an up-to-date project. + +.. 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the SSH dialog says that SSH is not enabled for this project, this likely +means that your project is using an old project template. + +.. image:: ../../_static/images/ui_ssh_activate.png + :width: 85% + :align: center + :alt: SSH modal for a project with no support. + +To update your project template, click on "Overview Status" to open the project +status page. Find the "Template Version" section, and click "Update". + +.. image:: ../../_static/images/ui_ssh_update_template.png + :width: 85% + :align: center + :alt: Project status page showing a new template available. + + +Alternatively, you can manually enable SSH for your project by :ref:`upgrading your +base image ` 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 ``>= 7.6`` is installed +* the Renku CLI ``>= 2.3.0`` is installed +* your Renku project is cloned + +This section will guide you through setting up these prerequisites. + +#. To check whether ``ssh`` is installed, run ``ssh -V``. If you get a response + like `OpenSSH_8.6p1, LibreSSL 3.3.6`, and the version number for OpenSSH is + ``>= 7.6``, then you are good to go! + +#. Install the Renku CLI version ``>= 2.3.0``. + + 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 ``2.3.0``, run ``pip install --upgrade renku>=2.3.0``. + +#. Clone your Renku Project. You can find the :meth:`renku clone ` + command under your project's Settings tab. Or, form it yourself in the style + of the following URL: + + .. code-block:: console + + $ renku login renkulab.io # this step is required if your project is private or internal + $ 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 + `` and providing a path to a password protected private 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 `: + + .. 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 `, + using the ``--ssh`` flag and ``-p renkulab`` to specify running the session + remotely on RenkuLab: + + .. code-block:: console + :emphasize-lines: 5-7 + + $ renku session start --ssh -p renkulab + 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 user-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 ` to open an SSH +connection directly. This will open a terminal in your RenkuLab Project session +environment. + +.. code-block:: console + + $ renku session open --ssh + 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 + `. 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 `. + +.. note:: + + **Can I use the normal** ``ssh`` **command?** Yes! If you prefer, you can + use the ``ssh`` command directly rather than the ``renku session open`` + command. You can again use the session ``id``, for example ``ssh + user-myproject-02a9e407``. + + +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 `_ + 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. + ``user-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 VSCode documentation `_. + +FAQ +--- + +My shell 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. diff --git a/docs/reference/templates.rst b/docs/reference/templates.rst index 81db500c52..3941f49d44 100644 --- a/docs/reference/templates.rst +++ b/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 `_ in both file content and filenames. You can therefore ask users for specific values