flyer-crawler.projectium.com/INSTALL.md

Installation Guide

This guide covers setting up a local development environment for Flyer Crawler.

Prerequisites

• Node.js 20.x or later
• Access to a PostgreSQL database (local or remote)
• Redis instance (for session management)
• Google Gemini API key
• Google Maps API key (for geocoding)

Quick Start

If you already have PostgreSQL and Redis configured:

# Install dependencies
npm install

# Run in development mode
npm run dev

---

Development Environment with Podman (Recommended for Windows)

This approach uses Podman with an Ubuntu container for a consistent development environment.

Step 1: Install Prerequisites on Windows

1. Install WSL 2: Podman on Windows relies on the Windows Subsystem for Linux.

   wsl --install
   

   Run this in an administrator PowerShell.

2. Install Podman Desktop: Download and install Podman Desktop for Windows.

Step 2: Set Up Podman

1. Initialize Podman: Launch Podman Desktop. It will automatically set up its WSL 2 machine.
2. Start Podman: Ensure the Podman machine is running from the Podman Desktop interface.

Step 3: Set Up the Ubuntu Container

1. Pull Ubuntu Image:

   podman pull ubuntu:latest
   

2. Create a Podman Volume (persists node_modules between container restarts):

   podman volume create node_modules_cache
   

3. Run the Ubuntu Container:

   Open a terminal in your project's root directory and run:

   podman run -it -p 3001:3001 -p 5173:5173 --name flyer-dev \
     -v "$(pwd):/app" \
     -v "node_modules_cache:/app/node_modules" \
     ubuntu:latest
   

   Flag	Purpose
   -p 3001:3001	Forwards the backend server port
   -p 5173:5173	Forwards the Vite frontend server port
   --name flyer-dev	Names the container for easy reference
   -v "...:/app"	Mounts your project directory into the container
   -v "node_modules_cache:/app/node_modules"	Mounts the named volume for node_modules

Step 4: Configure the Ubuntu Environment

You are now inside the Ubuntu container's shell.

1. Update Package Lists:

   apt-get update
   

2. Install Dependencies:

   apt-get install -y curl git
   curl -sL https://deb.nodesource.com/setup_20.x | bash -
   apt-get install -y nodejs
   

3. Navigate to Project Directory:

   cd /app
   

4. Install Project Dependencies:

   npm install
   

Step 5: Run the Development Server

npm run dev

Step 6: Access the Application

• Frontend: http://localhost:5173
• Backend API: http://localhost:3001

Managing the Container

Action	Command
Stop the container	Press Ctrl+C, then type exit
Restart the container	podman start -a -i flyer-dev
Remove the container	podman rm flyer-dev

---

Environment Variables

This project is configured to run in a CI/CD environment and does not use .env files. All configuration must be provided as environment variables.

For local development, you can export these in your shell or use your IDE's environment configuration:

Variable	Description
DB_HOST	PostgreSQL server hostname
DB_USER	PostgreSQL username
DB_PASSWORD	PostgreSQL password
DB_DATABASE_PROD	Production database name
JWT_SECRET	Secret string for signing auth tokens
VITE_GOOGLE_GENAI_API_KEY	Google Gemini API key
GOOGLE_MAPS_API_KEY	Google Maps Geocoding API key
REDIS_PASSWORD_PROD	Production Redis password
REDIS_PASSWORD_TEST	Test Redis password

---

Seeding Development Users

To create initial test accounts (admin@example.com and user@example.com):

npm run seed

After running, you may need to restart your IDE's TypeScript server to pick up any generated types.

---

Next Steps

• Database Setup - Set up PostgreSQL with required extensions
• Authentication Setup - Configure OAuth providers
• Deployment Guide - Deploy to production