🧩 Installation

Whether you're running it locally as a Python dev or deploying in containers as an ops engineer—Locentra OS installs cleanly, boots fast, and stays under your control.

This guide covers both manual setup and Docker-based deployment.

---

🧪 System Requirements

Minimum:

• Python 3.10+

• Node.js 18+

• PostgreSQL 13+

• Docker & Docker Compose (for containerized setup)

Recommended:

• Unix-like system (Linux/macOS)

• 8GB+ RAM for live inference and training

• GPU (CUDA) if using large models locally

---

🧱 1. Clone the Repository

git clone https://github.com/Locentra/OS.git
cd OS

---

🐍 2. Manual Installation (Local Python Setup)

Ideal for devs who want to step through the system layer by layer.

🔹 Backend Setup

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

🔹 Environment Variables

Copy the default .env and adjust settings:

cp .env.example .env

Example config:

MODEL_NAME=tiiuae/falcon-rw-1b
DATABASE_URL=postgresql://user:pass@localhost:5432/Locentra
DEBUG=true

🔹 Frontend Setup

cd ../web
npm install

🔹 Start Services

• Backend:

  cd ../backend
  bash ../scripts/run_server.sh

• Frontend:

  cd ../web
  npm run dev

• Initialize Database:

  python ../database/db_init.py

---

🐳 3. Docker Deployment (Recommended)

Fastest way to run the full stack locally. Clean, reproducible, no system conflicts.

🔹 One-Liner Boot

cp .env.example .env
docker-compose up --build

🔹 Access Points

• 🌐 App: http://localhost

• 🧠 API: http://localhost:8000

• 💻 UI: http://localhost:3000

• 📘 Docs: http://localhost/api/docs

Logs are streamed to console by default. Extend docker-compose.yml to route logs or mount volumes as needed.

---

📁 4. Backend Structure Overview

Locentra-os/backend/
├── api/         # FastAPI routes (REST API layer)
├── core/        # Engine bootstrapping, registry, settings
├── models/      # Inference, model loader, fine-tuning, adapter
├── agents/      # AutoTrainer, FeedbackAgent (self-learning logic)
├── db/          # SQLAlchemy models, migrations, connectors
├── services/    # Logic layer: memory, analytics, user mgmt
├── data/        # Tokenizer, vector embedding, dataset prep
├── utils/       # Metrics, crypto helpers, evaluation

The backend is modular—every service, agent, or component can be extended or replaced.