Complete Setup Instructions for Ubuntu 24.04 LTS

This guide walks you through setting up the FastAPI Tutorial from scratch on a fresh Ubuntu 24.04 LTS installation.

Prerequisites Check

Before starting, verify your system:

# Check Ubuntu version
lsb_release -a
# Should show: Ubuntu 24.04 LTS

# Check available disk space (need at least 2GB)
df -h

# Update system
sudo apt update && sudo apt upgrade -y

Step 1: Install Node.js and npm

Node.js 20.x LTS is recommended for this project.

# Install curl if not already installed
sudo apt install curl -y

# Add NodeSource repository for Node.js 20.x
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# Install Node.js (includes npm)
sudo apt-get install -y nodejs

# Verify installations
node --version    # Should show v20.x.x
npm --version     # Should show 10.x.x

# (Optional) Update npm to latest version
sudo npm install -g npm@latest

Troubleshooting Node.js Installation

If you encounter permission errors:

# Create npm global directory in your home folder
mkdir ~/.npm-global

# Configure npm to use new directory
npm config set prefix '~/.npm-global'

# Add to PATH (add this line to ~/.bashrc or ~/.profile)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

# Reload shell configuration
source ~/.bashrc

Step 2: Install Git

Step 3: Clone the Repository

# Create a directory for your projects (optional but recommended)
mkdir -p ~/projects
cd ~/projects

# Clone the repository
git clone https://github.com/lgtkgtv/fastapi_tutorial.git
cd fastapi_tutorial

# List files to verify
ls -la

Step 4: Install Project Dependencies

# Make sure you're in the project directory
cd ~/projects/fastapi_tutorial

# Install all dependencies from package.json
npm install

# This will take 2-5 minutes and install ~200+ packages
# You should see a progress bar

Expected Output

added 234 packages, and audited 235 packages in 2m

42 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

If Installation Fails

# Clear npm cache
npm cache clean --force

# Delete node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Try again
npm install

Step 5: Verify Installation

Check that all required dependencies are installed:

# Check if key dependencies exist
npm list react react-dom lucide-react tailwindcss

# Should show versions like:
# react@18.3.1
# react-dom@18.3.1
# lucide-react@0.544.0
# tailwindcss@3.4.1

Step 6: Verify Configuration Files

Ensure these files exist in your project root:

# Check for required config files
ls -la tailwind.config.js postcss.config.js vite.config.js

# Display contents of tailwind.config.js
cat tailwind.config.js

# Display contents of postcss.config.js
cat postcss.config.js

If Config Files Are Missing

Create them manually:

tailwind.config.js:

cat > tailwind.config.js << 'EOF'
/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}
EOF

postcss.config.js:

cat > postcss.config.js << 'EOF'
export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}
EOF

Step 7: Verify Source Files

# Check src directory structure
tree src/ || ls -R src/

# Should show:
# src/
# ├── App.jsx
# ├── main.jsx
# ├── index.css
# └── assets/

Verify index.css has Tailwind directives

cat src/index.css

# Should contain:
# @tailwind base;
# @tailwind components;
# @tailwind utilities;

If missing, create it:

cat > src/index.css << 'EOF'
@tailwind base;
@tailwind components;
@tailwind utilities;
EOF

Step 8: Start Development Server

# Start the dev server
npm run dev

# Expected output:
# VITE v5.x.x  ready in 500 ms
#
# ➜  Local:   http://localhost:5173/
# ➜  Network: use --host to expose
# ➜  press h + enter to show help

Accessing the Application

On the same machine:
- Open browser and go to: http://localhost:5173

From another computer on same network:

# Stop the server (Ctrl+C)
# Restart with --host flag
npm run dev -- --host

# Now accessible at: http://YOUR_IP:5173
# Find your IP with: hostname -I | awk '{print $1}'

Change the port:

# Stop the server (Ctrl+C)
# Start on different port
npm run dev -- --port 3000

Step 9: Verify Application is Working

Once the dev server is running:

