Skip to content

Latest commit

 

History

History
434 lines (306 loc) · 16.8 KB

INSTALL.md

File metadata and controls

434 lines (306 loc) · 16.8 KB
TODO

Ideas for this tuto

  • Complet Install-Visual-Studio-Code
  • Add advantage/disadvantage jupiter/vs code
  • Add the setup : WSL, ect. so it can be used for this project
  • Test

Environnement Setup

This guide will walk you through setting up a Jupyter Notebook on a machine using Mambaforge and WSL. And also install Visual Studio Code.

Prerequisites for Windows Users

1. Install WSL (Windows Subsystem for Linux)

  • Install Windows Terminal:

    • Download from the Windows Store (already installed on Windows 11).

  • Set up WSL:

    • Run Windows Terminal as administrator and execute: 
      wsl --install
    • Restart your computer, set up your Ubuntu user (username in small letters and password).

  • Update Linux Distribution:

    sudo apt-get update
sudo apt-get install wget ca-certificates

2. Configure Ubuntu Terminal

  • Set Ubuntu as Default Shell (optional):
    • In Terminal settings, under Startup, set Ubuntu as the default profile to always start with the correct terminal.

Installing Python with Mambaforge

1. Verify Existing Python Installation

  • Check if Python is already installed: 
    which python
    • If Python is present, you might want to uninstall it before proceeding.

2. Download and Install Mambaforge

  • Download Mambaforge:
    • Go to the Mambaforge GitHub page, find the appropriate Linux distribution that corresponds to the type of CPU (architecture) you are using, and copy the download link in the table.

[!IMPORTANT] Do not select an installer under Miniforge-pypy3 but Miniforge3.

  • Check the directory

    pwd

    Should return /home/<username>

    • Create a downloads folder
    mkdir downloads

  • Install Mambaforge:

    wget <Miniforge3_download_link>
bash <name_sh_file>.sh
    • Agree to the terms, press Enter for default options, and type yes when prompted to initialize conda.
    • Restart terminal for Ubuntu, you should see (base) at the beginning of prompt.

Note

Everytime you open a new Ubuntu terminal, you should see (base) environment. That means your configuration setup works well for this course and labs.

3. Verify Installation

  • Ensure Mambaforge is correctly installed: 
    which python
    • It should point to the Mambaforge directory : home/<username>/miniforge3/bin/python

Install important basic packages

1. Install JupyterLab and Essential Libraries

  • Install necessary packages:

    mamba install ipython jupyterlab ipywidgets
    • Accept prompts with Y.

2. Update Mambaforge

  • Keep Mambaforge up to date: 
    mamba update mamba

3. Register Python Environment in Jupyter

  • Set up the environment in Jupyter: 
    python3 -m ipykernel install --user --name=python3

4. Start JupyterLab

  • Launch JupyterLab: 
    jupyter lab --no-browser
    • Use the provided link to access JupyterLab from your browser.
  • Close JupyterLab:
    • Close navigator and clic on ctrl+c on Terminal, the accept prompts with Y

Install Visual Studio Code

VS Code is a source-code editor, it include usefull features like debugging support, code completion, code refactoring, syntax highlighting and embedded git control.

Use this installation help to guide you through the VSCode installation and configuration with WSL, stop before the section Install Git (optional).

Go to Developing in WSL for more information about the installation and operation.

Jupyter lab or VS code

For working on a Notebook, the two methods works and have advantages, few difference between the two methods :

VS code Jupyter
+ - + -
Can be set as we want Must be configured correctly Avoid setting conflict (folder where data are, etc) Underdeveloped modules (black formatter, git, github copilot, etc.)
Autocomplete IDE easy to install No autocomplete
Powerful modules

Git Setup

Be sure git is installed correctly on your computer by following this quick tutorial.

In Ubuntu/WSL Terminal, follow the next steps :

1. Configure Git

  • Set up your Git identity: 
    git config --global user.name "Your Name"
git config --global user.email "your.name@example.ch"
  • Confirm that the Git username is set correctly: 
    $ git config --global user.name
> Your Name
$ git config --global user.email
> your.name@example.ch

2. Set Up SSH for GitHub

  • Generate SSH Key:

    ssh-keygen -t ed25519 -C "your_email@example.ch"

    When you're prompted to "Enter a file in which to save the key", you can press Enter to accept the default file location, same for passphrase.

    eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

  • Add public SSH Key to GitHub:

    • Copy the generate text in Terminal by the following command : 
      cat ~/.ssh/id_ed25519.pub
    • Paste it into your GitHub account under Settings > SSH and GPG keys.

3. Clone Repository

  • Clone the project repository:

    Create a folder (like git in exemple) and clone the repository inside

    mkdir git 
cd git
git clone git@github.com:heig-vd-ie/rht.git

    Type yesto accept the warning.

4. Install Dependencies

  • Install packages from environment.yml into the (base) environnement: 
    cd rht
mamba env update -n base --file environment.yml

Commiting your work with Git

Commiting your work with Git

To add all the changes you've made:

git add .

To commit them:

git commit -m "MY MESSAGE HERE"

[!NOTE] -m is the message flag here. The message is really important in order for tracking your work via git.

You can also put those steps together like this:

git commit -a -m "MY MESSAGE HERE"

