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

    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

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

   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:

   cp .env.example .env
   

3. Configure .env file:

   # 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

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

# Run database migrations
python -m alembic upgrade head

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

6. Run the Application

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

    git clone <wizamart-repo>
    cd wizamart-repo
   

2. Start all services:

   docker-compose up -d
   

3. Initialize database:

   docker-compose exec api python -m alembic upgrade head
   

Manual Docker Setup

1. Build the image:

   docker build -t letzshop-import .
   

2. Run with environment variables:

   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

curl http://localhost:8000/health

Expected response:

{
  "status": "healthy",
  "database": "connected",
  "version": "1.0.0"
}

2. Run Tests

# 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

# 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

# Find process using port 8000
lsof -i :8000

# Kill the process
kill -9 <PID>

Permission Issues

# 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
2. Review application logs: docker-compose logs api
3. Open an issue on GitHub

Next Steps

• Quick Start Guide - Get familiar with basic operations
• Configuration Guide - Detailed configuration options
• API Documentation - Explore the API endpoints