Open browser to http://localhost:5173
You should see:
- Page title: "FastAPI Interactive Tutorial"
- Blue/indigo gradient background
- Left sidebar with lesson navigation (15 lessons)
- Main content area showing Lesson 1
Test functionality:
- Click through different lessons
- Click "Copy" button on code blocks
- Click "Mark Complete" button
- Navigate with Previous/Next buttons

Step 10: Build for Production (Optional)

# Create optimized production build
npm run build

# Output will be in dist/ directory
ls -lh dist/

# Preview production build locally
npm run preview

# Opens at http://localhost:4173

Common Issues and Solutions

Issue: Port 5173 already in use

# Find and kill process using port 5173
sudo lsof -t -i:5173 | xargs kill -9

# Or use a different port
npm run dev -- --port 3000

Issue: npm command not found

# Check if Node.js is installed
which node

# If not found, reinstall Node.js (see Step 1)

Issue: Permission denied errors

# Don't use sudo with npm in project directory
# If you get permission errors, fix npm permissions:
sudo chown -R $USER:$USER ~/.npm
sudo chown -R $USER:$USER ~/projects/fastapi_tutorial

Issue: Styles not loading (page looks plain)

# Verify Tailwind is installed
npm list tailwindcss

# Check index.css has Tailwind directives
cat src/index.css

# Restart dev server
# Ctrl+C to stop, then: npm run dev

Issue: Module not found errors

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

Issue: React version conflicts

# Check installed React version
npm list react

# If showing multiple versions, force single version
npm install react@18.2.0 react-dom@18.2.0

Environment Variables (If Needed)

If your project needs environment variables:

# Create .env file
cat > .env << 'EOF'
VITE_API_URL=http://localhost:8000
VITE_APP_NAME=FastAPI Tutorial
EOF

# Access in code with: import.meta.env.VITE_API_URL

Git Workflow

Initial Setup

# Initialize Git (if not already done)
git init

# Add files
git add .

# Commit
git commit -m "Initial commit"

# Add remote (if not already added)
git remote add origin <your-repo-url>

# Push to GitHub
git push -u origin main

Daily Workflow

# Pull latest changes
git pull origin main

# Make your changes to files
# ...

# Check what changed
git status
git diff

# Stage changes
git add .

# Commit with message
git commit -m "Description of changes"

# Push to remote
git push origin main

Performance Optimization

Enable faster rebuilds

Add to vite.config.js:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    port: 5173,
    hmr: {
      overlay: true
    }
  },
  build: {
    sourcemap: false, // Faster builds
    minify: 'terser'
  }
})

Reduce bundle size

Already optimized with:

Vite's tree-shaking
Production build minification
Code splitting

Monitoring Resources

# Check disk usage
du -sh node_modules/    # ~200-300MB
du -sh dist/            # ~200KB after build

# Monitor dev server
# Dev server uses ~100-200MB RAM
# Build process uses ~500MB-1GB RAM temporarily

Maintenance

Update dependencies periodically

# Check for outdated packages
npm outdated

# Update all to latest (careful - may break things)
npm update

# Update specific package
npm update lucide-react

# Update Node.js itself
# Use nvm (Node Version Manager) or download from nodejs.org

Clean up

# Remove node_modules (saves space when not developing)
rm -rf node_modules

# Clear npm cache
npm cache clean --force

# Reinstall when needed
npm install

Security Best Practices

# Check for vulnerabilities
npm audit

# Fix vulnerabilities automatically
npm audit fix

# For high/critical issues requiring breaking changes
npm audit fix --force  # Use with caution

# Update npm itself
npm install -g npm@latest

Next Steps

Customize the tutorial - Edit src/App.jsx to modify lessons
Deploy - See DEPLOYMENT_AWS.md or DEPLOYMENT_GCP.md
Add features - Progress persistence, search, etc.
Share - Push to GitHub and share the link

Getting Help

If you encounter issues:

Check this guide's troubleshooting section
Review the error message carefully
Search GitHub issues
Check Vite documentation: https://vitejs.dev
Check React documentation: https://react.dev

Summary Checklist

If all items are checked, you're ready to go!

FilesExpand file tree

setup.md

Latest commit

History