Full-Stack Starter: Setup & Environment Guide

Welcome to the Full Stack Web Development Course! This starter repository contains the essential setup instructions, starter files, and tools you need to configure your computer, connect to GitHub, and run your first Flask & PostgreSQL backend.

---

Table of Contents

1. Required Tools & Download Links
2. Step-by-Step Machine Installation (Windows & macOS)
3. Git & GitHub Setup (Local-First Workflow)
4. Step-by-Step Personal Access Token (PAT) Guide
5. Python & Flask Backend Setup (venv)
6. Common Errors & Student Troubleshooting Cheat Sheet

---

1. Required Tools & Download Links

Before starting class, complete the required action for each tool below:

Tool	Purpose	Action / What to Do	Official Download Link
VS Code	Code Editor	Download & install (ensure "Add to PATH" is checked)	Download VS Code
Git	Version Control System	Download & run the installer with default settings	Download Git
PostgreSQL	Relational Database Engine	Download & install (⚠️ remember your postgres password)	Download PostgreSQL
pgAdmin 4	PostgreSQL GUI Client	Download & install to visually view tables and queries	Download pgAdmin
Python (3.9+)	Backend Runtime	Download & install (ensure "Add Python to PATH" is checked)	Download Python
GitHub	Code Hosting Platform	Create a free account and verify your email address	Sign Up for GitHub
Render	Cloud Backend & Database Host	Create a free account (choose "Sign in with GitHub")	Sign Up for Render
Vercel	Cloud Frontend Host	Create a free account (choose "Continue with GitHub")	Sign Up for Vercel

---

2. Step-by-Step Machine Installation

1. Visual Studio Code

• macOS: Download the .zip file ➔ Drag Visual Studio Code.app into /Applications.
  • Important: Open VS Code, press Cmd + Shift + P, type Shell Command: Install 'code' command in PATH, and hit Enter.
• Windows: Run the .exe installer.
  • Important: During installation, ensure you check the box:
    • [x] Add to PATH (requires shell restart)
    • [x] Add "Open with Code" action to Windows Explorer context menu

2. Git Installation

• macOS: Open Terminal and run:

  git --version

  If not installed, macOS will prompt you to install Xcode Command Line Tools. Click Install.
• Windows: Run the Git installer. Choose default options, ensuring:
  • Default editor: Visual Studio Code.
  • Adjusting your PATH: "Git from the command line and also from 3rd-party software".

3. PostgreSQL & pgAdmin 4

1. Run the PostgreSQL installer (default port is 5432).
2. ⚠️ Write down your postgres password during installation (you will need this to connect your backend).
3. Open pgAdmin 4 ➔ Connect with your password ➔ Right-click Databases ➔ Create Database ➔ Name it notes_db.

---

3. Git & GitHub Setup (Local-First Workflow)

💡 Why Local-First? We build our project files locally on our computer first, track changes using local Git, and then connect our project to an empty GitHub repository.

Step 1: Set Your Git Identity

Run these commands once in your terminal (macOS Terminal / Windows Git Bash or PowerShell):

git config --global user.name "Your GitHub Username"
git config --global user.email "your-registered-github-email@example.com"
git config --global init.defaultBranch main

# Verify your settings
git config --list

Step 2: Initialize Git in Your Project Folder

Navigate to your project directory and run:

# 1. Initialize local git repository
git init

# 2. Check untracked files
git status

# 3. Stage all files
git add .

# 4. Create your first commit
git commit -m "Initial commit: project setup"

# 5. Ensure branch is main
git branch -M main

Step 3: Create an Empty Repository on GitHub

1. Log into GitHub.
2. Click the + icon in the top right ➔ select New repository.
3. Repository name: notes-app (or your project name).
4. ⚠️ DO NOT check any of these boxes:
   • [ ] Add a README file
   • [ ] Add .gitignore
   • [ ] Choose a license (Your repository MUST be completely empty with 0 commits so there are no merge conflicts).
5. Click Create repository.

---

4. Step-by-Step Personal Access Token (PAT) Guide

⚠️ Why do I need a Token instead of my Password? GitHub no longer allows pushing code via terminal using your account password. You must generate a Personal Access Token (Classic) which acts as your secure CLI password.

