🔧 Part 1 — Foundations

Key idea: Before you write a single line of backend code, your machine needs to be set up correctly. This section walks you through every step — from installing your IDE to running your first Python program. Future sections assume you have completed this setup.

The goal is not to memorise commands. The goal is to understand the system. Every tool exists to solve a problem — understand why it exists, not just how to use it.

Navigation

1. Full Development Environment Setup

This is the most important section in the handbook. Get everything here working before moving forward. When something goes wrong in a later section, the first question will always be: “Did you complete the setup checklist in Part 1?”

1.1 Choose Your IDE — VS Code or PyCharm?

An IDE (Integrated Development Environment) is the app you use to write, run, and debug code. Think of it as a text editor with superpowers — it highlights errors, lets you run code, shows you your files, and includes a terminal.

You have two great options for Python. Pick one and stick with it — do not install both and switch back and forth while you’re learning.

Side-by-Side Comparison

Recommendation: Start with VS Code — it is the most widely used editor on real engineering teams and works for every language you’ll ever encounter. PyCharm is an excellent alternative if you find VS Code confusing or want automatic Python setup.

1.2 Installing VS Code

Download: code.visualstudio.com

# Download and install the Microsoft GPG key and repository
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > packages.microsoft.gpg
sudo install -o root -g root -m 644 packages.microsoft.gpg /etc/apt/trusted.gpg.d/
sudo sh -c 'echo "deb [arch=amd64] https://packages.microsoft.com/repos/vscode stable main" > /etc/apt/sources.list.d/vscode.list'

# Install VS Code
sudo apt update
sudo apt install code

Install Essential VS Code Extensions

After installing VS Code, add these extensions (they make Python development much easier):

1. Press Ctrl+Shift+X (Windows/Linux) or Cmd+Shift+X (Mac) to open the Extensions panel.
2. Search for and install each of these:

1.3 Installing PyCharm (Alternative)

Download: jetbrains.com/pycharm/download

Download the Community edition — it is free and covers everything in this handbook.

# Install using the JetBrains Toolbox (recommended) or snap
sudo snap install pycharm-community --classic

PyCharm First-Run Setup

1. On first launch, PyCharm asks about plugins — skip and use defaults.
2. Choose New Project to create your first project (covered in section 1.7).
3. PyCharm automatically detects Python installed on your machine — you’ll see it pre-selected in the interpreter dropdown.

PyCharm tip: Unlike VS Code, PyCharm creates a virtual environment automatically when you create a new project. It also shows you which interpreter is active in the bottom-right status bar at all times.

1.4 Installing Python

Python is the programming language this handbook is built around.

Download: python.org/downloads

Always install Python 3.11 or newer. Python 2 is obsolete — do not install it.

brew install python@3.11

# Update package list
sudo apt update

# Install Python 3.11
sudo apt install python3.11 python3.11-venv python3-pip -y

# Verify
python3.11 --version
python3 --version
pip3 --version

1.5 Installing Git

Git is the tool that tracks every change you make to your code. It lets you go back in time, work in teams, and share code on GitHub.

Download: git-scm.com

1.5a Sign Up for a GitHub Account

GitHub is the platform where your code lives online. Think of it as a combination of a cloud backup for your code and a social network for developers. You will push your projects here so the team can see your work, review it, and collaborate with you.

Create Your Account

1. Go to github.com and click Sign up.
2. Enter your email address and click Continue.
3. Create a password (use something strong — at least 12 characters).
4. Choose a username. This will appear on all your commits and repos — keep it professional (e.g., jane-smith or jsmith-dev).
5. Complete the verification puzzle, then check your email for the verification code.
6. On the “Welcome to GitHub” screen, you can skip or answer the questions about your use — click Continue until you reach the dashboard.

You’re in! Your GitHub dashboard is at github.com/<your-username>.

Connect Git on Your Machine to GitHub

After installing Git (section 1.5), you need to authenticate so GitHub accepts your pushes. The most secure method is Personal Access Tokens (PAT).

Step 1 — Set your identity in Git

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Use the same email address you signed up to GitHub with — this links your commits to your account.

