orion/docs/getting-started/installation.md

# Installation Guide

This guide will help you set up the Wizamart Platform for development or production use.

## Prerequisites

Before you begin, ensure you have the following installed:

- **Python 3.11 or higher**
- **Docker and Docker Compose** (required for database and Redis)
- **Git**
- **PostgreSQL client tools** (optional, for debugging)

!!! note "PostgreSQL Only"
    This project uses PostgreSQL exclusively. SQLite is not supported.
    Docker provides the easiest way to run PostgreSQL locally.

## Development Setup

### 1. Clone the Repository

```bash
    git clone <wizamart-repo>
    cd wizamart-repo
```

### 2. Create Virtual Environment

=== "Windows"
    ```bash
    python -m venv venv
    venv\Scripts\activate
    ```

=== "macOS/Linux"
    ```bash
    python -m venv venv
    source venv/bin/activate
    ```

### 3. Install Dependencies

```bash
# Install main application dependencies
pip install -r requirements.txt # or make install

# Install development dependencies
pip install -r requirements-dev.txt # or make install-dev

# Install test dependencies
pip install -r tests/requirements-test.txt # or make install-test

# Install documentation dependencies (optional)
pip install -r requirements-docs.txt # or make install-docs

# All dependencies can be installed with make install-all
```

### 4. Database Setup

#### Option A: Local PostgreSQL

1. **Create Database**:
   ```sql
   CREATE DATABASE wizamart_db;
   CREATE USER wizamart_user WITH PASSWORD 'your_password';
   GRANT ALL PRIVILEGES ON DATABASE wizamart_db TO wizamart_user;
   ```

2. **Create Environment File**:
   ```bash
   cp .env.example .env
   ```

3. **Configure `.env` file**:
   ```env
   # Database
   DATABASE_URL=postgresql://wizamart_user:your_password@localhost/wizamart
   
   # Security
   SECRET_KEY=your-super-secret-key-here
   JWT_SECRET_KEY=your-jwt-secret-key-here
   
   # Environment
   ENVIRONMENT=development
   DEBUG=True
   ```

#### Option B: Docker PostgreSQL

```bash
docker run --name wizamart-postgres \
  -e POSTGRES_DB=wizamart_import \
  -e POSTGRES_USER=wizamart_user \
  -e POSTGRES_PASSWORD=your_password \
  -p 5432:5432 \
  -d postgres:15
```

### 5. Initialize Platform

```bash
# Option A: Full installation wizard (recommended)
make platform-install

# Option B: Manual steps
make migrate-up      # Run database migrations
make init-prod       # Initialize admin, CMS, email templates
```

### 6. Start Background Task Queue (Optional)

For production or to test background tasks:

```bash
# Start Redis (required for Celery)
docker compose up -d redis

# Start Celery worker (in separate terminal)
make celery-worker

# Start Celery beat scheduler (in separate terminal, for scheduled tasks)
make celery-beat

# Or start both together for development
make celery-dev
```

!!! tip "Development without Celery"
    Set `USE_CELERY=false` in `.env` to use FastAPI BackgroundTasks instead.
    This is the default and doesn't require Redis.

### 7. Run the Application

```bash
# Start development server
make dev
```

The application will be available at:

- **API**: http://localhost:8000
- **Interactive API Docs**: http://localhost:8000/docs
- **Alternative API Docs**: http://localhost:8000/redoc
- **Admin Panel**: http://localhost:8000/admin
- **Flower** (if Celery enabled): http://localhost:5555

## Docker Setup

### Quick Start with Docker Compose

1. **Clone and navigate to project**:
   ```bash
    git clone <wizamart-repo>
    cd wizamart-repo
   ```

2. **Start all services**:
   ```bash
   docker-compose up -d
   ```

3. **Initialize database**:
   ```bash
   docker-compose exec api python -m alembic upgrade head
   ```

### Manual Docker Setup

