Documentation /Develop

Self-Hosted Deployment

This is the canonical deployment guide for local or privately operated NosoGraph instances. A public hosted demo is not deployed. GitHub Pages is documentation only. For first-time local setup, use Installation; for API routes, use the API reference.

This platform is research software. It is not HIPAA/GDPR/FDA certified by this repository.

Security assumptions (self-host)

These are practical defaults, not a compliance program:

Control	Default	Intent
DEBUG=false	Requires API_KEY	Fail-fast outside local debug
Dashboard CSP	DASHBOARD_CSP_MODE=enforce	Dashboard + satellite HTML. Allows 'self' plus cdnjs for 3Dmol/Cytoscape. Pipeline HTML reports may still load Google Fonts and are not covered by this document CSP.
Rate limit	60 req / 60s / IP	Redis when reachable; in-memory fallback if Redis is down. RATE_LIMIT_FAIL_CLOSED=false is intentional so a Redis outage does not make the app unusable. Set true only if you would rather 429 than fail open.
GET APIs	Public except PROTECTED_PREFIXES	When API_KEY is set, mutations and /api/jobs, /api/llm/extract, /api/evidence/gather, /api/system/cache require the key. Other GETs stay public by design for local research. Do not assume this is safe on the public internet.
DEMO_MODE	false	Opt-in read-only guard. Not a hosted demo.
Researcher auth	AUTH_MODE=local	Cookie sessions or trusted proxy. Not SSO. DEBUG uses a weak session fallback — do not expose DEBUG.
Redis in Compose	published 6379:6379	Bind to localhost in production; do not expose Redis to the internet.

No new authentication system is introduced. This is not a multi-tenant SaaS.

Prerequisites

• Docker and Docker Compose v2
• At least 4 GB RAM (more for full disease validation builds)
• Optional: Redis reachable at CELERY_BROKER_URL when not using Compose

Quick start

1. Clone the repository and copy the environment template:

git clone https://github.com/AdamEddahmouni/nosograph.git
cd nosograph
cp .env.example .env

1. Edit .env for your environment. For local development, defaults are sufficient (DEBUG=true, empty API_KEY).

2. Start the stack:

docker compose --profile full up --build

1. Open the dashboard at http://localhost:8000.

Read-only demo profile (local)

Fixture-backed snapshot + DEMO_MODE=true. This does not publish a hosted demo.

docker compose --profile demo run --rm pipeline demo build
docker compose --profile demo up web-demo --build

See Demo. Operator notes live in the repository at docs/deployment/local-demo-operator.md (excluded from GitHub Pages).

Environment variables

Variable	Local default	Production recommendation
DEBUG	true	false
API_KEY	empty	Strong random secret (required when DEBUG=false)
AUTH_SESSION_SECRET	empty	Random secret for workspace sessions
CORS_ORIGINS	localhost origins	Your front-end origin(s) only
CELERY_BROKER_URL	redis://localhost:6379/0	Internal Redis URL
DASHBOARD_CSP / DASHBOARD_CSP_MODE	true / enforce	off only if you must disable document CSP
RATE_LIMIT_FAIL_CLOSED	false	true only if Redis outage should 429 instead of in-memory fallback
DEMO_MODE	false	true only for an intentional read-only instance
OPENAPI_ENABLED	follows DEBUG	false to hide /api/docs
BIOMEDICAL_DB_PATH	<repo>/data/biomedical.sqlite3	Persistent volume path for the universal biomedical store

See .env.example for the full list. DEMO_MODE must stay false unless you are operating an intentional read-only instance. There is no hosted public app.

Authentication modes

The platform uses two complementary auth layers:

1. API key (X-API-Key header) — protects job submission, cache admin, and job status/WebSocket streams when API_KEY is set. WebSocket clients may pass ?api_key= as a query parameter.

2. Researcher sessions — Evidence Workspace routes require login via /api/auth/login (AUTH_MODE=local) or a trusted reverse proxy (AUTH_MODE=proxy).

Health checks

Endpoint	Purpose
GET /api/health	Liveness — process is running
GET /api/ready	Readiness — Redis, Celery, workspace DB, and KG preload

Docker Compose configures a healthcheck on the web service using /api/health.

Faster Docker builds

The Dockerfile runs disease validate --all --strict at image build time. With the full 10,000+ module registry this is slow and, because scaffolded modules report config gaps, strict mode exits non-zero. For iterative dev builds, skip validation:

docker compose build --build-arg DOCKER_SKIP_DISEASE_VALIDATE=1 web

Gate release builds on an individual curated module instead:

python -m med_research.cli disease validate sle --strict

GitHub Actions runs on push/PR when the repository is public (free hosted runners). Use make ci-local locally before pushing. The workflow does not run disease validate --all --strict (scaffolds fail that check by design).

Data persistence

Runtime data lives under ./data (mounted to /app/data in containers):

• evidence_workspace.sqlite3 — workspace run history
• biomedical.sqlite3 — universal biomedical store
• Pipeline caches and report outputs

Back up this directory before upgrades. It is listed in .gitignore and is not version-controlled.

Initialize and populate the universal biomedical store on first boot if /api/v1 condition features are needed:

python -m med_research.cli biomed init
python -m med_research.cli biomed import mondo --artifact /path/to/mondo.json
python -m med_research.cli biomed import hp --artifact /path/to/hp.json
python -m med_research.cli biomed import hpoa --artifact /path/to/phenotype.hpoa.tsv

For test/demo data, make biomed-import-fixtures loads the minimal checked-in fixture bundle; make biomed-verify validates checksums and active store snapshots.

Research-only policy

This platform is for public biomedical knowledge and computational research. Do not store or process patient-identifiable data (PHI). See SECURITY.md and data licensing.

Troubleshooting

Symptom	Likely cause	Fix
Web container exits on start	DEBUG=false without API_KEY	Set API_KEY or DEBUG=true in .env
Jobs stay PENDING	Worker not running	docker compose --profile full up worker
429 Too Many Requests	Rate limit hit	Raise RATE_LIMIT_REQUESTS or wait
/api/ready returns 503	Redis/Celery unreachable	Check redis service and broker URLs