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

    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 Platform

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

# 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

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

    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

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

# 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