Step 2 — Generate a Personal Access Token (PAT)

A PAT is like a password for the terminal. GitHub no longer accepts your account password for Git operations.

1. Log in to github.com.
2. Click your profile photo (top-right) → Settings.
3. In the left sidebar, scroll down and click Developer settings.
4. Click Personal access tokens → Tokens (classic).
5. Click Generate new token → Generate new token (classic).
6. Give it a name (e.g., My Laptop Token).
7. Set Expiration to 90 days (or No expiration for personal learning machines).
8. Under Scopes, tick ✅ repo (this covers all repo operations you’ll need).
9. Click Generate token.
10. Copy the token immediately — GitHub will not show it again.

Save your token in a password manager or a secure note. You will need it the first time you push from this machine.

Step 3 — First Push (entering your token)

The first time you run git push, Git will prompt you for credentials:

# Enable credential caching so Git remembers for 1 hour
git config --global credential.helper cache

Tip: If you push and see remote: Support for password authentication was removed, it means you used your GitHub password instead of a PAT. Create a new PAT and use that.

git --version

xcode-select --install

brew install git

git --version

sudo apt update
sudo apt install git -y

git --version

First-Time Git Configuration

After installing Git on any OS, tell it your name and email. Git uses this to label your commits.

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

You only do this once per machine. It applies to all your Git projects.

1.6 Installing Docker Desktop

Docker lets you run software in isolated containers — same code, same environment, on any machine. You’ll use it later for running databases and packaging your API.

Download: docker.com/products/docker-desktop

docker --version
docker compose version

docker --version
docker compose version

# Install Docker Engine
sudo apt update
sudo apt install ca-certificates curl -y
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

# Run Docker without sudo (log out and back in after this)
sudo usermod -aG docker $USER

docker --version
docker compose version

1.7 Verify All Installations

Open a terminal (Git Bash on Windows, Terminal on Mac/Linux) and run each command. Every command should return a version number — not an error.

# Check Python
python --version         # Windows
python3 --version        # Mac / Linux

# Check pip (Python package manager)
pip --version            # Windows
pip3 --version           # Mac / Linux

# Check Git
git --version

# Check Docker
docker --version
docker compose version

Expected output (your exact versions may differ — that’s fine):

Python 3.11.9
pip 23.3.1 from ...
git version 2.44.0
Docker version 26.1.1
Docker Compose version v2.27.0

⚠️ If any command gives an error, stop here and fix it before continuing. Every other part of this handbook depends on these tools working.

1.8 Open a Project in Your IDE

Now that everything is installed, let’s open a project folder and get comfortable in the IDE.

VS Code

1. Create a new folder on your computer called hello-project (anywhere you like — your Desktop or Documents is fine).
2. Open VS Code.
3. Go to File → Open Folder and select hello-project.
4. VS Code opens the folder. The left sidebar shows your project files (currently empty).

Open the integrated terminal in VS Code:

• Press Ctrl+` (Windows/Linux) or Cmd+` (Mac) — the backtick key, top-left of most keyboards.
• Or go to Terminal → New Terminal from the menu bar.

A terminal panel opens at the bottom, already pointing to your project folder. You can run all commands from here — you do not need a separate terminal window.

Select the Python interpreter in VS Code:

1. Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac) to open the Command Palette.
2. Type Python: Select Interpreter and press Enter.
3. Choose the Python version you installed (e.g., Python 3.11.x).

Common issue: If no Python shows up, VS Code can’t find it. Make sure Python is on your PATH (check by running python --version in the terminal). If it works in the terminal but not in VS Code, restart VS Code.

PyCharm

1. Open PyCharm.
2. Click New Project.
3. Set the Location to a folder called hello-project.
4. Under Python Interpreter, select New environment using Virtualenv — PyCharm will create a venv automatically.
5. Click Create.

Open the terminal in PyCharm:

• Press Alt+F12 (Windows/Linux) or Option+F12 (Mac).
• Or go to View → Tool Windows → Terminal.

Check the active interpreter in PyCharm:

Look at the bottom-right corner of the PyCharm window. It shows the active Python interpreter (e.g., Python 3.11 (hello-project)). Click it to change.

