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)

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

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

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

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

# 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

# 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"

podman machine start

"Connection refused" to PostgreSQL

Wait a few seconds for PostgreSQL to initialize:

podman exec flyer-crawler-postgres pg_isready -U postgres

Port 5432 or 6379 already in use

Stop conflicting services or change port mappings:

# 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
• Understand the architecture: docs/architecture/DATABASE.md
• Learn testing: docs/development/TESTING.md
• Explore ADRs: docs/adr/index.md
• Contributing: CONTRIBUTING.md

Development Workflow

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