flyer-crawler.projectium.com/docs/getting-started/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

Dev Container with HTTPS (Full Stack)

When using the full dev container stack with NGINX (via compose.dev.yml), access the application over HTTPS:

• Frontend: https://localhost or https://127.0.0.1
• Backend API: http://localhost:3001

SSL Certificate Notes:

• The dev container uses self-signed certificates generated by mkcert
• Both localhost and 127.0.0.1 are valid hostnames (certificate includes both as SANs)
• If images fail to load with SSL errors, see FLYER-URL-CONFIGURATION.md

Eliminate SSL Warnings (Recommended):

To avoid browser security warnings for self-signed certificates, install the mkcert CA certificate on your system. The CA certificate is located at certs/mkcert-ca.crt in the project root.

See certs/README.md for platform-specific installation instructions (Windows, macOS, Linux, Firefox).

After installation:

• Your browser will trust all mkcert certificates without warnings
• Both https://localhost/ and https://127.0.0.1/ will work without SSL errors
• Flyer images will load without ERR_CERT_AUTHORITY_INVALID errors

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 Data

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

npm run seed

The seed script performs the following actions:

1. Rebuilds the database schema from sql/master_schema_rollup.sql
2. Creates test user accounts (admin and regular user)
3. Copies test flyer images from src/tests/assets/ to public/flyer-images/
4. Creates a sample flyer with items linked to the test images
5. Seeds watched items and a shopping list for the test user

Test Images: The seed script copies test-flyer-image.jpg and test-flyer-icon.png to the public/flyer-images/ directory, which is served by NGINX at /flyer-images/.

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