1.9 Create and Activate a Virtual Environment

A virtual environment (venv) is an isolated box of Python packages for your project. It prevents version conflicts between projects and keeps your global Python installation clean.

Every project should have its own venv. This is non-negotiable on real teams.

Skip this section if you are using PyCharm — PyCharm already created the venv for you in step 1.8.

Step 1 — Create the virtual environment

Open the terminal in your IDE (or any terminal) and make sure you are in your project folder:

# Make sure you are in your project folder
cd hello-project     # skip if you are already there

Now create the venv:

This creates a folder called venv/ inside your project. You only do this once per project.

Step 2 — Activate the virtual environment

You must activate the venv every time you open a new terminal window. When active, your terminal prompt shows (venv) at the start.

After activation, your prompt looks like this:

(venv) user@machine:~/hello-project$     ← (venv) means it's active

Step 3 — Verify the venv is active

# Should show a path inside your project's venv folder
which python          # Mac / Linux
where python          # Windows

Expected output (Mac/Linux):

/home/yourname/hello-project/venv/bin/python

Expected output (Windows):

C:\Users\yourname\hello-project\venv\Scripts\python.exe

If it shows a system path instead (like /usr/bin/python), the venv is not activated.

Deactivate when done

deactivate

Common venv errors

1.10 Your First Python Hello World Project

Now you will write and run your first Python program. No extra packages needed — just Python and your venv.

Create the file

In your IDE, create a new file called hello.py in your project folder:

VS Code: Click the New File icon in the Explorer sidebar (or File → New File), name it hello.py.

PyCharm: Right-click the project folder in the Project panel → New → Python File → name it hello.

Write the code

# hello.py
# This is your first Python program.
# The print() function outputs text to the terminal.

print("Hello, world!")

That’s it. One line of real Python code.

Run from the terminal

Make sure your venv is active ((venv) in the prompt), then:

python hello.py         # Windows
python3 hello.py        # Mac / Linux

Expected output:

Hello, world!

If you see Hello, world! — your setup is working. 🎉

Run from VS Code

1. Open hello.py in VS Code.
2. Click the ▶ Run button in the top-right corner of the editor, OR press F5.
3. A terminal panel opens at the bottom and shows the output.

Common issue: VS Code runs with the wrong Python. Check the bottom-left status bar — it should show your venv Python path (e.g., Python 3.11.x ('venv': venv)). If it shows the global Python, click the interpreter name and select your venv.

Run from PyCharm

1. Open hello.py in PyCharm.
2. Right-click in the editor → Run ‘hello’, OR press Shift+F10.
3. The output panel at the bottom shows Hello, world!.

PyCharm note: The Run button only appears once you have a Python file open. If you see a grey triangle (not green), make sure the interpreter at the bottom-right is set to your venv.

Common run errors

1.11 Initialize Your Demo Project and Push to GitHub

Now that your IDE is set up, your venv is active, and you have a working hello.py, it’s time to put your project under version control and push it to GitHub. This is what you will do every time you start a new project or mini exercise.

Why push to GitHub? The team reviews your work from GitHub, not from your local machine. If it is not on GitHub, it does not exist from the team’s perspective. Make it a habit — push early and push often.

Step 1 — Create a .gitignore file

Before initialising Git, tell it which files to ignore. The venv/ folder is large and machine-specific — never commit it.

Create a file called .gitignore in your project root:

venv/
__pycache__/
*.pyc
*.pyo
.env
.DS_Store

Step 2 — Initialise Git in your project folder

In your terminal (with venv active, inside hello-project/):

git init

This creates a hidden .git/ folder — Git now tracks changes in this folder.

Step 3 — Stage and commit your files

# Stage all files (hello.py and .gitignore)
git add .

# Commit with a descriptive message
git commit -m "Initial commit: hello world project"

Run git status to confirm there is nothing left unstaged.

Step 4 — Create a repository on GitHub

1. Go to github.com and log in.
2. Click the + icon (top-right) → New repository.
3. Fill in:
   • Repository name: hello-project (match your local folder name)
   • Description: My first Python hello world project (optional but good practice)
   • Visibility: Public (so the team can see it) or Private
   • Do NOT tick “Add a README” or any other options — you already have files locally