To push your committed changes from your local repository to your remote repository:

git push origin master

It is possible to get some type in your username/password for github. Unless you have configured SSH keys correctly..

More information about these steps:

[!IMPORTANT] You are done with the setup. If you did not get any trouble, you can continue with the tutorials for this course github.com's notebook viewer.

If you get many problems with your git branch or repo, please get in touch with Luca or Antoine.

Troubleshooting in the setup guide

This section is designed to help you solve problems before contacting support directly. Try one of the following steps, depending on which part of the guide is giving you trouble.

Installation automation (to optimize later on)

Install an isolated Python environment with setup-conda.sh (not necessary to follow)

We are going to run the following script from the terminal setup-conda.sh. Don't worry, we will guide you through the all process.

Go to your download folder by typing the following command in your terminal:

cd downloads
wget https://github.com/fastai/fastsetup/blob/master/setup-conda.sh

Then, you can type the following command into the terminal:

chmod u+x setup-conda.sh

In a nutshell, those commands help to change the permissions to add executable permission to the current user (yourself). Then type:

 ./setup-conda.sh

The installation is starting...

  • Restart terminal for Ubuntu.
  • You should see (base) at the beginning of prompt.

[!NOTE] Everytime you open a new Ubuntu terminal, you should see (base) environment. That means your configuration setup works well for this course and labs.

At this point, we have to check if your configuration works fine:

  • Run which python, you should see that the python you are running is in the mambaforge directory: home/<username>/miniforge3/bin/python on Linux/WSL and /Users/<username>/miniforge3/bin/python.
  • This means everything was just setup correctly.
Only if you encounter difficulties with WSL

Troubleshooting with WSL

There is no need to enable 'Windows Subsystem for Linux' in the Turn Windows features on or off settings unless you get in trouble with your installation setup. In such case, it is recommended to follow this tutorial or get back to assistance.

Only if you encounter difficulties with Mambaforge

Troublehsooting with Mambaforge

  • rm -rf mambaforge
  • Remove conda initializing commands from \\wsl.localhost\Ubuntu\home\<username>: .bashrc file (with a text editor). Delete everything at the end of the script between these commands:
# >>> conda initialize >>>
__conda_setup=
...
# <<< conda initialize <<<

[!NOTE] Uncollapse these section depending where you need more help to solve troubleshootings.

Only if you encounter difficulties with GitHub

Troubleshooting with GitHub

We regularly update the notebooks to fix issues and add support for new librarires. So make sure you update this project regularly.

For this, open a terminal, and run the following:

cd $HOME # or whatever development directory you chose earlier
cd rht # go to this project's directory
git pull

If you get an error, it's probably because you modified a notebook. In this case, before running git pull you will first need to commit your changes. I recommend doing this in your own branch, or else you may get conflicts:

git checkout -b my_branch # you can use another branch name if you want
git add -u
git commit -m "Describe your changes here"
git checkout main
git pull

Next, let's update the libraries. First, let's update mamba itself:

mamba update -c defaults -n base mamba
mamba activate base
jupyter lab --no-browser

Further references for the setup (not necessary to follow)

References (not necessary to follow – backup)

[!NOTE] Notice that it is however using conda install, which we will replace with mamba install.

For the complete setup from scratch

[!WARNING] More information about it can be found here and here. Mambaforge (Discouraged as of September 2023), that means "the packages and configuration of Mambaforge and Miniforge3 are now identical. The only difference between the two is the name of the installer and, subsequently, the default installation directory."

  1. Beginner's Guide to Mambaforge Installation
  2. Mambaforge setup page
  3. Fastsetup script
  4. Jeremy Howard's Live Coding Sessions
  5. Mamba Installation
  6. Mamba Installation with Docker
  7. Miniforge3 23.3.1-0

For VS Code and WSL details

  1. Windows Subsystem for Linux Documentation
  2. Open a WSL project in Visual Studio Code
  3. Open a remote folder or workspace
  4. Install Ubuntu on WSL2 and get started with graphical applications
  5. Install Ubuntu on WSL2 on Windows 10
  6. How to get access to your Linux (WSL) Files in Windows 10 or 11
  7. What're the differences between these 2 ways of launching WSL?
  8. Get started with Docker remote containers on WSL 2
  9. Advanced: Opening a WSL 2 folder in a container
  10. Get started tutorial for Python in VS Code
  11. Add User to WSL Linux Distro in Windows 10
  12. Switch user in WSL Linux Distro in Windows 10
  13. How to set default user, switch user, and remove a user for WSL

For Git and SSH

  1. Quickstart with GitHub
  2. What is a Git SSH Key?
  3. Checking for existing SSH keys
  4. Generating a new SSH key and adding it to the ssh-agent
  5. Generating a new SSH key for a hardware security key
  6. Adding a new SSH key to your GitHub account
  7. Multiple SSH Keys settings for different github account
  8. Working with SSH key passphrases
  9. About commit signature verification
  10. Do I need authentication as well as signing keys on GitHub?

JupyterLab Desktop and Python environment

  1. Connect to an existing JupyterLab server (with the link you just copied from your terminal session)
  2. The python requirements file and how to create it
  3. Conda install requirements
  4. Introducing the new JupyterLab Desktop!