flyer-crawler.projectium.com/docs/getting-started/QUICKSTART.md

# Quick Start Guide

Get Flyer Crawler running in 5 minutes.

## Prerequisites

- **Windows 10/11** with WSL 2
- **Podman Desktop** installed
- **Node.js 20+** installed

## 1. Start Containers (1 minute)

```bash
# Start PostgreSQL and Redis
podman start flyer-crawler-postgres flyer-crawler-redis

# If containers don't exist yet, create them:
podman run -d --name flyer-crawler-postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=flyer_crawler_dev \
  -p 5432:5432 \
  docker.io/postgis/postgis:15-3.3

podman run -d --name flyer-crawler-redis \
  -p 6379:6379 \
  docker.io/library/redis:alpine
```

## 2. Initialize Database (2 minutes)

```bash
# Wait for PostgreSQL to be ready
podman exec flyer-crawler-postgres pg_isready -U postgres

# Install extensions
podman exec flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev \
  -c "CREATE EXTENSION IF NOT EXISTS postgis; CREATE EXTENSION IF NOT EXISTS pg_trgm; CREATE EXTENSION IF NOT EXISTS \"uuid-ossp\";"

# Apply schema
podman exec -i flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev < sql/master_schema_rollup.sql
```

## 3. Configure Environment (1 minute)

Create `.env.local` in the project root:

```bash
# Database
DB_HOST=localhost
DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=flyer_crawler_dev
DB_PORT=5432

# Redis
REDIS_URL=redis://localhost:6379

# Application
NODE_ENV=development
PORT=3001
FRONTEND_URL=http://localhost:5173

# Secrets (generate your own)
JWT_SECRET=your-dev-jwt-secret-at-least-32-chars-long
SESSION_SECRET=your-dev-session-secret-at-least-32-chars-long

# AI Services (get your own keys)
VITE_GOOGLE_GENAI_API_KEY=your-google-genai-api-key
GOOGLE_MAPS_API_KEY=your-google-maps-api-key
```

## 4. Install & Run (1 minute)

```bash
# Install dependencies (first time only)
npm install

# Start development server
npm run dev
```

## 5. Access Application

- **Frontend**: http://localhost:5173
- **Backend API**: http://localhost:3001
- **Health Check**: http://localhost:3001/health

### Dev Container (HTTPS)

When using the full dev container with NGINX, access via HTTPS:

- **Frontend**: https://localhost or https://127.0.0.1
- **Backend API**: http://localhost:3001
- **Bugsink**: `https://localhost:8443` (error tracking)

**Note:** The dev container accepts both `localhost` and `127.0.0.1` for HTTPS connections. The self-signed certificate is valid for both hostnames.

**SSL Certificate Warnings:** To eliminate browser security warnings for self-signed certificates, install the mkcert CA certificate. See [`certs/README.md`](../../certs/README.md) for platform-specific installation instructions. This is optional but recommended for a better development experience.

### Dev Container Architecture

The dev container uses PM2 for process management, matching production (ADR-014):

| Process                    | Description              | Port |
| -------------------------- | ------------------------ | ---- |
| `flyer-crawler-api-dev`    | API server (tsx watch)   | 3001 |
| `flyer-crawler-worker-dev` | Background job worker    | -    |
| `flyer-crawler-vite-dev`   | Vite frontend dev server | 5173 |

**PM2 Commands** (run inside container):

```bash
# View process status
podman exec -it flyer-crawler-dev pm2 status

# View logs (all processes)
podman exec -it flyer-crawler-dev pm2 logs

# Restart all processes
podman exec -it flyer-crawler-dev pm2 restart all

# Restart specific process
podman exec -it flyer-crawler-dev pm2 restart flyer-crawler-api-dev
```

## Verify Installation

```bash
# Check containers are running
podman ps

# Test database connection
podman exec flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev -c "SELECT version();"

# Run tests (in dev container)
podman exec -it flyer-crawler-dev npm run test:unit
```

## Common Issues

### "Unable to connect to Podman socket"

```bash
podman machine start
```

### "Connection refused" to PostgreSQL

Wait a few seconds for PostgreSQL to initialize:

```bash
podman exec flyer-crawler-postgres pg_isready -U postgres
```

### Port 5432 or 6379 already in use

Stop conflicting services or change port mappings:

```bash
# Use different host port
podman run -d --name flyer-crawler-postgres -p 5433:5432 ...
```

Then update `DB_PORT=5433` in `.env.local`.

## Next Steps

- **Read the docs**: [docs/README.md](../README.md)
- **Understand the architecture**: [docs/architecture/DATABASE.md](../architecture/DATABASE.md)
- **Learn testing**: [docs/development/TESTING.md](../development/TESTING.md)
- **Explore ADRs**: [docs/adr/index.md](../adr/index.md)
- **Contributing**: [CONTRIBUTING.md](../../CONTRIBUTING.md)

## Development Workflow

```bash
# Daily workflow
podman start flyer-crawler-postgres flyer-crawler-redis
npm run dev
# ... make changes ...
npm test
git commit
```

For detailed setup instructions, see [INSTALL.md](INSTALL.md).