setup Documentation

Setup instructions for Le Wagon's students on their first day of AI Software Development Bootcamp

19,599 stars Ruby Ruby 1 file · ~3,853 tokens #ruby#setup
RAW Doc

File: README.md

In Chinese?

如果你在参加中文课程，请打开中文设置指南

¿En Español?

Haga clic en este enlace para acceder a la versión en español de la configuración.

Em Português?

Clique neste link para acessar a versão em português da configuração.

En Français ?

Clique sur ce lien pour accéder à la version française du setup.

In English

Setup guides for Le Wagon 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

text
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:

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 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 F2 or F11 or Suppr. 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, 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. 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.

Uncompressed and Unencrypted error

When running wsl --set-default-version 2, you might get a:

text
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.

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 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.

text
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:

text
sudo hwclock -s

Type your WSL password and click enter.

GitHub CLI installation failure

If the GitHub CLI installation instructions fail, 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的设置指南。请选择你电脑的操作系统（OS)：

File: README.es.md

¿En Español?

Guías de configuración para el curso de AI Software Development de Le Wagon. Elige tu sistema operativo (OS):

File: README.fr.md

En Français

Guides de configuration pour la formation AI Software Development du Wagon. 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. Escolha seu sistema operacional (SO):

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#ruby Browse ruby catalog → #setup Browse setup catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →