lordraw/discoverygram repository overview

⁠DiscoveryGram

A Telegram front-end for NoteDiscovery⁠: search, browse, read and create notes in your vault from a chat.

⁠What it will do

⁠Supported tags

Base image: python:3.12-slim-bookworm. Runs as a non-root user (uid 1001) with a built-in HEALTHCHECK.

⁠Quick start

You need a reachable NoteDiscovery instance and a bot token from @BotFather⁠.

docker run -d --name discoverygram \
  -p 8080:8080 \
  -e TELEGRAM_BOT_TOKEN='123456:AA...' \
  -e TELEGRAM_ALLOWED_USER_IDS='123456789' \
  -e NOTEDISCOVERY_URL='http://192.168.1.50:8000' \
  --restart unless-stopped \
  lordraw/discoverygram:latest

Check it came up:

curl localhost:8080/healthz   # {"status": "ok", "version": "0.1.0"}
curl localhost:8080/readyz    # 200 when NoteDiscovery is reachable, 503 otherwise

⁠docker compose

services:
  discoverygram:
    image: lordraw/discoverygram:latest
    container_name: discoverygram
    restart: unless-stopped
    env_file: [.env]
    ports:
      - "8080:8080"
    extra_hosts:
      - "host.docker.internal:host-gateway"

⁠Required configuration

Everything is configured through environment variables. Nothing is hardcoded, and invalid configuration fails fast with exit code 2 and a message naming the offending variable.

NOTEDISCOVERY_API_KEY is optional — NoteDiscovery may run unauthenticated. When set, it is sent as X-API-Key.

⁠Frequently useful settings

The full reference, including the nine LLM providers, is in CONFIGURATION.md⁠.

⁠LLM providers

Supported: NVIDIA, OpenRouter, Groq, Gemini, Cloudflare Workers AI, Cerebras, Mistral, Puter and Ollama. None is required until the LLM features land in phase 5.

Failover works on (provider, model) pairs, not on providers alone:

LLM_CHAIN_CHAT=nvidia,ollama
NVIDIA_MODELS=llama-3.3-70b,qwen2.5-72b
OLLAMA_MODELS=llama3.2

  nvidia/llama-3.3-70b (x3) -> nvidia/qwen2.5-72b (x3) -> ollama/llama3.2 (x3)

A model-level failure advances one rung and keeps the warm connection; a provider-level failure opens that provider's circuit and skips all of its remaining rungs at once. Listing ollama last keeps things working offline and keeps note content on your own hardware.

⁠Health and operations

• GET /healthz — liveness. 200 whenever the process is up.
• GET /readyz — readiness. 200 when every dependency check passes, 503 otherwise, with a per-check breakdown in the body.
• Docker HEALTHCHECK is built in; docker inspect reports healthy once ready.
• SIGTERM shuts down gracefully with exit code 0.
• Logs are structured JSON by default, with a correlation id per action and credentials redacted.

⁠Security notes

• The allow-list is the only thing between your notes and a stranger. The bot refuses to start without one, and rejects every non-listed user before any handler runs.
• The container runs as a non-root user (uid 1001).
• Never bake secrets into an image layer — pass them as environment variables or an env_file.
• Note content reaches third-party LLM providers only for commands that need it. Configuring an ollama-only chain keeps everything local.
• NoteDiscovery's MCP server is supported but disabled by default: it exposes a strict subset of the REST API, and enabling it in docker launch mode requires mounting the Docker socket, which grants root-equivalent access to the host.

⁠Documentation

• Source and README⁠
• Roadmap⁠
• Architecture⁠
• Features⁠
• Configuration reference⁠
• NoteDiscovery contract⁠

⁠License

MIT. DiscoveryGram is an independent project and is not affiliated with NoteDiscovery or Telegram.