Using IDEs
==========

This guide walks you through connecting to a Faculty server from your local IDE using
SSH. We cover two IDEs:
`PyCharm Professional Edition <https://www.jetbrains.com/pycharm/>`_ and
`Visual Studio Code <https://code.visualstudio.com/>`_. Connecting your IDE to a Faculty
server allows you to combine the benefits of your IDE's development features (e.g. code
completion, code navigation, and debugging) with the benefits of Faculty.

Set up
------

Authorised keys specify which users are allowed to log into a server using public key
authentication in SSH. The following steps guide you through generating an SSH key pair
and adding the public key to the authorised keys on Faculty. You only need to do this
once.

1. On your local machine, make sure you have the latest version of the Faculty command
   line client installed (see :ref:`installing-faculty`).

2. On your local machine, generate an SSH key pair (public key and private key) with
   ``ssh-keygen``.

3. On a server, add the public  key you created to ``~/.ssh/authorized_keys``. Each line
   of this file contains one key. For example:

   .. code-block:: none

      # ~/.ssh/authorized_keys
      ssh-rsa AAAAB3Nza...LiPk user@example.net

Connecting your IDE
-------------------

Follow the steps below to connect your IDE to a running Faculty server.

1. To connect to the server over SSH, you need to know the ``hostname``, ``username``
   and ``port``. You can fetch these details with the following command:

   .. code-block:: bash

      $ faculty server ssh-details <project> <server>

2. If everything is working correctly, you should now be able to SSH into the server
   with ``ssh <username>@<hostname> -p <port>``.

   .. note::

      This guide is focused on connecting your local IDE to Faculty.
      ``faculty shell <project> <server>`` is the preferred way to SSH into a server (
      see :ref:`faculty_shell` for more details).

3. Configure your IDE to connect to the Faculty server.

   The `Visual Studio Code Remote - SSH <https://code.visualstudio.com/docs/remote/ssh/>`_
   extension allows you to open a remote folder on any remote machine and run commands
   and other extensions directly on the remote machine.

   In PyCharm Professional Edition you can `configure a remote Python interpreter
   <https://www.jetbrains.com/help/pycharm/configuring-remote-interpreters-via-ssh.html>`_
   on a server and copy your sources to a Faculty server by creating a
   `deployment configuration
   <https://www.jetbrains.com/help/pycharm/creating-a-remote-server-configuration.html>`_.