Add dockerfile and update readme

Author: erikh360

.env.docker.example

@@ -0,0 +1,9 @@
+# Copy this file to .env.docker and set real values before running compose.
+
+# Shared app + worker configuration
+TURN_HMAC_SECRET=replace-with-turn-webhook-secret
+TURN_API_BASE_URL=https://whatsapp.turn.io
+TURN_API_TOKEN=replace-with-turn-api-token
+
+# Optional
+SENTRY_DSN=

.gitignore

@@ -38,6 +38,8 @@ pip-selfcheck.json
 # Environments
 .env/
 .venv/
+.env.docker
+.env
 
 # Installer logs
 pip-log.txt

README.md

@@ -1,107 +1,161 @@
 # MomConnect Intent Classifier
 
-Model that classifies the intent of inbound messages. It is not intended to be exposed to the outside world, we only have it accisble inside the cluster.
+Model that classifies the intent of inbound messages. It is not intended to be exposed to the outside world; we only have it accessible inside the cluster.
 
 ## Development
-This project uses [poetry](https://python-poetry.org/docs/#installation) for packaging and dependancy management, so install that first.
+
+This project uses [Poetry](https://python-poetry.org/docs/#installation) for packaging and dependency management, so install that first.
 
 Ensure you're also running at least python 3.11, `python --version`.
 
-Then you can install the dependencies
+Then you can install the dependencies:
+
+```bash
+poetry install
+```
+
+### Local Stack with Docker Compose
+
+This project ships with a local async stack:
+
+- `api`: Flask + Gunicorn on port `5000`
+- `worker`: Celery worker
+- `rabbitmq`: internal broker (no host ports exposed)
+
+1. Create your local env file:
+
+```bash
+cp .env.docker.example .env.docker
+```
+
+1. Fill in required values in `.env.docker`:
+
+- `TURN_HMAC_SECRET`
+- `TURN_API_BASE_URL`
+- `TURN_API_TOKEN`
+
+1. Spin up the stack:
+
+```bash
+docker compose --env-file .env.docker up --build
+```
+
+1. Verify the API is up:
+
 ```bash
-~ poetry install
+curl http://localhost:5000/metrics
 ```
 
-To run a local worker, set NLU_USERNAME and NLU_PASSWORD environment variables, then start up the flask worker
+1. Expose your local API with ngrok (host machine):
+
 ```bash
-~ poetry run flask --app src.application run
+ngrok http 5000
 ```
 
-### Running the Celery Worker
+Then point your webhook sender at:
+
+```text
+https://<your-ngrok-subdomain>.ngrok-free.app/nlu/
+```
 
-For async task processing, you need to run a Celery worker. First, ensure you have RabbitMQ running (or another message broker configured via `CELERY_BROKER_URL`).
+1. Quick local endpoint check (without signature, should return `401`):
 
-To start the Celery worker:
 ```bash
-~ poetry run celery -A src.celery_app worker --loglevel=info --concurrency=4
+curl -i -X POST http://localhost:5000/nlu/ \
+  -H "Content-Type: application/json" \
+  -d '{"messages":[]}'
 ```
 
-To test the Celery connection, you can run the hello world task:
-```python
-from src.tasks import hello_world
-result = hello_world.delay("Test")
-print(result.get())  # Should print: {'status': 'success', 'message': 'Hello, Test!'}
+### Local Python-Only Run (No Docker)
+
+To run Flask directly:
+
+```bash
+poetry run flask --app src.application run
 ```
 
-For local development with synchronous execution (no RabbitMQ needed), set:
+To run Celery directly (requires RabbitMQ or another broker):
+
+```bash
+poetry run celery -A src.celery_app worker --loglevel=info --concurrency=4
+```
+
+For synchronous local testing (no broker):
+
 ```bash
 export CELERY_TASK_ALWAYS_EAGER=true
 ```
 
-To run the autoformatting and linting, run
+To run the autoformatting and linting:
+
 ```bash
-~ ruff format && ruff check && mypy --install-types
+poetry run ruff format && poetry run ruff check && poetry run mypy --install-types
 ```
 
 For the test runner, we use [pytest](https://docs.pytest.org/):
+
 ```bash
-~ pytest
+poetry run pytest
 ```
 
-## Regenerating the embeddings json file
+## Regenerating the embeddings JSON file
 
-1. Delete the json embeddings file in src/data/
-1. Update the nlu.yaml with your changes
-1. Run the flask app, this should regenerate the embeddings file. `poetry run flask --app src.application run`
+1. Delete the JSON embeddings file in `src/data/`.
+1. Update `nlu.yaml` with your changes.
+1. Run the Flask app. This should regenerate the embeddings file:
+
+```bash
+poetry run flask --app src.application run
+```
 
 ## Editor configuration
 
 If you'd like your editor to handle linting and/or formatting for you, here's how to set it up.
 
 ### Visual Studio Code
 
-1. Install the Python and Ruff extensions
-1. In settings, check the "Python > Linting: Mypy Enabled" box
-1. In settings, set the "Python > Formatting: Provider" to "black" (apparently "ruff format" isn't supported by the Python extension yet and "black" is probably close enough)
-1. If you want to have formatting automatically apply, in settings, check the "Editor: Format On Save" checkbox
+1. Install the Python and Ruff extensions.
+1. In settings, check the "Python > Linting: Mypy Enabled" box.
+1. In settings, set the "Python > Formatting: Provider" to "black" (apparently `ruff format` is not supported by the Python extension yet, and `black` is probably close enough).
+1. If you want formatting to apply automatically, in settings, check the "Editor: Format On Save" checkbox.
 
 Alternatively, add the following to your `settings.json`:
+
 ```json
 {
-    "python.linting.mypyEnabled": true,
-    "python.formatting.provider": "black",
-    "editor.formatOnSave": true,
+  "python.linting.mypyEnabled": true,
+  "python.formatting.provider": "black",
+  "editor.formatOnSave": true
 }
 ```
 
 ## Release process
 
 To release a new version, follow these steps:
 
-1. Make sure all relevant PRs are merged and that all necessary QA testing is complete
-1. Make sure release notes are up to date and accurate
+1. Make sure all relevant PRs are merged and that all necessary QA testing is complete.
+1. Make sure release notes are up to date and accurate.
 1. In one commit on the `main` branch:
    - Update the version number in `pyproject.toml` to the release version
    - Replace the UNRELEASED header in `CHANGELOG.md` with the release version and date
-1. Tag the release commit with the release version (for example, `v0.2.1` for version `0.2.1`)
-1. Push the release commit and tag
+1. Tag the release commit with the release version (for example, `v0.2.1` for version `0.2.1`).
+1. Push the release commit and tag.
 1. In one commit on the `main` branch:
    - Update the version number in `pyproject.toml` to the next pre-release version
    - Add a new UNRELEASED header in `CHANGELOG.md`
-1. Push the post-release commit
+1. Push the post-release commit.
 
 ## Running in Production
-There is a [docker image](https://github.com/praekeltfoundation/mc-intent-classifier/pkgs/container/mc-intent-classifier) that can be used to easily run this service. It uses the following environment variables for configuration:
-
-| Variable      | Description | Required |
-| ----------    | ----------- | -------- |
-| NLU_USERNAME  | The username used for API requests | Yes (for /nlu/ endpoint) |
-| NLU_PASSWORD  | The password used for API requests | Yes (for /nlu/ endpoint) |
-| SENTRY_DSN    | Where to send exceptions to | No |
-| CELERY_BROKER_URL | RabbitMQ connection URL (e.g., amqp://user:pass@host:5672/) | Yes (for async processing) |
-| CELERY_RESULT_BACKEND | Result backend URL (e.g., rpc://) | No (defaults to rpc://) |
-| CELERY_TASK_ALWAYS_EAGER | Set to "true" for synchronous task execution (testing only) | No |
-| TURN_API_BASE_URL | Turn API base URL (e.g., https://whatsapp.turn.io) | Yes (for Turn integration) |
+
+There is a [docker image](https://github.com/praekeltfoundation/mc-intent-classifier/pkgs/container/mc-intent-classifier) that can be used to run this service. It uses the following environment variables for configuration:
+
+| Variable | Description | Required |
+| --- | --- | --- |
+| TURN_HMAC_SECRET | Shared secret used to validate the `X-Turn-Hook-Signature` header on `/nlu/` requests | Yes |
+| SENTRY_DSN | Where to send exceptions | No |
+| CELERY_BROKER_URL | RabbitMQ connection URL (for example, `amqp://user:pass@host:5672/`) | Yes (for async processing) |
+| CELERY_TASK_ALWAYS_EAGER | Set to `true` for synchronous task execution (testing only) | No |
+| TURN_API_BASE_URL | Turn API base URL (for example, `https://whatsapp.turn.io`) | Yes (for Turn integration) |
 | TURN_API_TOKEN | Turn API authentication token (Bearer token) | Yes (for Turn integration) |
 
 **Note:** You need to run both the Flask app (webhook receiver) and Celery worker (task processor) containers for full functionality.

docker-compose.yml

@@ -0,0 +1,63 @@
+services:
+  rabbitmq:
+    image: rabbitmq:3-management
+    healthcheck:
+      test: ["CMD", "rabbitmq-diagnostics", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    volumes:
+      - rabbitmq_data:/var/lib/rabbitmq
+
+  api:
+    build:
+      context: .
+    command:
+      [
+        "/.venv/bin/gunicorn",
+        "application:app",
+        "-b",
+        "0.0.0.0:5000",
+        "-w",
+        "4",
+      ]
+    working_dir: /src
+    depends_on:
+      rabbitmq:
+        condition: service_healthy
+    ports:
+      - "5000:5000"
+    environment:
+      TURN_HMAC_SECRET: ${TURN_HMAC_SECRET}
+      TURN_API_BASE_URL: ${TURN_API_BASE_URL}
+      TURN_API_TOKEN: ${TURN_API_TOKEN}
+      SENTRY_DSN: ${SENTRY_DSN:-}
+      CELERY_BROKER_URL: amqp://guest:guest@rabbitmq:5672//
+      CELERY_TASK_ALWAYS_EAGER: "false"
+
+  worker:
+    build:
+      context: .
+    command:
+      [
+        "/.venv/bin/celery",
+        "-A",
+        "src.celery_app",
+        "worker",
+        "--loglevel=info",
+        "--concurrency=4",
+      ]
+    working_dir: /src
+    depends_on:
+      rabbitmq:
+        condition: service_healthy
+    environment:
+      TURN_HMAC_SECRET: ${TURN_HMAC_SECRET}
+      TURN_API_BASE_URL: ${TURN_API_BASE_URL}
+      TURN_API_TOKEN: ${TURN_API_TOKEN}
+      SENTRY_DSN: ${SENTRY_DSN:-}
+      CELERY_BROKER_URL: amqp://guest:guest@rabbitmq:5672//
+      CELERY_TASK_ALWAYS_EAGER: "false"
+
+volumes:
+  rabbitmq_data: