Add HuggingFace Spaces deployment

- Dockerfile: single-container build (Kafka KRaft + Matcher + MD Feeder + Dashboard)
- entrypoint.sh: ordered startup – Kafka ready-check, topic creation, Python services
- kafka-kraft.properties: single-node KRaft config (no ZooKeeper)
- README.md: HF Space metadata + project overview
- dashboard.py: read PORT from env var (default 5000, HF uses 7860)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Dockerfile

@@ -0,0 +1,58 @@
+# HuggingFace Spaces – StockEx Trading Demo
+# Single container: Kafka (KRaft) + Matcher + MD Feeder + Dashboard
+
+FROM python:3.11-slim
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV PYTHONUNBUFFERED=1
+# Limit Kafka JVM heap to fit free-tier RAM
+ENV KAFKA_HEAP_OPTS="-Xmx400m -Xms256m"
+
+# Install Java (required by Kafka) + wget
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      default-jre-headless \
+      wget \
+    && rm -rf /var/lib/apt/lists/*
+
+# Download Apache Kafka 3.7.0 (KRaft mode – no ZooKeeper needed)
+ARG KAFKA_VERSION=3.7.0
+RUN wget -q \
+      "https://archive.apache.org/dist/kafka/${KAFKA_VERSION}/kafka_2.13-${KAFKA_VERSION}.tgz" \
+      -O /tmp/kafka.tgz \
+    && tar -xzf /tmp/kafka.tgz -C /opt \
+    && mv /opt/kafka_2.13-${KAFKA_VERSION} /opt/kafka \
+    && rm /tmp/kafka.tgz
+
+# Install Python dependencies
+RUN pip install --no-cache-dir \
+      kafka-python==2.0.2 \
+      Flask==2.2.5 \
+      requests==2.31.0
+
+# ── Application code (flat layout matching /app container paths) ──────────────
+WORKDIR /app
+
+COPY shared/                          /app/shared/
+COPY shared_data/securities.txt       /app/data/securities.txt
+
+# Matcher service
+COPY matcher/matcher.py               /app/matcher.py
+COPY matcher/database.py              /app/database.py
+
+# MD Feeder service
+COPY md_feeder/mdf_simulator.py       /app/mdf_simulator.py
+
+# Dashboard service
+COPY dashboard/dashboard.py           /app/dashboard.py
+COPY dashboard/templates/             /app/templates/
+
+# ── Kafka KRaft configuration ─────────────────────────────────────────────────
+COPY kafka-kraft.properties           /opt/kafka/config/kraft/server.properties
+
+# ── Startup script ────────────────────────────────────────────────────────────
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+EXPOSE 7860
+
+CMD ["/entrypoint.sh"]

README.md

@@ -0,0 +1,47 @@
+---
+title: StockEx Trading Demo
+emoji: 📈
+colorFrom: green
+colorTo: blue
+sdk: docker
+pinned: false
+app_port: 7860
+---
+
+# StockEx – Kafka-based Stock Exchange Simulator
+
+A real-time stock exchange simulation built with **Apache Kafka**, **Python**, and **Flask**.
+
+## Architecture
+
+| Service | Description |
+|---|---|
+| **Matcher** | Order matching engine (price-time priority, limit/market orders) |
+| **MD Feeder** | Synthetic market data generator, drives order flow |
+| **Dashboard** | Real-time trading dashboard with SSE streaming |
+
+## Features
+
+- **Live Order Book** – best bid/ask with depth
+- **Trade Feed** – real-time executions with SSE push
+- **Market Snapshot** – BBO per symbol with ticker tape
+- **Trade Chart** – live price/volume chart
+- **Price History** – OHLCV candlestick chart (1H / 8H / 1D / 1W / 1M)
+- **Start / End of Day** – reset prices, pause/resume simulation
+- **Order Management** – cancel and amend resting orders
+
+## Securities
+
+`ALPHA` · `PEIR` · `EXAE` · `QUEST` · `NBG`
+
+## Stack
+
+- Apache Kafka (KRaft mode, no ZooKeeper)
+- Python 3.11 · Flask · kafka-python
+- SQLite (matcher persistence + OHLCV history)
+- Canvas API candlestick charts
+- Server-Sent Events for real-time UI updates
+
+## Source
+
+GitHub: [github.com/Bonum/StockEx](https://github.com/Bonum/StockEx)

dashboard/dashboard.py

@@ -428,4 +428,5 @@ def stream():
 
 
 if __name__ == "__main__":
-    app.run(host="0.0.0.0", port=5000, debug=True, use_reloader=False)
+    port = int(os.getenv("PORT", "5000"))
+    app.run(host="0.0.0.0", port=port, debug=True, use_reloader=False)

entrypoint.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+set -e
+
+KAFKA_DIR=/opt/kafka
+
+export PYTHONPATH=/app
+export KAFKA_BOOTSTRAP=localhost:9092
+export MATCHER_URL=http://localhost:6000
+export PORT=7860
+
+# ── Kafka (KRaft) ─────────────────────────────────────────────────────────────
+echo "[startup] Formatting Kafka storage (KRaft)..."
+CLUSTER_ID=$($KAFKA_DIR/bin/kafka-storage.sh random-uuid)
+$KAFKA_DIR/bin/kafka-storage.sh format \
+  -t "$CLUSTER_ID" \
+  -c $KAFKA_DIR/config/kraft/server.properties \
+  --ignore-formatted
+
+echo "[startup] Starting Kafka..."
+$KAFKA_DIR/bin/kafka-server-start.sh $KAFKA_DIR/config/kraft/server.properties &
+KAFKA_PID=$!
+
+echo "[startup] Waiting for Kafka to be ready..."
+RETRIES=30
+until $KAFKA_DIR/bin/kafka-topics.sh \
+      --list --bootstrap-server localhost:9092 &>/dev/null 2>&1; do
+  RETRIES=$((RETRIES - 1))
+  if [ $RETRIES -le 0 ]; then
+    echo "[startup] ERROR: Kafka did not start in time"
+    exit 1
+  fi
+  sleep 3
+  echo "[startup] Still waiting for Kafka... ($RETRIES retries left)"
+done
+echo "[startup] Kafka ready."
+
+# Create topics
+for TOPIC in orders trades snapshots control; do
+  $KAFKA_DIR/bin/kafka-topics.sh \
+    --create --if-not-exists \
+    --topic "$TOPIC" \
+    --partitions 1 \
+    --replication-factor 1 \
+    --bootstrap-server localhost:9092
+done
+echo "[startup] Topics created."
+
+# ── Python services ────────────────────────────────────────────────────────────
+echo "[startup] Starting Matcher on port 6000..."
+python3 /app/matcher.py &
+sleep 8
+
+echo "[startup] Starting MD Feeder..."
+python3 /app/mdf_simulator.py &
+
+echo "[startup] Starting Dashboard on port 7860..."
+exec python3 /app/dashboard.py

kafka-kraft.properties

@@ -0,0 +1,20 @@
+process.roles=broker,controller
+node.id=1
+controller.quorum.voters=1@localhost:9093
+
+listeners=PLAINTEXT://localhost:9092,CONTROLLER://localhost:9093
+inter.broker.listener.name=PLAINTEXT
+advertised.listeners=PLAINTEXT://localhost:9092
+controller.listener.names=CONTROLLER
+listener.security.protocol.map=CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT
+
+log.dirs=/tmp/kafka-logs
+num.partitions=1
+offsets.topic.replication.factor=1
+transaction.state.log.replication.factor=1
+transaction.state.log.min.isr=1
+auto.create.topics.enable=true
+
+log.retention.hours=24
+log.segment.bytes=104857600
+log.retention.check.interval.ms=300000