1. **Build the image**:
   ```bash
   docker build -t letzshop-import .
   ```

2. **Run with environment variables**:
   ```bash
   docker run -d \
     --name wizamart-api \
     -p 8000:8000 \
     -e DATABASE_URL="postgresql://user:pass@host/db" \
     -e SECRET_KEY="your-secret-key" \
     wizamart-import
   ```

## Verification

### 1. Check Application Health

```bash
curl http://localhost:8000/health
```

Expected response:
```json
{
  "status": "healthy",
  "database": "connected",
  "version": "1.0.0"
}
```

### 2. Run Tests

```bash
# Run all tests
pytest

# Run specific test types
pytest -m unit
pytest -m integration
```

### 3. Access Documentation

- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc
- **This Documentation** (if running MkDocs): http://localhost:8001

## Environment Variables

### Core Settings

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `DATABASE_URL` | PostgreSQL connection string | - | ✅ |
| `JWT_SECRET_KEY` | JWT token secret | - | ✅ |
| `DEBUG` | Enable debug mode | `False` | ❌ |
| `LOG_LEVEL` | Logging level | `INFO` | ❌ |

### Celery / Redis

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `REDIS_URL` | Redis connection string | `redis://localhost:6379/0` | ❌ |
| `USE_CELERY` | Enable Celery task queue | `false` | ❌ |
| `FLOWER_URL` | Flower dashboard URL | `http://localhost:5555` | ❌ |
| `FLOWER_PASSWORD` | Flower authentication password | `changeme` | ❌ |

### Sentry Error Tracking

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `SENTRY_DSN` | Sentry DSN (leave empty to disable) | - | ❌ |
| `SENTRY_ENVIRONMENT` | Environment name | `development` | ❌ |
| `SENTRY_TRACES_SAMPLE_RATE` | Performance tracing rate (0.0-1.0) | `0.1` | ❌ |

### Cloudflare R2 Storage

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `STORAGE_BACKEND` | Storage backend (`local` or `r2`) | `local` | ❌ |
| `R2_ACCOUNT_ID` | Cloudflare account ID | - | ❌ (if r2) |
| `R2_ACCESS_KEY_ID` | R2 access key | - | ❌ (if r2) |
| `R2_SECRET_ACCESS_KEY` | R2 secret key | - | ❌ (if r2) |
| `R2_BUCKET_NAME` | R2 bucket name | `wizamart-media` | ❌ |
| `R2_PUBLIC_URL` | Custom public URL for R2 | - | ❌ |

### CloudFlare CDN

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `CLOUDFLARE_ENABLED` | Enable CloudFlare header handling | `false` | ❌ |

### Stripe Billing

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `STRIPE_SECRET_KEY` | Stripe secret key | - | ❌ |
| `STRIPE_PUBLISHABLE_KEY` | Stripe publishable key | - | ❌ |
| `STRIPE_WEBHOOK_SECRET` | Stripe webhook secret | - | ❌ |

## Troubleshooting

### Common Issues

#### Database Connection Issues
```bash
# Check if PostgreSQL is running
pg_isready -h localhost -p 5432

# Check database connectivity
python -c "from app.core.database import engine; engine.connect()"
```

#### Port Already in Use
```bash
# Find process using port 8000
lsof -i :8000

# Kill the process
kill -9 <PID>
```

#### Permission Issues
```bash
# Fix file permissions
chmod +x scripts/*.py

# Fix virtual environment permissions
chmod -R 755 venv/
```

### Getting Help

If you encounter issues:

1. Check the [Troubleshooting Guide](../development/troubleshooting.md)
2. Review application logs: `docker-compose logs api`
3. Open an [issue on GitHub](https://github.com/yourusername/letzshop-import/issues)

## Next Steps

- **[Quick Start Guide](quickstart.md)** - Get familiar with basic operations
- **[Configuration Guide](configuration.md)** - Detailed configuration options
- **[API Documentation](../api/index.md)** - Explore the API endpoints