============================
Login and SSH key generation
============================

.. note:: This process will only be done **once** for the first GitLab connection

First login to git2.boost-lab.net
=================================

You have received a confirmation email asking you to define a new password:

.. figure:: images/2LoginToTheServer/Picture1.png
   
   Confirmation email

Once the password has been defined, it will be possible to login normally to the server

SSH Key certificate creation
============================

.. contents::
	:local:
	:depth: 1
	:backlinks: top

The first thing to do once the login has been successful is to define an SSH Key [#f1]_ that will allow the local machine to push and pull from the repository.

.. _gitlab_navigation:

GitLab navigation
--------------------

To do so, navigate to the top-right corner of the GitLab interface and click on your user image (:numref:`fig3`). After having selected the **Profile** menu click on the **Edit profile** button represented as a pen in the top-right GitLab interface (:numref:`fig4`):

.. _fig3:
.. figure:: images/2LoginToTheServer/Picture2.png

   User menu

.. _fig4:
.. figure:: images/2LoginToTheServer/Picture3.png

   Edit profile button

Navigate to the **SSH Keys** tabs (:numref:`fig5`). The next step will consist on generating your own SSH Key.

.. _fig5:
.. figure:: images/2LoginToTheServer/Picture4.png

   SSH Keys tab

.. _ssh_key_verification:
   
SSH Key verification
-----------------------

Before generating an SSH Key, you should first see if you already have a local SSH Key. To do so, open a terminal command and type the following command:

**MacOS / Linux:**
::

    cat ~/.ssh/id_rsa.pub 

**Windows:**
::

    type %userprofile%\.ssh\id_rsa.pub 

If the terminal output indicates that the file does not exist, go to section C. If the terminal shows an output similar to the one in :numref:`fig6`, this means that you already have an SSH key: go to section D directly.

.. _fig6:
.. figure:: images/2LoginToTheServer/Picture5.png

   Terminal result when a SSH Key exists

.. _ssh_key_creation:   

SSH Key creation
-------------------

**MacOS** and **Linux** users can follow these steps to generate their SSH Key:

::

    ssh-keygen -t ed25519 -C "your_title"
    
.. note:: We are gradually moving from the rsa key to the ed25519 key. If you are using an ed25519 key, mentally replace rsa with ed25519 throughout this document.

The terminal will ask to which file the Key shall be exported, press Enter to use the default path. It will then ask you do define a passphrase for the SSH Key. The passphrase is a password that will be asked whenever the SSH key will be used. The output of the terminal should look like :numref:`fig7`:

.. _fig7:
.. figure:: images/2LoginToTheServer/Picture6.png

   SSH Key generation terminal output

If you are running Windows as your default OS, this `link`_ will explain the procedure to create a new SSH Key.

However, if you are working with EGit, the procedure to generate an SSH key is faster and easier:

Open **"Window" > "Preferences"** and ensure that your SSH2 home is configured correctly (usually this is ~/.ssh) and contains your SSH2 keys

.. figure:: images/2LoginToTheServer/Picture7.png

   SSH EGit menu

If you don't have SSH keys yet you may generate them on the second tab "Key Management" of this dialog. When you select “Generate RSA Key” you will get the information presented to you. Define a passphrase that will be associated to your SSH key. The :numref:`fig9` shows this window:

.. _fig9:
.. figure:: images/2LoginToTheServer/Picture8.png

   SSH Key generation

Copy the text that is highlighted in figure 9 and select Save **Private Key...**

Copying the SSH Key to GitLab
--------------------------------

To copy the SSH public key, use the following commands if the SSH key was not generated with EGit.

**MacOS:**

::

    pbcopy < ~/.ssh/id_rsa.pub

**Linux:**

::

    xclip -sel clip < ~/.ssh/id_rsa.pub

**Windows (if PuTTy used):**

::

    type %userprofile%\.ssh\id_rsa.pub | clip

Then simply paste it in the GitLab interface (the title will be completed automatically):

.. figure:: images/2LoginToTheServer/Picture9.png

   Pasting the public SSH Key

Clicking on **Add key** will upload your public key.

.. note:: You are now able to download and upload files to the server

.. rubric:: Footnotes

.. [#f1] Secure Shell (SSH) is a cryptographic network protocol for operating network services securely over an unsecured network: `wikipedia`_.

.. _wikipedia: https://en.wikipedia.org/wiki/Secure_Shell
.. _link: http://git2.boost-lab.net/help/ssh/README