Installation Guide

Set up your local development environment. Time: ~5 minutes.

Prerequisites

Tool	Version	Install
Docker Desktop	4.25+	docker.com
uv	latest	`curl -LsSf https://astral.sh/uv/install.sh \| sh`

⚠️ Python 3.12 required — uv will install it automatically.

Security

🔐 Credential Handling

Secrets via environment variables or secret manager only
Never commit .env files
No PII in model artifacts or logs

Step 1: Clone Repository

git clone https://github.com/hungryhub-team/hh-lion.git
cd hh-lion

Step 2: Configure Environment

cp .env.example .env

Step 3: Start Infrastructure

docker compose up -d

Verify:

docker compose ps

Expected: core containers running (redis, clickhouse, kafka, schema-registry, minio, mlflow, tei, opensearch)

Container	Port	URL	Purpose
`hh-lion-redis`	16379	-	Caching
`hh-lion-clickhouse`	19000 / 18123	localhost:18123/ping	Feature/event store
`hh-lion-kafka`	19092	-	Events
`hh-lion-schema-registry`	18081	localhost:18081	Schemas
`hh-lion-minio`	19100 / 19001	localhost:19001	Artifacts
`hh-lion-mlflow`	15000	localhost:15000	Tracking
`hh-lion-tei`	18080	localhost:18080/health	Text embeddings
`hh-lion-opensearch`	19200	localhost:19200	Search metadata

Step 4: Create Python Environment

# uv auto-detects Python 3.12 from .python-version
uv sync --all-extras

That’s it! No conda activate needed.

Step 5: Verify

uv run python -c "import recsys; print('✅ Ready!')"

CLI Commands

All operations use uv run prefix:

Command	Description
`uv run python -m scripts.compute_member_features --mode full --publish-online`	Publish member features to Feast v2
`uv run python -m scripts.compute_item_features --mode full --publish-online`	Publish item features to Feast v2
`uv run python -m scripts.compute_cohort_features --mode full --publish-online`	Publish cohort features to Feast v2
`TRAINING_DATA_SOURCE=clickhouse uv run python -m scripts.train --config homepage_personalization`	Train model from ClickHouse bookings
`uv run python -m scripts.evaluate --run_id <ID> --holdout_path <temporal_holdout.{csv,parquet}>`	Evaluate against a temporal holdout file
`uv run python -m scripts.register_model --run_id <ID> --name homepage_two_tower --stage Engineering`	Register homepage model and transition it to Engineering
`uv run python -m scripts.backfill_ann`	Backfill ANN index
`uv run pytest tests/`	Run tests

Environment Variables

Variable	Description	Default
`ENVIRONMENT`	Runtime mode (`development`, `engineering`, `production`)	`development`
`MLFLOW_MODEL_NAME`	Registered model name to load	(unset)
`MLFLOW_MODEL_ALIAS`	Registered model alias to load	(unset)
`FORCE_MOCK_MODEL`	Force mock serving mode (blocked in engineering/production)	`false`
`MLFLOW_TRACKING_URI`	MLflow URL	`http://localhost:15000`
`MLFLOW_S3_ENDPOINT_URL`	MinIO URL	`http://localhost:19100`
`AWS_ACCESS_KEY_ID`	MinIO key	`minioadmin`
`AWS_SECRET_ACCESS_KEY`	MinIO secret	`minioadmin`
`REDIS_HOST`	Redis hostname	`localhost`
`REDIS_PORT`	Redis port	`16379`
`REDIS_DB`	Redis database index	`0`
`REDIS_TLS`	Enable TLS for Redis connections	`false`
`CACHE_HMAC_SECRET`	Secret for refresh ownership HMAC validation	(empty)
`CORS_ALLOWED_ORIGINS`	Allowed CORS origins	`*`
`ANONYMOUS_ID_COOKIE_HTTPONLY`	Set `anonymous_id` cookie with `HttpOnly` (set `false` only if client-side JS must read it)	`true`
`GROWTHBOOK_API_HOST`	GrowthBook feature endpoint host	(empty)
`GROWTHBOOK_CLIENT_KEY`	GrowthBook SDK key	(empty)
`GROWTHBOOK_DEFAULT_HOMEPAGE_MODEL`	Fallback homepage model variant when GrowthBook is unavailable or the flag is missing (`control` or `member_two_tower`)	`control`
`TEI_API_URL`	TEI endpoint for embedding generation	`http://localhost:18080`
`TEI_TIMEOUT_SECONDS`	Embedding request timeout	`5.0`
`NAMESPACE`	Optional Kafka topic namespace prefix	(empty)
`KAFKA_BOOTSTRAP_SERVERS`	Kafka bootstrap servers for impression events	(unset)
`KAFKA_SECURITY_PROTOCOL`	Kafka broker security protocol	`plaintext`
`KAFKA_SCHEMA_REGISTRY_URL`	Schema Registry URL for Avro clients	`http://localhost:18081`
`KAFKA_IMPRESSION_TOPIC`	Base Kafka topic for impression events; prefixed by `NAMESPACE` when set	`hh.lion.recsys.impressions`

GPU / TorchRec (Optional)

For GPU development with TorchRec, Conda is still required:

conda env create -f envs/dev-x86-gpu.yml
conda activate hh-lion-dev-x86-gpu

See envs/README.md for details.

Troubleshooting

Issue	Solution
`ModuleNotFoundError: recsys`	`uv sync --all-extras`
Port in use	`lsof -i :<port>`
TorchRec not found (Mac)	Expected — TorchRec requires x86 + CUDA

→ Quickstart: Train your first model → Full Localhost Runbook (No Mock) → Operations Runbook Index → Release Readiness Checklist

HungryHub Knowledge Base