auto-claude: subtask-3-4 - Write development environment setup instructions

README.md

@@ -87,20 +87,227 @@ nordabiz/
 └── deployment_checklist.md     # Production deployment guide
 ```
 
-## Uruchomienie
+## Development Environment Setup
 
-Projekt jest statyczną stroną HTML. Aby uruchomić:
+Follow these steps to set up the development environment on your local machine.
 
-1. Otwórz plik `index.html` w przeglądarce
-2. Lub użyj lokalnego serwera:
-   ```bash
-   # Python 3
-   python3 -m http.server 8000
+### Prerequisites
 
-   # Node.js
-   npx http-server
-   ```
-3. Odwiedź: `http://localhost:8000`
+- **Python 3.9+** - Core programming language
+- **PostgreSQL 15+** - Database (via Docker or native installation)
+- **Git** - Version control
+- **Docker** (optional) - For containerized PostgreSQL
+
+### Installation Steps
+
+#### 1. Clone the Repository
+
+```bash
+git clone https://github.com/pienczyn/nordabiz.git
+cd nordabiz
+```
+
+#### 2. Create Virtual Environment
+
+```bash
+# Create virtual environment
+python3 -m venv venv
+
+# Activate virtual environment
+# On macOS/Linux:
+source venv/bin/activate
+
+# On Windows:
+venv\Scripts\activate
+```
+
+#### 3. Install Python Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+This will install all required packages including:
+- Flask 3.0.0 (web framework)
+- SQLAlchemy 2.0.23 (ORM)
+- psycopg2-binary 2.9.9 (PostgreSQL adapter)
+- google-generativeai 0.3.2 (Gemini AI)
+- Flask-Login, Flask-WTF, Flask-Limiter (security)
+- And more (see `requirements.txt` for complete list)
+
+#### 4. Set Up PostgreSQL Database
+
+**Option A: Using Docker (Recommended for Development)**
+
+```bash
+# Start PostgreSQL container
+docker compose up -d
+
+# Verify container is running
+docker ps | grep nordabiz-postgres
+```
+
+This creates a PostgreSQL 15 database on `localhost:5433` with:
+- Database: `nordabiz`
+- User: `nordabiz_app`
+- Password: `dev_password`
+
+**Option B: Native PostgreSQL Installation**
+
+```bash
+# Install PostgreSQL (example for Ubuntu/Debian)
+sudo apt install postgresql-15 postgresql-contrib-15
+
+# Create database and user
+sudo -u postgres psql
+```
+
+```sql
+CREATE DATABASE nordabiz;
+CREATE USER nordabiz_app WITH PASSWORD 'your_password_here';
+GRANT ALL PRIVILEGES ON DATABASE nordabiz TO nordabiz_app;
+\q
+```
+
+#### 5. Initialize Database Schema
+
+```bash
+# Apply schema (Docker setup)
+docker exec -i nordabiz-postgres psql -U nordabiz_app -d nordabiz < database/schema.sql
+
+# Or for native PostgreSQL
+psql -U nordabiz_app -d nordabiz -h localhost < database/schema.sql
+```
+
+#### 6. Configure Environment Variables
+
+Create `.env` file in the project root:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and configure the following variables:
+
+```bash
+# Flask Configuration
+SECRET_KEY=your-super-secret-key-change-this
+FLASK_ENV=development
+
+# Server Configuration
+PORT=5000
+HOST=0.0.0.0
+
+# Database Configuration (for Docker setup)
+DATABASE_URL=postgresql://nordabiz_app:dev_password@localhost:5433/nordabiz
+
+# Google Gemini API (required for AI chat)
+GOOGLE_GEMINI_API_KEY=your_gemini_api_key_here
+
+# Google PageSpeed Insights API (optional, for SEO audits)
+GOOGLE_PAGESPEED_API_KEY=your_pagespeed_api_key_here
+
+# Google Places API (optional, for GBP audits)
+GOOGLE_PLACES_API_KEY=your_places_api_key_here
+
+# Email Configuration (optional, for user verification)
+MAIL_SERVER=smtp.gmail.com
+MAIL_PORT=587
+MAIL_USE_TLS=True
+MAIL_USERNAME=your_email@gmail.com
+MAIL_PASSWORD=your_app_password_here
+MAIL_DEFAULT_SENDER=noreply@norda-biznes.info
+
+# Application URLs
+APP_URL=http://localhost:5000
+VERIFY_EMAIL_URL=http://localhost:5000/verify-email
+```
+
+**Getting API Keys:**
+- **Gemini API**: https://ai.google.dev/ (free tier: 200 requests/day)
+- **PageSpeed Insights**: https://developers.google.com/speed/docs/insights/v5/get-started (free tier: 25,000 requests/day)
+- **Google Places**: https://console.cloud.google.com/apis/credentials (free tier: $200/month credit)
+
+#### 7. Run the Application
+
+```bash
+# Ensure virtual environment is activated
+source venv/bin/activate  # or venv\Scripts\activate on Windows
+
+# Run Flask development server
+python3 app.py
+```
+
+The application will start on `http://localhost:5000`
+
+**Default ports:**
+- Flask app: `5000` (or `5001` if 5000 is occupied)
+- PostgreSQL (Docker): `5433` (mapped from container's 5432)
+
+#### 8. Verify Installation
+
+Open your browser and navigate to:
+- **Main app**: http://localhost:5000
+- **Health check**: http://localhost:5000/health
+- **API test**: http://localhost:5000/api/companies
+
+### Development Workflow
+
+```bash
+# Start PostgreSQL (if using Docker)
+docker compose up -d
+
+# Activate virtual environment
+source venv/bin/activate
+
+# Run application
+python3 app.py
+
+# In another terminal: Run tests
+python -m pytest tests/
+
+# Stop PostgreSQL when done
+docker compose down
+```
+
+### Troubleshooting
+
+**Database Connection Issues:**
+```bash
+# Check PostgreSQL is running (Docker)
+docker ps | grep nordabiz-postgres
+
+# Check PostgreSQL logs
+docker logs nordabiz-postgres
+
+# Restart PostgreSQL container
+docker compose restart
+```
+
+**Port Already in Use:**
+```bash
+# Change PORT in .env file
+PORT=5001
+
+# Or stop conflicting service
+lsof -ti:5000 | xargs kill -9
+```
+
+**Missing Dependencies:**
+```bash
+# Reinstall all dependencies
+pip install -r requirements.txt --force-reinstall
+```
+
+**Database Schema Issues:**
+```bash
+# Reset database (Docker)
+docker compose down -v  # WARNING: Deletes all data!
+docker compose up -d
+docker exec -i nordabiz-postgres psql -U nordabiz_app -d nordabiz < database/schema.sql
+```
+
+For more detailed database setup and management, see `database/README.md`.
 
 ## Planowane rozszerzenia