Kenneth's Setup Guide

Welcome! This guide will help you set up your Mac for Price Watch development. We'll go step-by-step, explaining what each tool does and why we need it.

Time needed: 45-60 minutes (mostly waiting for downloads)

What You'll Install

Tool	What It Does	Why We Need It
Homebrew	Package manager for Mac	Makes installing developer tools easy
Git	Version control	Track code changes and collaborate
Docker Desktop	Container platform	Runs the entire system on your Mac
VS Code/Cursor/Up to you	Code editor	Write and edit code with helpful features
GitHub Account	Code hosting	Access the Price Watch repository

Part 1: Initial Mac Setup

Step 1: Enable Developer Tools

What: Mac's built-in command-line developer tools Why: Many developer tools depend on these

Open Terminal (Applications → Utilities → Terminal)
Copy and paste this command:
```
xcode-select --install
```
Click "Install" in the popup window
Wait 5-10 minutes for installation
Type this to verify:
```
xcode-select -p
```
Expected output: /Library/Developer/CommandLineTools

What this does: Installs compilers and tools that other software needs to build and run.

Step 2: Install Homebrew

What: Homebrew is like an app store for developer tools Why: Makes installing and updating tools simple

Open Terminal (if not already open)

Go to https://brew.sh and copy the install command, OR paste this:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Press Enter and follow the prompts (may ask for your Mac password)
IMPORTANT: After installation, Homebrew shows a message about running 2 commands. Copy and run those commands.

They look like:
```
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
```
Close Terminal and reopen it
Verify Homebrew works:
```
brew --version
```
Expected output: Homebrew 4.x.x (any 4.x version is fine)

Troubleshooting:

If brew --version says "command not found", you need to run those 2 commands from step 4
Ask Dylan if you get stuck!

Step 3: Install Git

What: Git tracks changes to code over time Why: We use it to save our work and collaborate

Install Git:
```
brew install git
```
Verify installation:
```
git --version
```
Expected output: git version 2.x.x

Configure Git with your information:

git config --global user.name "Kenneth [Last Name]"
git config --global user.email "[email protected]"

What this does: Sets your identity for code commits (like signing your work).

Step 4: Set Up GitHub Access

What: GitHub hosts our code repository Why: You need access to download and update the code

