NexuX AI - True Source

FastAPI + PostgreSQL + Alembic

This project is a FastAPI application that uses PostgreSQL as the database and Alembic for schema migrations. It also includes a Docker configuration that lets you easily run your application in a container—using separate environment files for development and production.

---

📌 Setup Instructions

1️⃣ Install Dependencies

Ensure you have Python 3.9+ installed, then install dependencies:

pip install -r requirements.txt

2️⃣ Create a Virtual Environment (Recommended)

python -m venv .venv
source .venv/bin/activate  # On macOS/Linux
.venv\Scripts\activate    # On Windows

---

📌 PostgreSQL Database Setup

1️⃣ Start PostgreSQL Server (If not already running)

brew services start postgresql@14  # For macOS (Homebrew)

2️⃣ Connect to PostgreSQL

psql -U postgres

3️⃣ Create a Database & Schema

CREATE DATABASE nexux_db;
CREATE SCHEMA master_data AUTHORIZATION confidential_db_user;

4️⃣ Create Database User & Grant Access

CREATE USER confidential_db_user WITH PASSWORD 'password';
GRANT ALL PRIVILEGES ON DATABASE nexux_db TO confidential_db_user;
GRANT USAGE, CREATE ON SCHEMA master_data TO confidential_db_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA master_data
GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO confidential_db_user;

5️⃣ Verify Connection

psql -U confidential_db_user -d nexux_db -h localhost -c "\dn"   # List schemas
psql -U confidential_db_user -d nexux_db -h localhost -c "\dt master_data.*"   # List tables

---

📌 Running the FastAPI Application

1️⃣ Start FastAPI Server

uvicorn true_app.main:app --host 0.0.0.0 --port 8000 --reload

2️⃣ Access API Documentation

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

---

📌 Alembic: Database Migrations

Alembic is used to manage database schema changes.

1️⃣ Initialize Alembic (Run only once)

alembic init alembic

2️⃣ Configure Alembic to Detect Models

Edit alembic/env.py and ensure the following imports exist:

from true_app.database import SQLALCHEMY_DATABASE_URL, Base
from true_app.models import Role, Category, Component, Country, Document, Tenant
from true_app.models.associations import category_document, component_category

Set the correct metadata:

target_metadata = Base.metadata

3️⃣ Generate a Migration File

alembic revision --autogenerate -m "Added master_data schema"

4️⃣ Apply Migrations to Database

alembic upgrade head

5️⃣ View Migration History

alembic history

6️⃣ Undo Last Migration

alembic downgrade -1

7️⃣ Reset Alembic Version (If Needed)

Check the current applied migration:

psql -U confidential_db_user -d nexux_db -h localhost -c "SELECT * FROM alembic_version;"

Reset Alembic version (if a migration file was manually deleted):

DELETE FROM alembic_version;
INSERT INTO alembic_version (version_num) VALUES ('latest_revision_hash');

Find latest_revision_hash using:

alembic history

---

📌 Debugging Issues

🔹 Check if Alembic is Detecting Models

alembic check

🔹 Check for Tables in Database

psql -U confidential_db_user -d nexux_db -h localhost -c "\dt master_data.*"

🔹 Force Reapply Migrations

alembic downgrade base
alembic upgrade head

🔹 Check if PostgreSQL is Running

brew services list  # For macOS
systemctl status postgresql  # For Linux

---

📌 Docker & Deployment Setup

This project includes a Docker configuration that allows you to run your FastAPI application in a container. It also supports switching between development and production environment configurations.

Dockerfile

Your Dockerfile is configured to:

• Install dependencies (including system packages)
• Copy your application code and environment files
• Run an entrypoint script that applies Alembic migrations before starting the server

Example Dockerfile snippet:

FROM python:3.9-slim

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

RUN apt-get update \
    && apt-get install -y gcc libpq-dev netcat-openbsd \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

COPY requirements.txt .
RUN pip install --upgrade pip && pip install -r requirements.txt

COPY . .

COPY ./entrypoint.sh /app/entrypoint.sh
RUN chmod +x /app/entrypoint.sh

EXPOSE 8000

ENTRYPOINT ["/app/entrypoint.sh"]
CMD ["uvicorn", "true_app.main:app", "--host", "0.0.0.0", "--port", "8000"]

entrypoint.sh

Your entrypoint script applies Alembic migrations before launching the server:

#!/bin/sh

echo "Running Alembic migrations..."
alembic upgrade head

exec "$@"

Docker Compose Configuration

Your docker-compose.yml for development might look like this:

version: '3.9'

services:
  app:
    build: .
    ports:
      - "8000:8000"
    environment:
      # Use the development environment file
      ENV_FILE: ".env"
    extra_hosts:
      - "host.docker.internal:host-gateway"

Note:
The extra_hosts mapping is used so that the container can resolve host.docker.internal (which points to your host machine) when running on Linux.
In production, you typically point your DATABASE_URL and DATABASE_HOST to your cloud database host (using an .env.production file), and the extra hosts mapping is not required.

Environment Files

Your environment files control database connection settings:

• .env (Development)

  DATABASE_URL=postgresql://confidential_db_user:password@host.docker.internal:5432/nexux_db
  DATABASE_HOST=host.docker.internal
  PROJECT_NAME=true-source

• .env.production (Production)

  DATABASE_URL=postgresql://confidential_db_user:ProdPassword@your-cloud-db-host:5432/nexux_db
  DATABASE_HOST=your-cloud-db-host
  PROJECT_NAME=true-source

You can select which file to use by setting the ENV_FILE environment variable (as done in your docker-compose). For production deployments, ensure your orchestration system injects the proper environment variables or loads the correct .env.production file.

Running with Docker

1. Build and Start Containers (Development):

   docker-compose up --build

2. Access the API Documentation:
   • Swagger UI: http://localhost:8000/docs
   • ReDoc: http://localhost:8000/redoc

---

📌 Deployment Notes

• Ensure DATABASE_URL is correct in production.
  Adjust your .env.production or environment variables accordingly.
• Run migrations before deployment:

  alembic upgrade head

• For production, consider using Gunicorn:

  gunicorn -k uvicorn.workers.UvicornWorker true_app.main:app --bind 0.0.0.0:8000

---

📌 Summary of Commands

Command	Description
uvicorn true_app.main:app --reload	Start FastAPI server (development)
alembic revision --autogenerate -m "message"	Create a new migration
alembic upgrade head	Apply migrations
alembic downgrade -1	Undo last migration
psql -U confidential_db_user -d nexux_db -h localhost -c "\dt master_data.*"	Check tables
brew services start postgresql@14	Start PostgreSQL

---