# Astrology Project - Complete Setup Guide

Step-by-step guide to set up the Astrology & Synastry Compatibility project locally or on a server.

---

## 📋 Table of Contents

1. [System Requirements](#system-requirements)
2. [Project Structure](#project-structure)
3. [Backend Setup](#backend-setup)
4. [Frontend Setup](#frontend-setup)
5. [Run the Project](#run-the-project)
6. [Verify Installation](#verify-installation)
7. [Troubleshooting](#troubleshooting)

---

## ✅ System Requirements

### Minimum Requirements
- **OS**: Linux, macOS, or Windows (with WSL)
- **RAM**: 2GB minimum, 4GB recommended
- **Storage**: 2GB for dependencies and ephemeris data
- **Disk Speed**: SSD recommended for better performance

### Software Prerequisites

#### **Python 3.10+**
```bash
# Check Python version
python --version  # Should be 3.10.x or higher

# Install Python 3.10 (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install python3.10 python3.10-venv python3-pip
```

#### **Node.js 16+**
```bash
# Check Node version
node --version  # Should be 16.x or higher
npm --version   # Should be 8.x or higher

# Install Node.js (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
```


#### **Git** (for cloning repository)
```bash
# Install Git
sudo apt-get install git

# Verify
git --version
```

---

## 📁 Project Structure

```
astrology-project-birthdate-chart/
├── frontend/                          # React + Vite frontend
│   ├── src/
│   │   ├── pages/                    # Page components
│   │   ├── components/               # Reusable components
│   │   ├── css/                      # Stylesheets
│   │   ├── data/                     # Static data
│   │   ├── utils/                    # Helper functions
│   │   ├── App.jsx
│   │   ├── Layout.jsx
│   │   └── main.jsx
│   ├── public/                       # Static assets
│   ├── package.json
│   ├── vite.config.js
│   └── README.md
│
├── backend/                           # FastAPI backend
│   ├── main.py                        # FastAPI app entry point
│   ├── astrology.py                   # Astrology calculations
│   ├── database.py                    # Database setup
│   ├── models.py                      # Database models
│   ├── schemas.py                     # Pydantic schemas
│   ├── .env                           # Environment variables (REQUIRED)
│   ├── charts/                        # Generated SVG charts
│   │   ├── birthchart/
│   │   ├── synastry-chart/
│   │   ├── solar-return/
│   │   ├── lunar-return/
│   │   └── ...
│   ├── ephe/                          # Ephemeris data files
│   │   ├── sepl_18.se1
│   │   ├── semo_18.se1
│   │   ├── seas_18.se1
│   │   └── sefstars.txt
│   ├── services/                      # Service modules
│   └── venv/                          # Python virtual environment
│
├── venv/                              # Main Python virtual environment
├── cache/                             # Cached data
├── backup/                            # Backup files
├── Astrology.md                       # Project overview
├── Configuration.md                   # Configuration guide
├── frontend-backend.md                # Frontend/Backend reference
├── README.md                          # Main project README
├── Tech_stack.txt                     # Technology stack
└── SETUP.md                           # This file

```

---

## 🔧 Backend Setup

### Step 1: Navigate to Project Root

```bash
cd /path/to/astrology-project-birthdate-chart
```

### Step 2: Create Python Virtual Environment

```bash
# Create virtual environment
python3.10 -m venv venv

# Activate virtual environment
# On Linux/macOS:
source venv/bin/activate

# On Windows (PowerShell):
.\venv\Scripts\Activate.ps1

# On Windows (Command Prompt):
venv\Scripts\activate.bat
```

You should see `(venv)` prefix in your terminal.

### Step 3: Upgrade pip and Install Dependencies

```bash
# Upgrade pip
pip install --upgrade pip

# Install backend dependencies
pip install \
  fastapi==0.135.3 \
  uvicorn==0.44.0 \
  pydantic==2.12.5 \
  python-dotenv==1.2.2 \
  pyswisseph==2.10.3.2 \
  kerykeion==5.12.7 \
  bcrypt==5.0.0 \
  requests==2.33.1 \
  pytz==2026.1.post1 \
  passlib==1.7.4 \
  python-jose==3.5.0
```

Or use requirements file (if available):
```bash
pip install -r requirements.txt
```

### Step 4: Create Backend Configuration File

```bash
# Navigate to backend
cd backend

# Create .env file
cat > .env << EOF
# Frontend URL for CORS
FRONTEND_URL=http://172.16.16.148:5173

# Backend URL
BACKEND_URL=http://172.16.16.148:8000

DB_HOST=localhost
DB_PORT=3306
DB_NAME=Astrology
DB_USER=root
DB_PASSWORD=Test@123

JWT_SECRET_KEY=my_super_secret_key_123
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=1440


EOF
```

**Edit the .env file** with your actual configuration:
```bash
nano .env
# or
vim .env
```
### Step 5: downlode the MySQL -connecter 
cd /var/www/html/your-project/backend
source venv/bin/activate

pip install mysql-connector-python python-dotenv

### Step 6: Verify Ephemeris Files

Check that ephemeris data files exist in `backend/ephe/`:

```bash
# From project root
ls -la backend/ephe/

# Should show:
# - sepl_18.se1
# - semo_18.se1
# - seas_18.se1
# - sefstars.txt
```

If files are missing, the project will not work. These files come with the project.

### Step 7: Verify Chart Directories

```bash
# Create chart directories if they don't exist
mkdir -p backend/charts/birthchart
mkdir -p backend/charts/synastry-chart
mkdir -p backend/charts/composite-chart
mkdir -p backend/charts/solar-return
mkdir -p backend/charts/lunar-return
mkdir -p backend/charts/saturn_return
mkdir -p backend/charts/progressed
mkdir -p backend/charts/progressedchart
mkdir -p backend/charts/transit

# Verify permissions (should be writable)
chmod 755 backend/charts/*
```

---

## 📦 Frontend Setup

### Step 1: Navigate to Frontend Directory

```bash
# From project root
cd frontend
```

### Step 2: Install Dependencies

```bash
# Install Node modules
npm install

# This installs:
# - React 19.2.5
# - Vite 8.0.10
# - React Router DOM 7.14.2
# - Axios 1.15.2
# - Framer Motion 12.38.0
# - And other dependencies listed in package.json
```

### Step 3: Configure Frontend (Optional)

If using a different backend URL, update API calls in frontend:

```bash
# Common files to check/update:
# - src/utils/ (API URL constants)
# - src/services/ (API service files)
```

Look for hardcoded URLs like `http://172.16.16.148:8000` and update as needed.

---

## 💾 Database Setup

### Step 1: Create MySQL Database

```bash
# Login to MySQL
mysql -u root -p

# Enter password: (default: Test@123 or your password)
```


## 🚀 Run the Project

### Terminal 1: Start Backend

```bash
# From project root
source venv/bin/activate
cd backend
python main.py

# Expected output:
# Uvicorn running on http://0.0.0.0:8000
# Press CTRL+C to quit
```

Or with explicit Uvicorn command:
```bash
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

### Terminal 2: Start Frontend

```bash
# From project root (new terminal)
cd frontend
npm run dev

# Expected output:
# VITE v8.0.10  ready in XXX ms
# ➜  Local:   http://localhost:5173/
# ➜  press h to show help
```

### Access the Application

- **Frontend**: http://localhost:5173 or http://172.16.16.148:5173
- **Backend API**: http://localhost:8000
- **API Docs**: http://localhost:8000/docs (Swagger UI)

---

## ✅ Verify Installation

### Backend Health Check

```bash
# Check if backend is running
curl http://localhost:8000/

# Expected response: {"message": "API health check successful"}
```

### Frontend Health Check

Open browser and visit: `http://localhost:5173`

Should see the astrology application homepage.

### API Documentation

Visit: `http://localhost:8000/docs`

Should see interactive Swagger API documentation.

### Test Birth Chart Calculation

```bash
# Using curl or Postman
curl -X POST http://localhost:8000/chart-data \
  -H "Content-Type: application/json" \
  -d '{
    "year": 1990,
    "month": 3,
    "day": 15,
    "hour": 14,
    "minute": 30,
    "second": 0,
    "latitude": 28.7041,
    "longitude": 77.1025,
    "timezone": 5.5
  }'

# Expected response: Planet positions and moon phase data
```

---

## 🐛 Troubleshooting

### Backend Won't Start

**Error**: `FRONTEND_URL is missing in backend .env`
```bash
# Solution: Add FRONTEND_URL to backend/.env
echo "FRONTEND_URL=http://localhost:5173" >> backend/.env
```

**Error**: `Port 8000 already in use`
```bash
# Solution: Kill process on port 8000
lsof -i :8000
kill -9 <PID>

# Or use different port
uvicorn main:app --port 8001
```

**Error**: `ModuleNotFoundError: No module named 'kerykeion'`
```bash
# Solution: Reinstall dependencies
cd /var/www/html/Astrologybackend/backend
source venv/bin/activate

pip install git+https://github.com/g-battaglia/kerykeion.git
```

### Frontend Won't Start

**Error**: `npm: command not found`
```bash
# Solution: Install Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install nodejs
```

**Error**: `Cannot find module 'react'`
```bash
# Solution: Reinstall dependencies
rm -rf node_modules package-lock.json
npm install
```


### CORS Errors in Frontend

**Error**: `Access to XMLHttpRequest blocked by CORS policy`
```bash
# Solution: Update FRONTEND_URL in backend/.env
# Make sure it matches exactly (including port)
FRONTEND_URL=http://172.16.16.148:5173
# Then restart backend
```

### Charts Not Generating

**Error**: `FileNotFoundError: Kerykeion SVG chart was not generated`
```bash
# Solution: Check ephemeris files
ls -la backend/ephe/
# If missing, download from kerykeion repository

# Ensure charts directory is writable
chmod 755 backend/charts
```

**Error**: `Permission denied: 'backend/charts'`
```bash
# Solution: Fix directory permissions
sudo chown -R $USER:$USER backend/charts
chmod -R 755 backend/charts
```

### Virtual Environment Issues

**Error**: `No module named 'venv'`
```bash
# Solution: Install venv
sudo apt-get install python3.10-venv
```

**Error**: `(venv) not showing in terminal`
```bash
# Solution: Re-activate virtual environment
source venv/bin/activate
```

---

## 🔍 Verification Checklist

Before considering setup complete, verify:

- [ ] Python 3.10+ installed: `python --version`
- [ ] Node.js 16+ installed: `node --version`
- [ ] MySQL running: `sudo systemctl status mysql`
- [ ] Virtual environment created and activated: `(venv)` showing in terminal
- [ ] Backend dependencies installed: `pip list | grep fastapi`
- [ ] Frontend dependencies installed: `npm ls react`
- [ ] `backend/.env` file created with FRONTEND_URL
- [ ] Ephemeris files exist: `ls backend/ephe/`
- [ ] Chart directories created: `ls backend/charts/`
- [ ] Backend starts without errors: `python main.py`
- [ ] Frontend starts without errors: `npm run dev`
- [ ] Backend API accessible: `curl http://172.16.16.148:8000`
- [ ] Frontend accessible: `http://172.16.16.148:5173`

---

## 📊 Quick Start Summary

```bash
# 1. Clone/Navigate to project
cd /path/to/astrology-project-birthdate-chart

# 2. Setup Backend
python3.10 -m venv venv
source venv/bin/activate
pip install -r requirements.txt  # or manually install packages
cd backend
# Create .env file with FRONTEND_URL and DB credentials
python main.py

# 3. Setup Frontend (new terminal)
cd frontend
npm install
npm run dev








---

## 🌐 Production Deployment

For production setup, refer to:
- [Configuration.md](Configuration.md#-deployment-configuration)
- [Astrology.md](Astrology.md#🌐-deployment-configuration)

Key production steps:
1. Use strong passwords in `.env`
2. Configure real MySQL database (not SQLite)
3. Set up HTTPS/SSL certificates
4. Use production ASGI server (Gunicorn)
5. Use Nginx as reverse proxy
6. Configure firewall rules
7. Set up monitoring and logging
8. Enable rate limiting

---

## 📚 Additional Resources

- **Project Overview**: [Astrology.md](Astrology.md)
- **Configuration Guide**: [Configuration.md](Configuration.md)
- **Frontend/Backend Ref**: [frontend-backend.md](frontend-backend.md)
- **FastAPI Docs**: https://fastapi.tiangolo.com/
- **Kerykeion Docs**: https://github.com/g-battaglia/Kerykeion
- **React Docs**: https://react.dev/
- **Vite Docs**: https://vitejs.dev/

---

## 💬 Support

If you encounter issues:

1. Check the [Troubleshooting](#troubleshooting) section
2. Review logs: `backend/` terminal output or browser console
3. Verify all prerequisites are installed
4. Check .env file configuration
5. Ensure database is running and accessible

---

**Setup Guide Version**: 1.0  
**Last Updated**: May 25, 2026  
**Tested On**: Python 3.10.12, Node.js 18+, MySQL 8.0+