Torben Sorensen
45ac4fccf5
Some checks failed
Deploy to Test Environment / deploy-to-test (push) Failing after 2m15s
350 lines
8.2 KiB
Markdown
350 lines
8.2 KiB
Markdown
# Quick Start Guide
|
|
|
|
Get Flyer Crawler running in 5 minutes.
|
|
|
|
---
|
|
|
|
## Prerequisites Checklist
|
|
|
|
Before starting, verify you have:
|
|
|
|
- [ ] **Windows 10/11** with WSL 2 enabled
|
|
- [ ] **Podman Desktop** installed ([download](https://podman-desktop.io/))
|
|
- [ ] **Node.js 20+** installed
|
|
- [ ] **Git** for cloning the repository
|
|
|
|
**Verify Prerequisites**:
|
|
|
|
```bash
|
|
# Check Podman
|
|
podman --version
|
|
# Expected: podman version 4.x or higher
|
|
|
|
# Check Node.js
|
|
node --version
|
|
# Expected: v20.x or higher
|
|
|
|
# Check WSL
|
|
wsl --list --verbose
|
|
# Expected: Shows WSL 2 distro
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Setup (5 Steps)
|
|
|
|
### Step 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
|
|
```
|
|
|
|
**Expected Output**:
|
|
|
|
```text
|
|
# Container IDs displayed, no errors
|
|
```
|
|
|
|
### Step 2: Initialize Database (2 minutes)
|
|
|
|
```bash
|
|
# Wait for PostgreSQL to be ready
|
|
podman exec flyer-crawler-postgres pg_isready -U postgres
|
|
# Expected: localhost:5432 - accepting connections
|
|
|
|
# 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
|
|
```
|
|
|
|
**Expected Output**:
|
|
|
|
```text
|
|
CREATE EXTENSION
|
|
CREATE EXTENSION
|
|
CREATE EXTENSION
|
|
CREATE TABLE
|
|
... (many tables created)
|
|
```
|
|
|
|
### Step 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 - see command below)
|
|
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)
|
|
GEMINI_API_KEY=your-google-gemini-api-key
|
|
GOOGLE_MAPS_API_KEY=your-google-maps-api-key
|
|
```
|
|
|
|
**Generate Secure Secrets**:
|
|
|
|
```bash
|
|
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
|
|
```
|
|
|
|
### Step 4: Install and Run (1 minute)
|
|
|
|
```bash
|
|
# Install dependencies (first time only)
|
|
npm install
|
|
|
|
# Start development server
|
|
npm run dev
|
|
```
|
|
|
|
**Expected Output**:
|
|
|
|
```text
|
|
> flyer-crawler@x.x.x dev
|
|
> concurrently ...
|
|
|
|
[API] Server listening on port 3001
|
|
[Vite] VITE ready at http://localhost:5173
|
|
```
|
|
|
|
### Step 5: Verify Installation
|
|
|
|
| Check | URL/Command | Expected Result |
|
|
| ----------- | ------------------------------ | ----------------------------------- |
|
|
| Frontend | `http://localhost:5173` | Flyer Crawler app loads |
|
|
| Backend API | `http://localhost:3001/health` | `{ "status": "ok", ... }` |
|
|
| Database | `podman exec ... psql -c ...` | `SELECT version()` returns Postgres |
|
|
| Containers | `podman ps` | Shows postgres and redis running |
|
|
|
|
---
|
|
|
|
## Full Dev Container (Recommended)
|
|
|
|
For a production-like environment with NGINX, Bugsink error tracking, and PM2 process management:
|
|
|
|
### Starting the Dev Container
|
|
|
|
```bash
|
|
# Start all services
|
|
podman-compose -f compose.dev.yml up -d
|
|
|
|
# View logs
|
|
podman-compose -f compose.dev.yml logs -f
|
|
```
|
|
|
|
### Access Points
|
|
|
|
| Service | URL | Notes |
|
|
| ----------- | ------------------------ | ---------------------------- |
|
|
| Frontend | `https://localhost` | NGINX proxy to Vite |
|
|
| Backend API | `http://localhost:3001` | Express server |
|
|
| Bugsink | `https://localhost:8443` | Error tracking (admin/admin) |
|
|
| PostgreSQL | `localhost:5432` | Database |
|
|
| Redis | `localhost:6379` | Cache |
|
|
|
|
**SSL Certificate Setup (Recommended)**:
|
|
|
|
To eliminate browser security warnings, install the mkcert CA certificate:
|
|
|
|
```bash
|
|
# Windows: Double-click certs/mkcert-ca.crt and install to Trusted Root CAs
|
|
# See certs/README.md for detailed instructions per platform
|
|
```
|
|
|
|
### PM2 Commands
|
|
|
|
```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
|
|
```
|
|
|
|
### Dev Container Processes
|
|
|
|
| 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 |
|
|
|
|
---
|
|
|
|
## Verification Commands
|
|
|
|
Run these to confirm everything is working:
|
|
|
|
```bash
|
|
# Check containers are running
|
|
podman ps
|
|
# Expected: flyer-crawler-postgres and flyer-crawler-redis both running
|
|
|
|
# Test database connection
|
|
podman exec flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev -c "SELECT version();"
|
|
# Expected: PostgreSQL 15.x with PostGIS
|
|
|
|
# Run tests (in dev container)
|
|
podman exec -it flyer-crawler-dev npm run test:unit
|
|
# Expected: All tests pass
|
|
|
|
# Run type check
|
|
podman exec -it flyer-crawler-dev npm run type-check
|
|
# Expected: No type errors
|
|
```
|
|
|
|
---
|
|
|
|
## Common Issues and Solutions
|
|
|
|
### "Unable to connect to Podman socket"
|
|
|
|
**Cause**: Podman machine not running
|
|
|
|
**Solution**:
|
|
|
|
```bash
|
|
podman machine start
|
|
```
|
|
|
|
### "Connection refused" to PostgreSQL
|
|
|
|
**Cause**: PostgreSQL still initializing
|
|
|
|
**Solution**:
|
|
|
|
```bash
|
|
# Wait for PostgreSQL to be ready
|
|
podman exec flyer-crawler-postgres pg_isready -U postgres
|
|
# Retry after "accepting connections" message
|
|
```
|
|
|
|
### Port 5432 or 6379 already in use
|
|
|
|
**Cause**: Another service using the port
|
|
|
|
**Solution**:
|
|
|
|
```bash
|
|
# Option 1: Stop conflicting service
|
|
# Option 2: Use different host port
|
|
podman run -d --name flyer-crawler-postgres -p 5433:5432 ...
|
|
# Then update DB_PORT=5433 in .env.local
|
|
```
|
|
|
|
### "JWT_SECRET must be at least 32 characters"
|
|
|
|
**Cause**: Secret too short in .env.local
|
|
|
|
**Solution**: Generate a longer secret:
|
|
|
|
```bash
|
|
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
|
|
```
|
|
|
|
### Tests fail with "TZ environment variable" errors
|
|
|
|
**Cause**: Timezone setting interfering with Node.js async hooks
|
|
|
|
**Solution**: Tests must run in dev container (not Windows host):
|
|
|
|
```bash
|
|
# CORRECT - run in container
|
|
podman exec -it flyer-crawler-dev npm test
|
|
|
|
# INCORRECT - do not run on Windows host
|
|
npm test
|
|
```
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
| Goal | Document |
|
|
| ----------------------- | ----------------------------------------------------- |
|
|
| Understand the codebase | [Architecture Overview](../architecture/OVERVIEW.md) |
|
|
| Configure environment | [Environment Variables](ENVIRONMENT.md) |
|
|
| Set up MCP tools | [MCP Configuration](../tools/MCP-CONFIGURATION.md) |
|
|
| Learn testing | [Testing Guide](../development/TESTING.md) |
|
|
| Understand DB schema | [Database Documentation](../architecture/DATABASE.md) |
|
|
| Read ADRs | [ADR Index](../adr/index.md) |
|
|
| Full installation guide | [Installation Guide](INSTALL.md) |
|
|
|
|
---
|
|
|
|
## Daily Development Workflow
|
|
|
|
```bash
|
|
# 1. Start containers
|
|
podman start flyer-crawler-postgres flyer-crawler-redis
|
|
|
|
# 2. Start dev server
|
|
npm run dev
|
|
|
|
# 3. Make changes and test
|
|
npm test
|
|
|
|
# 4. Type check before commit
|
|
npm run type-check
|
|
|
|
# 5. Commit changes
|
|
git commit
|
|
```
|
|
|
|
**For dev container users**:
|
|
|
|
```bash
|
|
# 1. Start dev container
|
|
podman-compose -f compose.dev.yml up -d
|
|
|
|
# 2. View logs
|
|
podman exec -it flyer-crawler-dev pm2 logs
|
|
|
|
# 3. Run tests
|
|
podman exec -it flyer-crawler-dev npm test
|
|
|
|
# 4. Stop when done
|
|
podman-compose -f compose.dev.yml down
|
|
```
|
|
|
|
---
|
|
|
|
Last updated: January 2026
|