MkDocs documentation integration

docs/getting-started/installation.md

@@ -0,0 +1,242 @@
+# Installation Guide
+
+This guide will help you set up the Letzshop Import application for development or production use.
+
+## Prerequisites
+
+Before you begin, ensure you have the following installed:
+
+- **Python 3.10 or higher**
+- **PostgreSQL 12 or higher**
+- **Git**
+- **Docker** (optional, for containerized deployment)
+
+## Development Setup
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/yourusername/letzshop-import.git
+cd letzshop-import
+```
+
+### 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
+
+# Install development dependencies
+pip install -r requirements-dev.txt
+
+# Install test dependencies
+pip install -r tests/requirements-test.txt
+
+# Install documentation dependencies (optional)
+pip install -r requirements-docs.txt
+```
+
+### 4. Database Setup
+
+#### Option A: Local PostgreSQL
+
+1. **Create Database**:
+   ```sql
+   CREATE DATABASE letzshop_import;
+   CREATE USER letzshop_user WITH PASSWORD 'your_password';
+   GRANT ALL PRIVILEGES ON DATABASE letzshop_import TO letzshop_user;
+   ```
+
+2. **Create Environment File**:
+   ```bash
+   cp .env.example .env
+   ```
+
+3. **Configure `.env` file**:
+   ```env
+   # Database
+   DATABASE_URL=postgresql://letzshop_user:your_password@localhost/letzshop_import
+   
+   # 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 letzshop-postgres \
+  -e POSTGRES_DB=letzshop_import \
+  -e POSTGRES_USER=letzshop_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
+```
+
+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 https://github.com/yourusername/letzshop-import.git
+   cd letzshop-import
+   ```
+
+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 letzshop-api \
+     -p 8000:8000 \
+     -e DATABASE_URL="postgresql://user:pass@host/db" \
+     -e SECRET_KEY="your-secret-key" \
+     letzshop-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