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.10 or higher**
- **Docker and Docker Compose** (required for database)
- **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 Database

```bash
# Run database migrations
python -m alembic upgrade head

# Create initial admin user (optional)
python scripts/create_admin.py
```

### 6. Run the Application

```bash
# Start development server
uvicorn main:app --reload --host 0.0.0.0 --port 8000 # or 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

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

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `DATABASE_URL` | PostgreSQL connection string | - | ✅ |
| `SECRET_KEY` | Application secret key | - | ✅ |
| `JWT_SECRET_KEY` | JWT token secret | - | ✅ |
| `ENVIRONMENT` | Environment (dev/staging/prod) | `development` | ❌ |
| `DEBUG` | Enable debug mode | `False` | ❌ |
| `LOG_LEVEL` | Logging level | `INFO` | ❌ |
| `CORS_ORIGINS` | Allowed CORS origins | `["*"]` | ❌ |

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