Click-by-Click Generation Steps:

1. Click your Profile Picture (top-right of GitHub) ➔ Settings.
2. In the left sidebar, scroll to the bottom ➔ click Developer settings.
3. Click Personal access tokens ➔ select Tokens (classic).
4. Click Generate new token ➔ select Generate new token (classic).
5. Set token details:
   • Note: My-Local-VSCode-Token
   • Expiration: 30 days (or 90 days).
   • Select scopes: Check the [x] repo box (gives full permission to push to your repositories).
6. Click the green Generate token button at the bottom.
7. COPY YOUR TOKEN NOW:
   • Copy the token starting with ghp_....
   • Paste it in a safe notepad temporarily. GitHub will never display this token again once you leave the page!

Pushing to GitHub with Your PAT:

Method A: Direct Remote URL (Recommended — No Password Prompts)

# Replace with your actual token, username, and repo name
git remote add origin https://<YOUR_PAT_TOKEN>@github.com/<YOUR_GITHUB_USERNAME>/<APP_NAME>.git

# Example:
# git remote add origin https://ghp_abcdef1234567890@github.com/john_doe/notes-app.git

# Push your code
git push -u origin main

Method B: Standard Push Prompt

git remote add origin https://github.com/<YOUR_GITHUB_USERNAME>/<APP_NAME>.git
git push -u origin main

When prompted in terminal:

• Username: Enter your GitHub username.
• Password: Paste your Personal Access Token (ghp_...). (Note: Characters will not show while pasting; simply paste and hit Enter).

---

5. Python & Flask Backend Setup (venv)

Step 1: Create & Navigate to Backend Folder

mkdir backend && cd backend

Step 2: Create a Python Virtual Environment

python -m venv venv

Step 3: Activate the Virtual Environment

• On macOS / Linux:

  source venv/bin/activate

• On Windows (PowerShell):

  .\venv\Scripts\Activate.ps1

• On Windows (Command Prompt):

  .\venv\Scripts\activate.bat

(When activated, your terminal prompt will show (venv) at the beginning).

Step 4: Install Project Dependencies

Make sure you have requirements.txt in your backend folder:

pip install -r requirements.txt

Step 5: Configure Environment Variables (.env)

Create a file named .env in your backend/ directory:

DATABASE_URL=postgresql://postgres:your_password@localhost:5432/notes_db
ALLOWED_HOSTS=*

(Replace your_password with the password you set during PostgreSQL installation).

Step 6: Start the Flask Backend Server

python app.py

Open your browser and visit: http://127.0.0.1:5000/api/hello to verify your server is running!

---

6. Common Errors & Troubleshooting Cheat Sheet

1. Windows PowerShell Script Execution Disabled

• Error: .\venv\Scripts\Activate.ps1 cannot be loaded because running scripts is disabled on this system.
• Fix: Open Windows PowerShell as Administrator and run:

  Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

2. Git Authentication / PAT Issues

• Error: remote origin already exists
  • Fix:

    git remote remove origin
    git remote add origin https://<YOUR_PAT_TOKEN>@github.com/<YOUR_USERNAME>/notes-app.git
    git push -u origin main

• Error (macOS Keychain): macOS remembers an old expired password.
  • Fix: Open Spotlight (Cmd + Space) ➔ search Keychain Access ➔ search for github.com ➔ delete the saved entry ➔ re-run git push.
• Error (Windows Credential Manager): Windows uses wrong saved credentials.
  • Fix: Search Windows for Credential Manager ➔ Windows Credentials ➔ under Generic Credentials, find git:https://github.com ➔ click Edit and paste your new PAT.

3. Port 5000 Already in Use

• Error: OSError: [Errno 48] Address already in use: 5000
• Fix (macOS):

  lsof -ti:5000 | xargs kill -9

• Fix (Windows):

  netstat -ano | findstr :5000
  taskkill /PID <PID_NUMBER> /F

4. PostgreSQL Connection Failed

• Error: psycopg.OperationalError: connection to server at "localhost", port 5432 failed
• Fix: Make sure PostgreSQL is running on your machine:
  • macOS: brew services start postgresql
  • Windows: Open services.msc ➔ find postgresql-x64 ➔ right-click and select Start.