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:

```bash
# 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.

   ```powershell
   wsl --install
   ```

   Run this in an administrator PowerShell.

2. **Install Podman Desktop**: Download and install [Podman Desktop for Windows](https://podman-desktop.io/).

### 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**:

   ```bash
   podman pull ubuntu:latest
   ```

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

   ```bash
   podman volume create node_modules_cache
   ```

3. **Run the Ubuntu Container**:

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

   ```bash
   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**:

   ```bash
   apt-get update
   ```

2. **Install Dependencies**:

   ```bash
   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**:

   ```bash
   cd /app
   ```

4. **Install Project Dependencies**:

   ```bash
   npm install
   ```

### Step 5: Run the Development Server

```bash
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](../FLYER-URL-CONFIGURATION.md#ssl-certificate-configuration-dev-container)

**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`](../../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:

```bash
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](DATABASE.md) - Set up PostgreSQL with required extensions
- [Authentication Setup](AUTHENTICATION.md) - Configure OAuth providers
- [Deployment Guide](DEPLOYMENT.md) - Deploy to production