# 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

### 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`):

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