Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jtapieromalambo-ctrl/Signia/llms.txt

Use this file to discover all available pages before exploring further.

This page covers a complete Signia installation from scratch, including system-level prerequisites, Python environment setup, environment variable configuration, database options, and static file collection. If you just want the fastest path to a running dev server, see the Quickstart. Come back here when you need to understand the full picture — for example, when setting up a production environment or troubleshooting a dependency issue.

​
Prerequisites

The table below lists everything that must be installed on your system before you begin. All Python packages are handled by requirements.txt; only the tools in this table need to be installed manually.
ToolMinimum versionNotes
Python3.11Exact minor version matters — MediaPipe and faster-whisper wheels target 3.11
pip23+Bundled with Python 3.11
GitAnyRequired to clone the repository
ffmpegAnyRequired by faster-whisper for audio decoding
Windows users: You do not need to install ffmpeg globally. The repository includes bundled ffmpeg binaries in the /ffmpeg/ directory. The traduccion module prepends that directory to PATH at runtime, so faster-whisper can locate ffmpeg automatically. Do not move or delete the /ffmpeg/ folder.
On Linux and macOS (and in production on Railway), ffmpeg must be installed at the system level. On Ubuntu/Debian: 
sudo apt-get install ffmpeg libgl1 libglib2.0-0
libgl1 and libglib2.0-0 are required by OpenCV and MediaPipe. Railway’s nixpacks.toml installs these automatically during the production build.

​
Virtual environment

Isolate Signia’s dependencies from your system Python by creating a virtual environment. The project conventionally names this environment ENT. 
python -m venv ENT
.\ENT\Scripts\Activate.ps1
If PowerShell blocks the activation script, run the following once and then retry:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
After activation, your prompt will show (ENT) at the start of each line.

​
Install Python dependencies

With the virtual environment active, install all packages from the lock file: 
pip install -r requirements.txt
The table below describes the most important packages. The full requirements.txt includes their transitive dependencies.
PackageVersionPurpose
Django5.2.12Core web framework
django-allauth65.15.0OAuth authentication (Google, Facebook)
faster-whisper1.2.1Speech-to-text transcription of audio input
mediapipe0.10.30Hand landmark extraction for webcam recognition
scikit-learn1.8.0RandomForest classifier for sign recognition
groq1.2.0API client for the LSC grammar LLM layer
psycopg2-binary2.9.11PostgreSQL database adapter
gunicorn25.3.0WSGI server for production
whitenoise6.12.0Static file serving in production
dj-database-url3.1.2Parses DATABASE_URL connection strings
python-decouple3.8Reads environment variables from .env
Installation can take several minutes on first run because packages like mediapipe, faster-whisper, and scikit-learn include large compiled binaries. A fast internet connection and pip’s wheel cache speed up subsequent installs significantly.

​
Environment variables

Create a .env file in the project root — the same directory as manage.py: 
Signia/
├── .env          ← here
├── manage.py
├── requirements.txt
└── ...

​
Development (SQLite)

For a local development setup, only two variables are strictly required to start the server: 
SECRET_KEY=your-secret-key-here
DEBUG=True
Generate a cryptographically strong SECRET_KEY: 
python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

​
Full variable reference

# ── Django ─────────────────────────────────────────────
SECRET_KEY=your-secret-key-here
DEBUG=True

# ── Database ────────────────────────────────────────────
# Omit for SQLite (auto-used in development).
# Required for production PostgreSQL:
DATABASE_URL=postgresql://user:password@host.neon.tech/signia?sslmode=require

# ── LSC grammar layer ───────────────────────────────────
GROQ_API_KEY=your-groq-api-key

# ── Email / OTP verification (Brevo) ───────────────────
BREVO_API_KEY=your-brevo-api-key
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-gmail-app-password

# ── OAuth (configure providers in Django Admin after migrate) ──
SITE_ID=1

# ── Production only ─────────────────────────────────────
# RAILWAY_PUBLIC_DOMAIN=your-app.up.railway.app

​
Database setup

Signia supports two database backends selected automatically based on whether DATABASE_URL is present in the environment.

​
SQLite (development — no configuration needed)

If DATABASE_URL is not set, Django uses an SQLite file at db.sqlite3 in the project root. This requires no external service and is the recommended choice for local development. 
python manage.py migrate

​
PostgreSQL with Neon (production)

For production, Signia is configured to connect to a Neon PostgreSQL instance. The connection string must include ?sslmode=require because the settings apply sslmode: require and DISABLE_SERVER_SIDE_CURSORS: True (required for Neon’s connection pooler).
  1. Create a free project at neon.tech.
  2. Copy the connection string from the Neon dashboard.
  3. Add it to your .env:
DATABASE_URL=postgresql://user:password@host.neon.tech/signia?sslmode=require
  1. Run migrations:
python manage.py migrate

​
Create a superuser

Regardless of the database backend, create a superuser to access the admin video panel at /admin-videos/: 
python manage.py createsuperuser
Superusers bypass the disability-selection routing after login and are sent directly to the admin panel.

​
Static files

​
Development

In development, Django serves static files automatically from the /static/ directory. No extra configuration is needed.

​
Production

In production, WhiteNoise serves all static files directly from the /staticfiles/ directory. Run the following command to collect static files before deploying: 
python manage.py collectstatic --no-input
This copies all static assets from /static/ and each app’s static/ directory into /staticfiles/.
Signia uses CompressedStaticFilesStorage instead of the more common ManifestStaticFilesStorage. This is intentional. Manifest mode appends a content hash to every filename (e.g., mediapipe.wasm becomes mediapipe.abc123.wasm). MediaPipe’s WASM loader looks for files by their original exact names and cannot follow renamed paths, which causes the webcam recognition feature to silently fail. CompressedStaticFilesStorage compresses files with gzip and Brotli but leaves filenames unchanged, keeping WASM loading intact.Additionally, .wasm and .task file extensions are added to WHITENOISE_SKIP_COMPRESS_EXTENSIONS to prevent WhiteNoise from compressing them — Chromium makes HTTP range requests to WASM files, and compressed responses break range request semantics.

​
Final check

Start the development server to verify everything is wired up correctly: 
python manage.py runserver
You should see: 
Django version 5.2.12, using settings 'Signia.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CTRL-BREAK.
Open http://127.0.0.1:8000 to confirm the home page loads. Log in with the superuser account you created and visit /admin-videos/ to verify admin access.
The webcam sign recognition module at /reconocimientos/camara/ will return a 503 error until reconocimientos/modelo/model_seq.pkl exists. This file is generated by training the RandomForest model. To train the model, log in as a superuser, upload sign videos with their correct labels from /admin-videos/, and click “Entrenar modelo”. Training runs in a background thread inside the Django process. Once complete, it saves model_seq.pkl and label_encoder.npy to reconocimientos/modelo/ and deletes all processed source videos from the database and disk.

Build docs developers (and LLMs) love

Get started for freeTalk to us