Deploy Expedientes Docentes with Docker or bare metal

The system can be deployed in two ways: Docker Compose (recommended for production and staging) or bare-metal Python (recommended for development or environments where Docker is unavailable). Both modes expose the FastAPI application on port 8000.

Docker Compose
Bare Metal

Docker Compose deployment

Docker Compose is the recommended production deployment method. The provided docker-compose.yml runs a single container (agente-expedientes) and connects to MongoDB and Ollama running directly on the host — they are intentionally kept outside the container network for simpler data management and persistence.

Prerequisites

Docker Engine 24+ and Docker Compose v2
MongoDB 6+ running on the host at port 27017
An active internet connection (for pulling the base image and OpenRouter calls), or Ollama running on the host at port 11434 for local LLM inference

Ghostscript (used for PDF compression by StorageAgent) is included in the Docker image — you do not need to install it on the host for Docker deployments.

docker-compose.yml overview

services:
  agente-expedientes:
    build: .
    image: agente-expedientes:latest
    container_name: agente-expedientes
    restart: unless-stopped
    ports:
      - "8000:8000"
    env_file:
      - .env
    environment:
      MONGO_URI: mongodb://host.docker.internal:27017
      OLLAMA_HOST: http://host.docker.internal:11434
      OLLAMA_MODEL: gemma4:e4b
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
    extra_hosts:
      - "host.docker.internal:host-gateway"

Key points:

env_file: .env loads your full configuration. The environment block then overrides MONGO_URI to mongodb://host.docker.internal:27017 — no manual adjustment to MONGO_URI is needed for single-server deployments.
OLLAMA_HOST in the environment block is present for reference but is not read by the application code — OllamaProvider reads OLLAMA_BASE_URL from src/config.py. If using Ollama, set OLLAMA_BASE_URL=http://host.docker.internal:11434 in your .env file directly, or update it at runtime via PUT /config/llm.
extra_hosts: host.docker.internal:host-gateway makes the host machine reachable from inside the container at host.docker.internal on both Linux and macOS/Windows.
Volumes ./data and ./logs are bind-mounted so document files and logs persist outside the container lifecycle.
restart: unless-stopped ensures the service restarts automatically after host reboots.

Deploy steps

Clone the repository

git clone https://github.com/gcapella0/agente-inteligente-expedientes.git
cd agente-inteligente-expedientes

Configure environment variables

cp .env.example .env

Open .env and set at minimum:

JWT_SECRET_KEY — change from the default placeholder
MAIL_USER and MAIL_PASS — your IMAP credentials
OPENROUTER_API_KEY — if using OpenRouter, or set LLM_PROVIDER=ollama for local inference

See the Environment Variables reference for the full list.

Create data and log directories

mkdir -p data/input data/storage logs

These will be bind-mounted into the container. The Dockerfile also creates them inside the image as a fallback.

Build the image

docker compose build

The build installs system dependencies (Ghostscript, libgl1, etc.) and then pip install -r requirements.txt. Subsequent builds are fast thanks to Docker layer caching.

Start the service

docker compose up -d

The container starts uvicorn src.api.main:app --host 0.0.0.0 --port 8000 --workers 2.

Operations commands

# Stream live logs
docker compose logs -f

# Restart the service (e.g., after editing .env)
docker compose restart

# Stop the service
docker compose down

# Update to latest code
git pull && docker compose build && docker compose up -d

Bare-metal Python deployment

Run the application directly with uvicorn — useful for development, debugging, or environments where Docker is not available.

Prerequisites

Python 3.12+
MongoDB 6+ running locally or accessible over the network

Ghostscript — required by StorageAgent for PDF compression:

# Debian / Ubuntu
sudo apt install ghostscript

# macOS
brew install ghostscript

Ollama (optional) — only if LLM_PROVIDER=ollama

Setup and run

Create a virtual environment

python3.12 -m venv venv
source venv/bin/activate      # Windows: venv\Scripts\activate

Install dependencies

pip install -r requirements.txt

python-doctr[torch] (~500 MB) downloads the OCR model weights on first run, not at install time.

Configure environment variables

cp .env.example .env
# Edit .env with your real values

Start the API server

Development (with auto-reload on code changes):

uvicorn src.api.main:app --host 0.0.0.0 --port 8000 --reload

Production (stable, no reload overhead):

uvicorn src.api.main:app --host 0.0.0.0 --port 8000 --workers 1

Use --workers 1 in production. The OCR model (docTR) holds large in-memory state; multiple workers would each load their own copy and may exhaust RAM.

Verification

After starting the service by either method, confirm it is healthy:

curl http://localhost:8000/health

Expected response:

{ "status": "ok" }

Additional endpoints to verify:

URL	Description
`http://localhost:8000/ui`	Web UI — login with `admin@uneg.edu.ve` / `admin123`
`http://localhost:8000/docs`	Interactive Swagger / OpenAPI documentation
`GET http://localhost:8000/info`	Returns API version, total endpoint count, and enabled capabilities

The first login credentials are admin@uneg.edu.ve / admin123. Change the password immediately after verifying the service is running (see security checklist below).

Security checklist

Before exposing the service to any network beyond localhost, complete the following:

The defaults shipped in .env.example and the codebase are intentionally weak placeholders. They must be changed before production use.

Change JWT_SECRET_KEY — replace the default cambiar-en-produccion-clave-larga-y-compleja with a cryptographically random value:
```
python -c "import secrets; print(secrets.token_hex(48))"
```
Change the admin password — the default admin123 is hardcoded as the first-run seed. Log in to the web UI at /ui or call POST /auth/change-password to update it immediately.
Restrict CORS origins — src/api/main.py currently allows http://localhost:3000 and http://localhost:8080 as CORS origins. For production, update the allow_origins list to your actual frontend domain(s) only.
Use HTTPS — place the service behind a reverse proxy (nginx or Caddy) that terminates TLS. Never expose port 8000 directly to the internet over plain HTTP.
Protect MongoDB — enable MongoDB authentication and use credentials in MONGO_URI (e.g., mongodb://user:password@host:27017/expedientes_uneg). Ensure MongoDB is not exposed on a public interface.

Introducción

Arquitectura

Configuración

Interfaz Web

Docker Compose deployment

Prerequisites

docker-compose.yml overview

Deploy steps

Operations commands

Bare-metal Python deployment

Prerequisites

Setup and run

Verification

Security checklist

Build docs developers (and LLMs) love

Introducción

Arquitectura

Configuración

Interfaz Web

Documentation Index

​Docker Compose deployment

​Prerequisites

​docker-compose.yml overview

​Deploy steps

​Operations commands

​Bare-metal Python deployment

​Prerequisites

​Setup and run

​Verification

​Security checklist

Build docs developers (and LLMs) love

Docker Compose deployment

Prerequisites

docker-compose.yml overview

Deploy steps

Operations commands

Bare-metal Python deployment

Prerequisites

Setup and run

Verification

Security checklist