4. Click Create repository.

GitHub shows you a page with setup instructions — you only need the “…or push an existing repository from the command line” section.

Step 5 — Connect your local project to GitHub

Copy and run the commands GitHub shows. They look like this (with your actual username and repo name):

git remote add origin https://github.com/your-username/hello-project.git
git branch -M main
git push -u origin main

When prompted:

• Username: your GitHub username
• Password: paste your Personal Access Token (from section 1.5a — not your GitHub password)

Step 6 — Verify on GitHub

Reload your GitHub repository page — you should see hello.py and .gitignore listed.

🎉 Your first project is live on GitHub!

Future pushes (after the first)

Once the remote is set up, pushing new changes is just:

git add .
git commit -m "Describe your change"
git push

You won’t need to enter credentials again (they were cached in step 3 of section 1.5a).

1.12 Setup Checklist ✅

Go through each item below. Do not move to Part 2 until every box is ticked.

• VS Code (or PyCharm) is installed and opens without errors
• VS Code Python extension is installed (or PyCharm is detecting Python automatically)
• python --version (or python3 --version) shows 3.11.x or newer in a terminal
• pip --version # Windows or pip3 --version # Mac / Linux shows a version number
• git --version shows 2.x.x or newer
• git config --global user.name and user.email are set
• GitHub account created and verified at github.com
• Personal Access Token (PAT) generated and saved securely
• docker --version shows a version number
• docker compose version shows a version number
• Docker Desktop is running (whale icon visible, or docker ps returns without error)
• A project folder (hello-project) is open in your IDE
• A virtual environment (venv/) has been created inside the project folder
• The venv is activated — (venv) is visible in your terminal prompt
• .gitignore contains venv/ and __pycache__/
• hello.py contains print("Hello, world!")
• Running python hello.py in the terminal prints Hello, world!
• Running hello.py from the IDE (Run button or F5) also prints Hello, world!
• git init run in hello-project/, files committed, pushed to GitHub
• GitHub repo is visible at github.com/<your-username>/hello-project

All boxes ticked? You have a fully working development environment. Everything in the rest of this handbook builds on this foundation.

Stuck on something? Check the error tables in each section above. If you’re still stuck, search the exact error message — you are very unlikely to be the first person to see it.

2. How to Approach Learning

The goal is not to memorise commands. The goal is to understand the system.

Every tool exists to solve a problem. Before using a tool, ask:

• What problem does this solve?
• How does it fit into the system?
• What would break without it?

3. Common Setup Failures

These are the most common problems beginners hit. Check here before asking for help.

4. Git Mental Model

Git tracks your code across four states:

Working Directory → Staging → Commit → Remote

Git Basics

Before you start, tell Git who you are (do this once):

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Initialise a new repository:

git init

Check what has changed (run this often):

git status

Stage all changed files:

git add .

Create a commit with a description:

git commit -m "Describe what you changed and why"

Push to remote (GitHub):

git push

Branching Workflow

Rules (non-negotiable):

• Never work directly on main
• Create a new branch for every task
• Push your branch to GitHub when done

# Start from the latest main branch
git checkout main
git pull

# Create and switch to a new branch for your task
git checkout -b feature/my-task

# Do your work, then stage and commit
git add .
git commit -m "Add my feature"

# Push the branch to GitHub so others can see it
git push -u origin feature/my-task

Common Git Problems

5. Internet Flow and HTTP Basics

How the Internet Works

Client → HTTP Request → Server → HTTP Response → Client

1. You type a URL or click a button in a browser
2. Your browser (the client) sends an HTTP request to a server
3. The server processes the request (runs code, queries the database)
4. The server sends back an HTTP response with data
5. Your browser renders the response

HTTP Methods

HTTP Status Codes

6. Terminal Basics

If you are new to the terminal, here are the most important commands:

Windows users: Use Git Bash (installed with Git) or Windows Terminal with PowerShell. Many Unix commands like ls and touch work in Git Bash.

Part 1 Summary

Navigation