Crafting a Thorough Guide for New Developers (Ubuntu on VirtualBox)

7 min readJun 30, 2021

Recently, I have been having so much fun editing our existing README file on our Github. The README file has long been left unattended and only used for a couple of random resources for developers like “Don’t overuse count() and exists().” and “Use foreign key values directly!”. I am 80% sure that nobody really facilitates the former README since such resources were already shared on Slack and we didn’t use them often, maybe except Google’s coding style guidelines (link).

Well, it was about time to fix this!

Useful Markdown Techniques

There are many posts out there that boast a wide array of Markdown syntaxes. However, too much info isn’t that efficient when it comes to IT and I have been meaning to make my own list of Markdown syntaxes and techniques that might be useful in the future (and for others also).

The thing is, I have used a mixture of HTML and Markdown syntaxes, for some HTML syntaxes can come very handy in certain situations. However, let me introduce some very basic Markdown syntaxes.

Basic Markdown Syntaxes

That’s pretty much it! Now it’s time to demonstrate some useful techniques involving the syntaxes I just introduced.

Since our README file is growing massic, in my opinion, the most important thing is to add some sort of navigation. Most of the books out there have this thing called Table of Content. There is a way for you to make the same thing for your README.

How to Make Table of Content

Let’s say you have three chapters in your README (Chapter 1, Chapter 2, Chapter 3).

# Chapter 1
## sub-chapter A 
some content
## sub-chapter B
some content# Chapter 2
## sub-chapter A
some content
## sub-chapter B
some content# Chapter 3
## sub-chapter A
some content
## sub-chapter B
some content

The Table of Content for this example would look like this:

# Table of Content
1. Chapter 1
2. Chapter 2
3. Chapter 3

If any of those chapters have like 100 or 1000 lines each, such a table would barely help the developers who only need certain parts of the whole README. There is a way to make those table elements lead them directly to the corresponding chapter. Utilize []().

# Table of Content
1. [Chapter 1](#chapter_1)
2. [Chapter 2](#chapter_2)
3. [Chapter 3](#chapter_3)# Chapter 1 <a name="chapter_1"></a>
## sub-chapter A 
some content
## sub-chapter B
some content# Chapter 2 <a name="chapter_2"></a>
## sub-chapter A
some content
## sub-chapter B
some content# Chapter 3 <a name="chapter_3"></a>
## sub-chapter A
some content
## sub-chapter B
some content

Pay attention to the partial HTML syntaxes, <a> tags. Inside each tag, I put the alias of each chapter headings, which I used as a link in the Table of Content with the ‘#’ prefix. This will create direct links where a user doesn’t have to do anything but click the chapter element to immediately land on the corresponding part.

How to Put External Links

Our new README is very thorough and has almost every step in order to install and set up local environments. However, nothing can be perfect that some others with different desktop environments shall be stuck with some esoteric technical issues unique to their machine. Therefore, I had to put a lot of links to those source websites for documentation where I utilized in order to solve issues.

One simple syntax is this

[Here is the link!](http://examplemodule.com/doc/setup.html/)

This will show just “Here is the link!” with a hyperlink that lands you to the corresponding link address.

syntax in use

In my very honest opinion, just throwing a bunch of useful original documentation on the README itself could be very useful. My README is too granularly detailed that I am afraid some new developers might not improve their way of solving technical issues themselves. However, I trust that our new Jr. SWEs have enough problem-solving skills already and my README will only significantly reduce the time and headaches from the initial setup.

Structure of the New README

Unfortunately, I cannot share small details of the README because there is much sensitive information that can be used maliciously. So I will only introduce the highest level of abstractions.

General Information

This is where I introduced the whole picture of our backend project. There can be some confusing parts — a lot of people prefer to call a whole thing an “application” or “app” while I wanted to distinguish between a whole “project” from several “applications” that amount to be this “project”.

In this chapter, I explained what each app does — e.g, “contacts app is responsible for managing accounts such as user accounts, clients, and suppliers”. As of June 2021, there are six apps in this project so it wasn’t hard to finish this chapter.

Technologies

This is where I listed languages and libraries and etc. It has two big parts: application level and infrastructure level. The former has a long list of languages that constitute this project such as Python, JavaScript, and SQL. It also has many libraries listed in requirements.txt. I didn’t go through every single package in requirements.txt (i.e, Django, DRF, boto3) because some of them are deprecated — which I might have to come back to and inform that they are indeed deprecated.

The infrastructure level lines up a bunch of Amazon Web Service platforms and tools. It is useful for the Jr. SWEs to take a look at the how and why of AWS platforms. Since our company is too small to have DevOps (yet!) our backend SWEs need to learn how to use them.

Project Setup

This is the most fun part! I had so much fun (I repeat it!). In my case, I used VirtualBox to install a whole new Linux machine because trying to set it up on my existing machine would be pointless since all the necessary packages are already installed.

VirtualBox download link
Ubuntu download link

The first problem I faced was the installation of Ubuntu.

when you click “Add”, it shows some error

When you press Add, VirtualBox will suddenly stop working and show you some fatal error. The solution is to manually locate the iso file with:

right-click on the new machine (located on the left side of the VirtualBox UI)
Settings
choose the Storage tab on the upper part
↓ refer to the image below ↓

After this, you will be able to rev up the new Ubuntu machine with no problem. The installation process will take some time (at least 10 minutes).

After the VM Setup

The first thing I did was to install very basic tools for software developers: a text editing tool and Git.

open Terminal
sudo apt-get install --upgrade
sudo apt-get install vim or sudo apt-get install emacs (whichever floats your boat… can also be nano… but take a look at the picture below and choose accordingly)

sudo apt install git

Then it was time to install pyenv and Python

pyenv doc link (I used this doc to install pyenv)
once pyenv is installed, I restarted the login session.
pyenv install 3.7.9
pyenv versions shows 3.7.9
pyenv global 3.7.9 to set the global Python version

And lastly, I created the Python environment

python3 -m venv myenv
source myenv/bin/activate

Then came all the nitty-gritty of installing Tradir backend project after gaining authentication for the repository, then setting up the pip packages & PSQL server, and etc… sensitive stuff cannot be posted here. However, I will show you one thing that bothered me every time I tried to set up a local Python environment in the next part: epilogue.

Epilogue

If your codebase has a lot of packages going on, there is a chance that your Python project has

A. mysqlclient
B. psycopg2
C. tangled dependencies

I am going to show you how to solve those problems.

Navigate into the directory where you have your requirements.txt. If you try to install every package, it will most likely cause some error with “exit code 1”. To fix this you need to:

sudo apt-get install python3-dev defautl-libmysqlclient-dev build-essential
pip install mysqlclient
sudo apt-get install libpq-dev python-dev

And finally:

pip install --no-deps -r requirements.txt

because --no-deps solves the tangled dependency issues.