* Linux is allowed as an engineer. The following is a basic guide to go over
the basics of what is recommended for installation to get you up and running
as quickly as possible.
# Linux
Linux is allowed as an alternative to an Apple Mac running MacOS. Historically this was only allowed for the engineering team, but anyone in GitLab can use Linux. Just bear in mind it is assumed you are capable of self-support when running Linux - there is a #linux channel in Slack where one can exchange tips and tricks, but it is not intended as an official helpdesk resource.
The following is a guide to go over the basics of what is recommended for installation to get you up and running as quickly as possible.
* Not everything listed here may apply to your use case.
* This document will not cover the customization desired for your own personal
configuration and setup of your desktop/window manager/etc.
* This guide is intended to be very generic. Be aware package names listed
here may be named differently on your distro of choice.
* And as always, there are multiple ways to do many things, so if you have a
better preference or are more familiar with another method, feel free to do so
and contribute back to this document.
## Generic Tooling
* Some common tools are potentially best to download via their site, these
include:
* This document will not cover the customization desired for your own personal configuration and setup of your desktop/window manager/etc.
* This guide is intended to be very generic. Be aware package names listed here may be named differently on your distro of choice.
* And as always, there are multiple ways to do many things, so if you have a better preference or are more familiar with another method, feel free to do so and contribute back to this document.
## Basic Setup
Outside of the basics listed [here](https://about.gitlab.com/handbook/security/#laptop-or-desktop-system-configuration) for all laptop and desktop systems, there are a few additional steps required for Linux. Currently, the recommended laptop for Linux is Dell running Ubuntu, which is discussed in detail [here](https://about.gitlab.com/handbook/business-ops/it-ops-team/#laptop-configurations). These instructions assume that setup, so for alternate choices in hardware or Linux distribution it is recommended you use this as a general guideline but adapt as needed.
Dell maintains its own Ubuntu distribution. While not needed to use Linux on Dell, it does seem to offer direct support for various chipsets and hardware components. This means that for a stock Ubuntu (or other distribution) install, generic choices are often made by the installer, and if you wish to take advantage of drivers that better support the hardware, you may have to install and configure drivers for certain components. The Dell Ubuntu distribution removes that burden.
To summarize our install process to meet GitLab standards, we will go the following steps (remember these steps were current as of December 2019):
* Boot up the Dell and begin the installation of Ubuntu on the screen.
* When you reach the screen that gives you the option to create recovery media, insert a USB thumbdrive and do so.
* Continue with the installation until complete.
* immediately back up some key files created during the installation process. If you decide to switch to generic Ubuntu (for example to upgrade to a newer Ubuntu version), you will need these files.
* Reboot and using the recovery media, restore the system but select the option to encrypt the hard drive.
* Complete the installation as before,
### Initial Installation
***Note:** Before installation, make sure you have a few USB thumbdrives on hand. It is highly recommended you use modern thumbdrives that are compatible with UEFI booting (most modern ones are).
* Boot up the Dell Laptop. You will reach an Ubuntu System Configuration screen. Under "Welcome" select your language and press Continue.
* You will be presented with a "Terms of Service" to review. Click the checkbox at the bottom and click Continue.
* On the "Keyboard layout" screen, make your selection and click on Continue.
* On the "Wireless" screen, choose the network, enter its password and click on Continue.
* On the Where are you? screen you enter your location to determine your time zone. Click Continue.
* On the Who are you? screen you enter in your computer name, username, your password. Click Continue.
* You will be given an opportunity to make a backup copy of recovery media. It is highly recommended you do so, even if you intend to wipe and reload the entire operating system from scratch. In the event of complete failure, you can at least recover the system. For our purposes of encrypting the hard drive, it is a must. Do this on a USB drive and make sure you label it "Recovery". Follow the prompts and press Continue when complete.
* The system will reboot.
* When it boots up, log in. If asked if you wish to "Help improve Ubuntu", select the option of "No, don't send system info" in case crash information is sent that contains proprietary work information. If it tries to update the system with patches, fine - but you do not have to update yet if you don't want to. We are getting ready to rewipe anyway.
* Insert a blank USB drive, as we need to back up some data before we encrypt the main hard drive, just in case the encryption process fails.
* The USB drive will auto-mount, usually to a location like "/media/<username>" where <username> is the name you log in with.
* Hold down the Ctrl key and press t to open a terminal window. Type in the following:
`$ df`
* This is mainly to confirm the USB drive location, in my instance this was "/media/mloveless".
* Create a couple of directories to store backups of some critical information we might need:
`$ sudo mkdir /media/mloveless/bkup`
`$ sudo mkdir /media/mloveless/bkup/apt`
* We need to make a backup copy of all information regarding sources for updates to our system to our USB drive:
* Next we need to backup and copy signing keys used for verifying packages for future installation and update processes:
`$ sudo apt-key exportall > apt.keys`
`$ sudo cp apt.keys /media/mloveless/bkup`
* Unmount and remove the USB drive, and label it "Backup". We're now ready to encrypt the Dell hard drive.
* Insert the USB drive labeled "Recovery" and boot off of that USB drive. You may have to enter the BIOS and specifically choose to boot off of it. Instructions vary by Dell laptop, it usually involves pressing F2 or F12 during the boot process. Search on the Dell website for more information, but essentially you want to select an option that allows you to boot off of the USB drive.
* Once you boot up, you will be given some options for recovery. The language has changed for this, but the option you are looking for is a complete wipe and reload of the system. As you move forward, installation will continue, similar to the regular installation above. The main difference is you are looking for an option to encrypt the hard drive. Do so, and reinstall as normal. You will be repeating the steps from above.
* On restart, you will be prompted for your password for the encrypted drive, and you will log in as normal.
* If all goes correctly, you will end up at a normal Ubuntu desktop and can jump down to the Final Installation Steps below.
* If there is a problem where the recovery fails and you are unable to encrypt the drive (or you wish to upgrade the system to a more recent version of Ubuntu), you will need to proceed with the steps below.
## Alternate Installation
In some cases the "recovery" process when trying to encrypt the hard drive has failed for other team members, in other cases they decided they wanted to use a more recent version of the Ubuntu operating system than what the Dell Ubuntu version is. Either way, you can follow these steps. **These steps assume you have the "Backup" USB drive created during the Initital Installation instructions.**
You will need a copy of vanilla Ubuntu copied onto a UEFI bootable USB drive (labeled "Ubuntu", and this will be a fairly straight-forward Ubuntu install. The instructions assume Ubuntu 18.04 LTS, although you can do the same with a later version, including non-LTS versions.
* Insert the USB drive labeled "Ubuntu" into the USB port and boot. Press F12 when you see the Dell logo. You will reach a boot screen which lists the following (if you do not reach the boot screen, try restarting again and hitting F12 quickly and repeatedly after the logo appears). Select your UEFI-compatible USB drive. This is important: If you do not use a UEFI USB device for your initial load, it could trick your install process into a non-UEFI style installation, rendering your laptop unbootable.
* Once booted up, select Install Ubuntu.
* On the "Keyboard layout" screen, make your selection and click on Continue.
* On the "Wireless" screen, choose the network, enter its password and click on Continue.
* On the "Updates and other software" screen, make sure the "Normal installation" is checked. There is no need to select the "Install third party software for graphics and Wi-Fi hardware and additional media formats" unless you decide to take advantage of additional drivers for your hardware (which you can do later if you wish). Click on Continue.
* On the "Installation type" screen, click on "Erase disk and install Ubuntu", then click on "Encrypt the new Ubuntu installation for security". "Use LVM with the new Ubuntu installation" will be checked automatically, which you can leave it. Click on the Install Now button.
* On the "Choose a security key:" screen, enter a strong password and confirm it. DO NOT FORGET THIS PASSWORD. If you do you will have to reinstall as you will be unable to boot. Click on the Install Now button. After a brief wait a "Write the changes to disks?" window will appear to confirm you are installing the partitions, click on Continue.
* On the "Where are you?" screen select your timezone and click Continue.
* On the Who are you? screen, you will be prompted for your name, the name of your computer, a username, a password, and your password a second time to ensure it is correct. The button next to "Require my password to login" will be selected, make sure it remains selected. For convenience sake, you may wish to make your username match your GitLab username, but this is not required.
* The install process will take a while, anywhere from a few minutes to maybe an hour, depending on your connection speed. You will eventually reach an "Installation Complete" window. Click on Restart Now. After the restart, remove the USB drive.
* On restart, you will be prompted for your password for the encrypted drive, and you will log in as normal.
* After you have reached the Ubuntu Desktop, you will have a few more steps to perform.
* Edit /etc/apt/sources.list, remove the `#` symbol to uncomment the line that reads:
`# deb http://archive.canonical.com/ubuntu bionic partner`
* Insert the USB drive labeled "Backup" and perform the following action:
* Enter the following commands from a terminal window (the instructions below assume your username is mloveless, change to your username:
* The commands above will restore pointers to the Dell Ubuntu repository, perform updates, and remove unused packages introduced during this entire process (none occurred during testing, this is to be sure).
## General Applications
* Enable the firewall with the following command:
`$ sudo ufw enable`
* The prompt will respond with "Firewall is active and enabled on system startup".
* Some common applications to install include Google Chrome, Slack, and Zoom. Not all may be available via the normal Ubuntu repository, but you can download them via their respective sites with up-to-date installation instructions:
*[Google Chrome](https://www.google.com/chrome/)
*[Slack](https://slack.com/downloads/linux)
*[Zoom](https://zoom.us/download)
* Checkout our [Tools page](/handbook/tools-and-tips/) for more potential items.
## Dell and Nvidia
Some GitLab team members have experienced issues with the Nvidia drivers on Dell, including battery drain due to sleep issues when the laptop is closed, random lockups when waking the laptop up, and so on. If this happens, consider the following steps:
* Examine the /etc/default/grub file, the line containing `GRUB_CMDLINE_LINUX_DEFAULT`may look like this:
