orion/docs/getting-started/installation.md

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

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

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

   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:

   cp .env.example .env
   

3. Configure .env file:

   # 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

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

# 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

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 https://github.com/yourusername/letzshop-import.git
   cd letzshop-import
   

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

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