Create GitHub Account (if you don't have one)

Go to https://github.com/signup
Create an account (use your SendCutSend email)
Tell Dylan your GitHub username so he can give you access

Set Up SSH Key (secure authentication)

What: SSH keys are like a secure password that Git uses automatically Why: You won't have to type your password every time you push code

Generate a new SSH key:

ssh-keygen -t ed25519 -C "[email protected]"

Press Enter 3 times (accept default location, no passphrase)
Copy your public key:
```
cat ~/.ssh/id_ed25519.pub
```
This shows a long line starting with ssh-ed25519. Copy the entire line.
Add to GitHub:
- Go to https://github.com/settings/keys
- Click "New SSH key"
- Title: "Kenneth's Mac"
- Paste the key you copied
- Click "Add SSH key"
Test the connection:
```
ssh -T [email protected]
```
Expected output: Hi [your-username]! You've successfully authenticated...

Troubleshooting:

If you get "Permission denied", double-check you copied the entire key
If you get "Host key verification", type yes and press Enter

Step 5: Install Docker Desktop

What: Docker runs all 5 parts of our system (database, Redis, Rails, Sidekiq, scraper) in isolated containers Why: Makes setup consistent across different Macs - everyone runs the exact same environment

Go to https://www.docker.com/products/docker-desktop
Download Docker Desktop for Mac
- If you have an M1/M2/M3 Mac: Choose "Apple Chip"
- If you have an Intel Mac: Choose "Intel Chip"
- Not sure? Click the Apple menu → "About This Mac" → Look for "Chip" or "Processor"
Open the downloaded .dmg file
Drag Docker to Applications folder
Open Docker from Applications
Follow the setup wizard (accept defaults)
Docker icon appears in menu bar (top-right, looks like a whale)
Wait for "Docker Desktop is running" message
Verify Docker works:
```
docker --version
docker compose version
```
Expected output: Version numbers for both commands

Settings to configure:

Click Docker icon in menu bar → Settings
Go to "Resources"
Set Memory: 4 GB (minimum)
Set CPUs: 2 (minimum)
Click "Apply & Restart"

What this does: Docker creates mini-computers inside your Mac that run our database, job queue, Rails app, and scraper service.

Step 6: Install VS Code (Code Editor)

What: VS Code is a powerful code editor with helpful features Why: Makes writing code easier with syntax highlighting, auto-complete, and debugging

Go to https://code.visualstudio.com/
Download for macOS
Open the downloaded .zip file
Drag "Visual Studio Code" to Applications folder
Open VS Code from Applications

Install Helpful Extensions

In VS Code, click the Extensions icon (looks like 4 squares, left sidebar)
Search and install these:
- Ruby (by Shopify) - Helps with Rails code
- Ruby LSP (by Shopify) - Auto-complete for Ruby
- Docker (by Microsoft) - Manage Docker containers
- ESLint (by Microsoft) - JavaScript/TypeScript linting
- Prettier - Code formatter

What these do: Each extension adds helpful features like auto-complete, error highlighting, and code formatting.

Part 2: Clone the Price Watch Repository

Step 1: Create a Projects Folder

Why: Keeps your development work organized

mkdir -p ~/Documents/work/SendCutSend
cd ~/Documents/work/SendCutSend

What this does:

mkdir -p creates folders (the -p creates parent folders if needed)
cd changes directory (moves you into that folder)
~ is a shortcut for your home folder

Step 2: Clone the Repository

What: Downloads the entire project to your Mac Why: You need the code on your computer to work on it

git clone [email protected]:dylan-conlin/price-watch.git
cd price-watch

What this does:

git clone downloads the repository
cd price-watch moves you into the project folder

Step 3: Open in VS Code

code .

What this does: Opens the current folder (. means "here") in VS Code.

You should now see the project structure in the left sidebar:

rails/ - Rails application
scraper/ - Node.js scraper service
docs/ - Documentation
README.md - Project overview

Part 3: Set Up the Development Environment

Step 1: Copy Environment Template

What: Creates a configuration file for secrets (passwords, credentials) Why: The scraper needs competitor account credentials to log in

cp scraper/.env.example scraper/.env

What this does: Copies the example file to create your own .env file.

Step 2: Add Real Credentials

Open scraper/.env in VS Code
Replace the placeholder credentials with real ones (ask Dylan for these)

Example:

[email protected]
JACOB_HOLLY_PASSWORD=RealPasswordHere123!
JACOB_HOLLY_LOCATION=atlanta_ga

IMPORTANT: Never commit .env to Git! It contains passwords. (Don't worry - it's already in .gitignore so Git will ignore it automatically)

Step 3: Start Docker Services

What: Starts all 5 services (postgres, redis, rails, sidekiq, scraper) Why: The system needs all pieces running to work

docker compose up -d

What this does:

docker compose up starts all services defined in docker-compose.yml
-d runs in "detached" mode (background) so you get your terminal back

Wait 30-60 seconds for everything to start, then check status:

docker compose ps

Expected output: All 5 services show "Up" status

Step 4: Set Up the Database

What: Creates tables and loads historical data Why: Rails needs a database structure to store competitors, quotes, parts, etc.

docker compose exec rails bin/rails db:create
docker compose exec rails bin/rails db:migrate
docker compose exec rails bin/rails db:seed

What each command does:

db:create - Creates the database
db:migrate - Creates tables (materials, personas, quotes, etc.)
db:seed - Loads historical data (182 materials, 205 quotes, 114 parts, 3 personas)

Expected output: Each command shows what it created/loaded

Step 5: Verify Everything Works

Run tests:

make test
make test-scraper

Expected output:

Rails: 95 tests, 217 assertions, 0 failures, 0 errors
Scraper: 25 passed

If tests pass, you're ready to go! 🎉

Part 4: Your First Scrape

Let's run the scraper to collect a real quote!

Step 1: Open Rails Console

What: Rails console is like a playground to interact with the system Why: Easiest way to test the scraper manually

docker compose exec rails bin/rails console

You'll see a prompt: irb(main):001:0>

Step 2: Trigger a Scrape

Copy and paste this:

# Claim an available persona (account rotation)
persona = Persona.claim_available!('oshcut')

# Get a part to quote
part = PartProfile.first

# Get a material to quote
material = Material.find_by(sku: 'ALU6061-125')

# Collect quotes for 6 quantities
result = ScrapeOrchestrator.collect_quote(
  competitor: 'oshcut',
  persona: persona,
  part_profile: part,
  material: material,
  quantities: [1, 10, 25, 50, 100, 250]
)

# See the results
puts "Collected #{result[:quotes].size} quotes!"
result[:quotes].each do |quote|
  puts "Qty #{quote.quantity}: $#{quote.unit_price} (#{quote.lead_time_days} days)"
end

Step 3: Watch It Work

What's happening:

Browser opens in Docker container (you won't see it)
Logs in to OshCut
Uploads STEP file
Selects material
Tests 6 quantities
Saves quotes to database
Takes screenshots

Takes about 30 seconds.

Expected output:

Collected 6 quotes!
Qty 1: $19.46 (3 days)
Qty 10: $10.05 (3 days)
Qty 25: $8.97 (3 days)
Qty 50: $8.19 (3 days)
Qty 100: $7.35 (3 days)
Qty 250: $6.26 (3 days)

Notice: Prices go down as quantity increases (volume discounts!)

Step 4: Exit Console

exit

Common Commands Reference

Keep this section handy!

Docker Commands

# Start all services
docker compose up -d

# Stop all services
docker compose down

# View logs
docker compose logs -f rails      # Rails app
docker compose logs -f scraper    # Scraper service
docker compose logs -f sidekiq    # Background jobs

# Restart a service
docker compose restart rails
docker compose restart scraper

# Check service status
docker compose ps

Database Commands

# Rails console (interact with database)
docker compose exec rails bin/rails console

# Run migrations (update database structure)
docker compose exec rails bin/rails db:migrate

# Reset database (WARNING: deletes all data!)
docker compose exec rails bin/rails db:reset

Testing Commands

# Run Rails tests
make test

# Run scraper tests
make test-scraper

# Run specific test file
docker compose exec rails bin/rails test test/models/persona_test.rb

Git Commands

# Check what changed
git status

# See your recent commits
git log --oneline -10

# Pull latest code from GitHub
git pull

# Create a new branch for your work
git checkout -b kenneth/add-new-feature

# Save your changes
git add .
git commit -m "Add new feature"

# Push to GitHub
git push

Troubleshooting

"Docker daemon is not running"

Problem: Docker Desktop isn't started Solution:

Open Docker Desktop from Applications
Wait for "Docker Desktop is running" message
Try your command again

"Port already in use"

Problem: Another service is using the port Solution:

docker compose down
# Wait 5 seconds
docker compose up -d

"Permission denied" with Git

Problem: SSH key not set up correctly Solution: Go back to "Part 1, Step 4" and re-do SSH key setup

Rails console won't start

Problem: Rails service isn't running Solution:

docker compose ps          # Check if rails is "Up"
docker compose logs rails  # Check for errors
docker compose restart rails

Tests failing

Problem: Something isn't set up correctly Solution:

# Reset database and try again
docker compose exec rails bin/rails db:reset
make test

If still failing, ask Dylan!

What to Do If You Get Stuck

Check the logs: docker compose logs -f rails or docker compose logs -f scraper
Restart services: docker compose down && docker compose up -d
Ask Dylan: Take a screenshot of the error and send it to Dylan

Next Steps

Once you're set up and the scraper works:

Read the documentation:
- Getting Started Guide - Project overview
- Development Workflow - Daily development tasks
- Testing Strategy - How tests work
Explore the code:
- Start with rails/app/models/ - Data models (Persona, Material, Quote)
- Then scraper/src/scrapers/oshcut-scraper.ts - The OshCut scraper
Make a small change:
- Try adding a puts statement to see what's happening
- Run the scraper again
- See your change in action!

Learning Resources

Mac Terminal Basics:

https://support.apple.com/guide/terminal/welcome/mac

Git Basics:

https://try.github.io (interactive tutorial)

Ruby on Rails:

https://guides.rubyonrails.org/getting_started.html

TypeScript/Node.js:

https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html

Docker:

https://docs.docker.com/get-started/

Questions?

Ask Dylan anytime! There are no dumb questions. Everyone was new to this once.

Remember: You have deep domain knowledge (competitors, pricing, materials) that Dylan doesn't have. Your input is valuable even while you're learning the technical side.

Welcome to the team! 🚀

dylan-conlin/kenneth-setup.md

Kenneth's Setup Guide

What You'll Install

Part 1: Initial Mac Setup

Step 1: Enable Developer Tools

Step 2: Install Homebrew

Step 3: Install Git

Step 4: Set Up GitHub Access

Create GitHub Account (if you don't have one)

Set Up SSH Key (secure authentication)

Step 5: Install Docker Desktop

Step 6: Install VS Code (Code Editor)

Install Helpful Extensions

Part 2: Clone the Price Watch Repository

Step 1: Create a Projects Folder

Step 2: Clone the Repository

Step 3: Open in VS Code

Part 3: Set Up the Development Environment

Step 1: Copy Environment Template

Step 2: Add Real Credentials

Step 3: Start Docker Services

Step 4: Set Up the Database

Step 5: Verify Everything Works

Part 4: Your First Scrape

Step 1: Open Rails Console

Step 2: Trigger a Scrape

Step 3: Watch It Work

Step 4: Exit Console

Common Commands Reference

Docker Commands

Database Commands

Testing Commands

Git Commands

Troubleshooting

"Docker daemon is not running"

"Port already in use"

"Permission denied" with Git

Rails console won't start

Tests failing

What to Do If You Get Stuck

Next Steps

Learning Resources

Questions?