## File: README.md

## In Chinese?

如果你在参加中文课程，请打开[中文设置指南](README.cn.md)

## ¿En Español?

Haga clic en [este enlace](README.es.md) para acceder a la versión en español de la configuración.

## Em Português?

Clique [neste link](README.pt.md) para acessar a versão em português da configuração.

## En Français ?

Clique sur [ce lien](README.fr.md) pour accéder à la version française du setup.

## In English

Setup guides for [Le Wagon](https://www.lewagon.com) AI Software Development course. Please choose your operating system (OS):



|  |  |  |
| --- | --- | --- |

---

## File: docs/macos_cheatsheet.md

Hello and welcome to this macOS cheatsheet.

The goal is to gather here all known issues and tips with the macOS setup.

# Issues

## Brew HEAD not linked to origin/master ?

If you get one of the following error while installing a binary

```bash
~ % brew install git
fatal: Could not resolve HEAD to a revision
No available formula or cask for the name "git"
```
This should help
```bash
git -C $(brew --repository homebrew/core) checkout master
```

## Error: Permission denied @ apply2files - /usr/local/lib/docker/cli-plugins

If you get a Homebrew error `Permission denied @ apply2files` with "docker" in the path that follows,

run
```
mkdir -p /Applications/Docker.app/Contents/Resources/cli-plugins
```
and then rerun `brew cleanup`.

See  for more info

---

## File: docs/pull_request_template.md

# How to contribute to the Setup repository

## Before opening a Pull Request

We know that encountering issues can be frustrating but before opening a PR to modify the setup that can theoretically be used by a few thousand people:

- Are you the only one experiencing this issue?
- Is it a temporary issue?
- Is it a quick fix and shouldn't be used in the long term?

We currently have a cheatsheet for each OS for tips and / issues that don't belong to the setup itself, so feel free to have a look there first. Maybe your contributing should live there:

- [macOS](https://github.com/lewagon/setup/blob/master/docs/macos_cheatsheet.md)
- [Windows](https://github.com/lewagon/setup/blob/master/docs/windows_cheatsheet.md)
- [Ubuntu](https://github.com/lewagon/setup/blob/master/docs/ubuntu_cheatsheet.md)

## Opening a Pull Request

We have a specific architecture for the setup so we can reuse part of the content for different platforms (macOS/Windows/Ubuntu).

There are 2 main folders **_partials** and **images**:
- *images* is where the images live
- **partials_ is where the content live. For example, setting up Github is not platform dependent. So we have a `_partials/github.md` file with the guidelines to setup Github. This allows us to reuse the content described there.**

**Naming convention**

Partials prefixed with the OS are specific to only one OS. Partials shared among two or more OSes have no prefix.

**Build**

[`build.rb`](https://github.com/lewagon/setup/blob/master/build.rb) is the code that generates the 3 files `macos.md`, `ubuntu.md` & `windows.md` and the corresponding chinese translated versions. For each platform, there is a list of partials to use.

To update any content, it is required to update the matching partial. The CI will then run `ruby build.rb` and commit the changes to the main md files on the branch.

If you modify directly the destination file (`macos.md`, `ubuntu.md` & `windows.md`) without modifying the partials, your changes will be overridden the next time someone (or the CI) runs `ruby build.rb`

This is the flow you need to follow:
- Identify the partial(s) in which you want to make modifications
- Make changes
- Open PR
- Check files after the CI build
- Ask for a review

Many thanks for contributing 🙌 🚀

---

## File: docs/ubuntu_cheatsheet.md

Hello and welcome to this Ubuntu cheatsheet.

The goal is to gather here all known issues and tips with the Ubuntu setup.

# Issues

## No Devices choice at reboot

Make sure Windows FastBoot is disabled and restart in **Advanced Mode**.

## No OS choice at reboot

Disable Windows FastBoot **&** Bios FastBoot (see below).

**OR**

Access the Bios and change Boot option **ONE by ONE** <=> choose an option, save, reboot, if your problem persists, come back to default Boot option, choose another option and move on.

## Disable Bios FastBoot

1. Restart your machine in default mode and keep pushing on <kbd>F2</kbd> or <kbd>F11</kbd> or <kbd>Suppr.</kbd> to access the Bios.
2. Look for the boot options to disable the Bios FastBoot

## GitHub CLI installation failure

If [the GitHub CLI installation instructions fail](https://github.com/lewagon/setup/blob/master/ubuntu.md#github-cli-installation), chances are that you have the package `gitsome` installed. This package provides a `gh` binary which can conflict with `gh` GitHub CLI binary. In this case, run `sudo apt remove gitsome` before running the GitHub CLI installation instructions again.

---

## File: docs/windows_cheatsheet.md

Hello and welcome to this Windows cheatsheet.

The goal is to gather here all known issues and tips with the Windows setup.

# Issues

## Network Unreachable

When trying to connect to remote hosts, eg. when trying to do `sudo apt update`, you might see an error message saying that the network is unreachable. Here are two possible solutions: if the first one doesn't help, try the second one.

### A note about diagnosing this problem

- This is a common networking issue, and we must be sure that the problem lies with WSL only, and not with the Windows host. Please first ensure that there are no known networking issues on Windows. If you can successfully browse a few sites on Windows, but you can't connect to the internet in WSL, it would appear that this is an WSL problem. Please continue to the next section.

### Refresh and reset network

- `Start` > `cmd` > 'Open as administrator'
- Run the following commands:
    ```bash
    wsl --shutdown
    netsh winsock reset
    netsh int ip reset all
    netsh winhttp reset proxy
    ipconfig /flushdns
    ```
- Reset the network (`Start` > Search for `Network Reset`; click `Reset`)
- Restart Windows
- *[Source](https://github.com/microsoft/WSL/issues/4926#issuecomment-679410653)*. There might be other relevant solutions there.
- If this still does not solve your problem, try the next section.

### Add a custom DNS server address to WSL

- Open a WSL terminal and type the following:
  ```bash
  sudo mv /etc/resolv.conf /etc/resolv.conf.old
  sudo touch /etc/resolv.conf
  sudo echo "[network]\ngenerateResolvConf = false\n" >> /etc/wsl.conf
  ```
- You should now have internet access within the WSL terminal.
- Ensure that the fix works even when WSL is restarted. Open PowerShell and run the following command:
  ```bash
  wsl.exe --shutdown
  ```
- Open a new WSL terminal. You should be able to access the internet.
- *[Source](https://stackoverflow.com/a/60302925)*.

## Uncompressed and Unencrypted error

When running `wsl --set-default-version 2`, you might get a:
```
Error: 0xc03a001a The requested operation could not be completed due to a virtual disk system limitation. Virtual hard disk files must be uncompressed and unencrypted and must not be sparse.
```


To fix this issue, open the `File Explorer` and go to:
`C:\Users\<YOUR_USERNAME>\AppData\Local\Packages\CanonicalGroupLimited<SOMETHING>`

It should look something like this:


Right click on `LocalState`, then `Properties`, then `Advanced`.

Ensure `Compress contents to save disk space` and `Encrypt contents to secure data` are both deselected.

Click `OK`, then `Apply`, then `Apply changes to this folder only`.

[Credits](https://simplernerd.com/wsl2-uncompressed/).

## Input/Output error

This happens when the hidden `wslhost.exe` is not working. We just need to restart it!

Close all WSL2 tabs.

Open a PowerShell tab and run the following command:

```bash
wsl.exe --shutdown
```

Check that your Ubuntu is properly stopped with the command

```bash
wsl -l -v
```

Open a new WSL2 Tab, problem should be fixed.

## ERR_CONNECTION_REFUSED / Unable to reach localhost

If you get this error trying to connect to your `rails server`, `serve` or `jupyter notebook`, a simple restart of WSL might do the trick.

- Open a new PowerShell tab
- Run `wsl --shutdown` to shutdown WSL.
- Open a new PowerShell tab or run `wsl` to restart WSL.
- Retry to connect to `localhost:xxxx`. You can as well try `127.0.0.1:xxxx` (the local IP of the machine) instead.

If the issue is still present, you need to allow the connection in Windows Defender Public rules.
Close all WSL terminal. Open a PowerShell terminal and type the following command to stop all WSL processes:

```bash
wsl --shutdown Ubuntu
```

Hit **Start** and type `Windows Defender Firewall` and open it.

Click on **Advanced Settings**

Right click on **Inboud Rules** and select **New Rule...**. Under **Rule Type** leave `Program` selected and hit **Next**.

For the program, Select `The program path:` and paste this path: `%SystemRoot%\System32\wsl.exe`. Click on **Next**.

For the Action section, make sure `Allow the connection` is selected and hit **Next**.

For the Profile section, make sure the 3 options are selected and click on **Next**.

Finally you will be asked to chose a name for this new rule, go with `WSL - Inbound`.

Repeat the whole process by creating a **Outbound Rule** with the same settings, except for the name: `WSL - Outbound`.

## Insecure World Writable

The warning `Insecure world writable dir /mnt/c in PATH, mode 040777` is caused by the two differents way of Windows & Linux to deal with file permissions.
To silence those warnings:

```bash
sudo touch /etc/wsl.conf
echo '[automount]' | sudo tee -a /etc/wsl.conf > /dev/null
echo 'options="metadata,umask=0033"' | sudo tee -a /etc/wsl.conf > /dev/null
```

Restart all terminals.

## Update version 2004 not offered

Microsoft is slowly releasing the latest major version of Windows (version 2004). Here is the guideline if your Windows is not offering you the update.
Go to [Windows 10](https://www.microsoft.com/en-us/software-download/windows10) and under `Windows 10 May 2020 Update` click on **Update now**. This will download a tool on your machine. Open it.

A compatibility check will start:



Next, you will be offered a choice, choose **Upgrade this PC now** and click on **Next**:



Let the tool do the work:



Microsoft is encountering some errors with the version 2004, Chances are that the update assistant will tell you that you're machine is not compatible yet!
Do not close the assistant.
Open a file explorer at this **path** `C:\$WINDOWS.~BT\Sources\Panther`
Locate the file `compatscancache.dat` and **delete it**
Go back to the update assistant and click **Refresh**.

The installation should carry on.

## Sudo apt update connection timed out

This happens if you're using AVG antivirus.
Disable AVG VPN if you're using it.

Open AVG Internet **Security -> Menu - Settings - Full Protection - Enhanced firewall**. Check `Enable Internet connection sharing mode`
On the same page, click on **System Rules** and enabled the first 2 options `Windows file & printer sharing` `Remote desktop connections`
Scroll down to click on save.

## Slow network

If you experience slow network on your fresh WSL2:

- Open Ubuntu (or your other distro)

- Open Network Connections in your settings ("View network connections" in your windows search)

- You should see

```bash
  vEthernet (WSL)
  Enabled
  Hyper-V Virtual Ethernet Adapter
```

- Right-click and open Properties

- In the Properties pane, click Configure...

- In the Configure pane, go to the "Advanced" Tab

- Click on "Large Send Offload Version 2" and update the value to "Disabled"

If you see two "Large Send Offload Version" options, disable both.

## Cloudinary: Stale request

If you see issues connecting to your Cloudinary API from your local WSL and you saw this error.

```
Stale request - reported time is 2016-12-15 04:14:53 +0000 which is more than 1 hour ago
```

The error is caused by a different system time between the WSL OS and the windows host machine. To fix it, please run this command in your windows terminal:

```
sudo hwclock -s
```

Type your WSL password and click enter.

## GitHub CLI installation failure

If [the GitHub CLI installation instructions fail](https://github.com/lewagon/setup/blob/master/ubuntu.md#github-cli-installation), chances are that you have the package `gitsome` installed. This package provides a `gh` binary which can conflict with `gh` GitHub CLI binary. In this case, run `sudo apt remove gitsome` before running the GitHub CLI installation instructions again.

# Tips

## Check Windows Subsystem for Linux

Open a PowerShell terminal.

Type the following command:

```bash
wsl -l -v
```

It will tell you the name of your WSL, it's state and version.

## Switch from version 1 to version 2

To switch a WSL from version 1 to 2, open a PowerShell terminal.

Type the following command:
⚠️ The conversion's time depends on the size of your Ubuntu filesystem, it can be long and WSL will be unsuable in the meantime. ⚠️

```bash
wsl --set-version Ubuntu 2
```

You can revert to version 1:

```bash
wsl --set-version Ubuntu 1
```

## Access root session

To access the `root` session, open a PowerShell terminal.

Type the following command:

```bash
wsl -d Ubuntu -u root
```

You can change the password of that `root` session by using the command:

```bash
passwd
```

You will prompted to enter a new password.

Now, from your normal session, you can switch from your session to the `root` on with:

```bash
su -
```

You will be asked for the password.

You can exit the `root` session with `Ctrl + D`.

## Testing on Rails

You need to have the latest version of Chrome installed on your machine to run tests on Rails, since we will use _Headless Chrome_ for System Testing. It's a browser without a user interface, well-suited for this kind of automated tests. Before running your system tests you need to make sure you have a **recent** version of Chrome on your system (not Chromium).

If you are getting a `Webdrivers::BrowserNotFound: Failed to find Chrome binary` error when running tests, it means that you are missing Chrome on your system or need to install the latest version:

```bash
# Ubuntu
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo apt install ./google-chrome-stable_current_amd64.deb
rm -rf google-chrome-stable_current_amd64.deb
```

Once installed, you can run your tests with:

```bash
rails test:system
```

---

## File: README.cn.md

## 新同学

### 你在中国吗？

开始设置之前，:point_down: 你可能会需要用到 VPN，所以保证你有 VPN，或者让老师为你提供一个。

### 全球

[Le Wagon](https://www.lewagon.com)的设置指南。请选择你电脑的操作系统（OS)：



|  |  |  |
| --- | --- | --- |

---

## File: README.es.md

## ¿En Español?

Guías de configuración para el curso de AI Software Development de [Le Wagon](https://www.lewagon.com). Elige tu sistema operativo (OS):



|  |  |  |
| --- | --- | --- |

---

## File: README.fr.md

## En Français

Guides de configuration pour la formation AI Software Development du [Wagon](https://www.lewagon.com). Choisis ton système d’exploitation (OS):



|  |  |  |
| --- | --- | --- |

---

## File: README.pt.md

## Em Português?

Guias de configuração para o curso de AI Software Development [Le Wagon](https://www.lewagon.com). Escolha seu sistema operacional (SO):



|  |  |  |
| --- | --- | --- |