Tutorial: How to set-up your new nbdev development environment in Ubuntu
In this tutorial, you will install your new clean development environment for python, Jupyter notebook and nbdev.
You will use powerful features such as: linux chroot, python virtual environment, Jupyter notebook and nbdev.
Prerequisites
You need a computer running the latest version of Ubuntu. This tutorial is written for Ubuntu version 22, named Jammy. Although it is recommended to use the same version, most of the tutorial can be followed with other versions of Ubuntu.
Make sure to install: debootstrap, schroot.
You can install them with:
sudo apt install debootstrap
sudo apt install schrootYou need a local Linux user - in this tutorial, mine is called chris.
And you also need a github account, and an authentication token already configured.
Create a chroot environment
Initiate the chroot with debootstrap
You will first create a clean chroot environment. A chroot is an isolated linux environment where packages are installed independently of the main operating system packages. Whatever is installed in the chroot will not contaminate your main operating system.
If you want to know more about chroot, you can read the wikipedia article.
sudo debootstrap jammy nbdevMount bind OS folder
Bind mount dev, proc and sys in the chroot env:
sudo mount --rbind /dev ~/mychroots/nbdev/dev
sudo mount --rbind /proc ~/mychroots/nbdev/proc
sudo mount --rbind /sys ~/mychroots/nbdev/sysCopy apt source configuration
Copy the sources apt repo to the chroot env:
sudo cp /etc/apt/sources.list ~/mychroots/nbdev/etc/apt/sources.listYou will be able to install any package in the chroot environment from the repository list.
Edit schroot configuration
Edit schroot configuration as follows for the new chroot environment:
sudo vi /etc/schroot/schroot.conf[nbdev]
description=nbdev - Jammy
directory=/home/chris/mychroots/nbdev
users=chris
root-groups=rootConfigure the user in the chroot environment
Create the first user (I recommend to use the same user as the one doing the schroot in the mother environment) and add it to sudoers. For convenience, I configure it to run without password when doing sudo:
adduser chris
usermod -aG sudo chris
visudoAdd the following line:
chris ALL=(ALL) NOPASSWD:ALLNow you are done with the chroot environment !
You can simply enter the chroot environment with your user as follows:
schroot -c nbdev --directory /home/chrisTo exit the environment, type simply:
exitPackages Installation
Upgrade
Enter again the chroot environment.
You start by upgrading your local packages with the latest updates:
sudo apt update
sudo apt upgradePackages installation
Then, you install the new packages needed for your environment:
sudo apt install python3-pip python3-venv gitInstall github client
To install the Github client, you copy and paste the following command:
type -p curl >/dev/null || sudo apt install curl -y
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
&& sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg \
&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
&& sudo apt update \
&& sudo apt install gh -yConfigure git and github
Git configuration
For git, you configure your user name and email - so that your commit messages include the right author:
git config --global user.email YOUR_EMAIL
git config --global user.name YOUR_NAMEGithub configuration
For Github, you need to register your authentication token.
gh auth loginFollow the prompts, select Github.com and as method for authentication: with authentication token.
Note that your authentication token will expire after some time, and you will need to configure again your github access from time to time.
Install your Python virtual environment
Still inside the chroot environment, cd to your home directory, and build a python virtual environment. Then install jupyter, jupyter_contrib_nbextensions, jupyterthemes, twine and nbdev
cd
mkdir pyenv
cd pyenv
python3 -m venv nbenv
source nbenv/bin/activate
python3 -m pip install jupyter jupyter_contrib_nbextensions jupyterthemes nbdev twinetwine will be used to publish packages to PyPi.
Configure Jupyter notebook
You then enable 2 useful jupyter notebook extensions:
jupyter nbextension enable collapsible_headings/main
jupyter nbextension enable toc2/mainThese extensions bring: collapsible headings, and the display of Table of Content.
And you enable a Jupyter dark theme - I like cheterish:
jt -t chesterishIn this set-up, the top Navigate menu from the TOC2 extension seems to remain blank. But the left Table of Content works fine - which is still very useful.
Your first nbdev project
Initiate your github repository
You create a new github repository. Once this is done, copy its HTTPS clone url.
Clone your repository in your development environment:
git clone YOUR_REPOSITORY_HTTPS_URLConfigure the nbdev environment
Now you can set-up the initial nbdev environment with:
nbdev_new
nbdev_install_hooks
git add .
git commit -m 'Creation'
git pushOpen the Jupyter notebook
Within your project folder structure, you can start Jupyter and start working with the notebook in the nbs folder:
jupyter notebook nbs/PyPi Configuration
To be able to publish your packages to PyPi, register at pypi, and then create a file called ~/.pypirc with your login details. It should have these lines:
[pypi]
username = your_pypi_username
password = your_pypi_passwordCongratulations
Congratulations you have a working nbdev environment in a completely isolated environment with chroot and python virtual environment ! You can now enjoy the power of Jupyter notebooks and nbdev library.
Next Steps
You can now continue with the nbdev walkthough.
You can explore the nbdev features: github pages workflow integration, pypi integration, etc.
Enjoy coding with nbdev !
If you enjoyed this tutorial, please follow me here.