ecrespo/reflex-chatbot repository overview

⁠Docker and Docker Hub

Image: ecrespo/reflex-chatbot⁠ (linux/amd64 and linux/arm64). Source: https://github.com/ecrespo/chatbot⁠.

The image runs Reflex in production mode with frontend and backend on a single port (3000 by default). docker build installs the Python dependencies (uv, from uv.lock), bun and the frontend packages, and runs a first build. At start-up Reflex recompiles in a few seconds, so PORT or REFLEX_API_URL can change without rebuilding the image.

Files:

⁠1. Run the published image

docker run --rm -p 3000:3000 --env-file .env \
  --add-host host.docker.internal:host-gateway \
  ecrespo/reflex-chatbot:latest

Open http://localhost:3000⁠. When OLLAMA_BASE_URL is empty or unset, the container uses Ollama on the host (http://host.docker.internal:11434/v1).

With OpenRouter only, no special networking is needed:

docker run --rm -p 3000:3000 \
  -e LLM_PROVIDER=openrouter -e OPENROUTER_API_KEY=sk-or-v1-... \
  ecrespo/reflex-chatbot:latest

Tags: latest (last stable release), X.Y.Z and X.Y. Pre-releases (X.Y.ZrcN) only get their own tag.

⁠2. docker compose and profiles

A single docker-compose.yml covers every setup. The chatbot always runs; the Ollama services only start when their profile is enabled:

Use one Ollama profile at a time. Instead of --profile you can set COMPOSE_PROFILES=ollama in .env, and then docker compose up -d is enough.

docker compose up uses the published image ${DOCKERHUB_USER:-ecrespo}/reflex-chatbot:${IMAGE_TAG:-latest}; add --build to build it from your checkout instead.

Stop everything, whatever profile started it: make down (docker compose --profile '*' down). Models are kept in the ollama-models volume.

⁠2a. LLM on your machine (no profile)

cp .env.example .env        # set LLM_PROVIDER, models, keys
docker compose up -d
docker compose logs -f chatbot

docker-compose.yml loads .env and overrides the local server URLs, because inside the container localhost is the container itself:

host.docker.internal is mapped to the host with extra_hosts: host-gateway (Linux) and exists out of the box in Docker Desktop (macOS/Windows).

On Linux the host server must listen on all interfaces, not only on 127.0.0.1:

Alternative on Linux: add network_mode: host to the chatbot service (and remove ports); then localhost really is the host and the DOCKER_* variables are not needed.

⁠2b. Ollama inside compose (profiles ollama / ollama-gpu)

# in .env: LLM_PROVIDER=ollama, OLLAMA_MODEL=llama3.2, OLLAMA_PULL_MODELS="llama3.2 qwen3:8b"
docker compose --profile ollama up -d        # CPU
docker compose --profile ollama-gpu up -d    # NVIDIA GPU (nvidia-container-toolkit)

• ollama / ollama-gpu store models in the ollama-models volume and publish 11434 on 127.0.0.1 only, since Ollama has no authentication (OLLAMA_PORT changes the port, OLLAMA_BIND=0.0.0.0 exposes it to the network). Both answer to the DNS name ollama.
• ollama-pull waits until Ollama is healthy, pulls OLLAMA_PULL_MODELS and exits. After a new pull, press Modelos in the UI.
• The chatbot waits for Ollama's healthcheck and uses http://ollama:11434/v1 automatically (keep DOCKER_OLLAMA_BASE_URL empty).
• AMD ROCm: profile ollama with OLLAMA_IMAGE_TAG=rocm, and add devices: ["/dev/kfd", "/dev/dri"] to the ollama service.

⁠3. Ports, domain and reverse proxy

The browser connects to the backend over a WebSocket on the same host and port as the page. Therefore:

• Change the port with PORT (same number inside and outside): PORT=8080 docker compose up -d.
• If you publish on a different external port (-p 80:3000) or behind a proxy/domain, set REFLEX_API_URL to the public URL, e.g. REFLEX_API_URL=https://chat.mydomain.com.
• The proxy must forward WebSockets on /_event. Caddy example:

chat.mydomain.com {
    reverse_proxy localhost:3000
}

Nginx:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 300s;
}

⁠4. Updating a running deployment

docker compose pull                 # new chatbot (and Ollama) images
docker compose up -d                # recreates only what changed
docker image prune -f               # optional: drop the old layers

Pin a version with IMAGE_TAG=0.2.0 in .env and change it when you want to upgrade. With an Ollama profile, pass the same --profile (or keep COMPOSE_PROFILES in .env).

⁠5. Publishing to Docker Hub

Releases are published automatically by .github/workflows/release.yml when a vX.Y.Z tag is pushed, together with the PyPI package — see RELEASING.md⁠. The workflow logs in with the DOCKERHUB_TOKEN secret (a personal access token with Read, Write & Delete scope), pushes the X.Y.Z, X.Y and latest tags and updates the repository description from this file. Edits to this page merged into main are synced to Docker Hub by .github/workflows/dockerhub-description.yml.

Manual publishing (e.g. from a fork):

docker login -u <your_user>                          # Personal access token as password

make docker-push DOCKERHUB_USER=<your_user>          # local arch, :latest and :<version>

docker buildx create --use --name multi 2>/dev/null || docker buildx use multi
make docker-buildx DOCKERHUB_USER=<your_user>        # amd64 + arm64

On an amd64 machine the arm64 half runs under QEMU and the frontend prerender may time out; the release workflow avoids this by building each architecture on a native runner and joining them with docker buildx imagetools create.

With compose: DOCKERHUB_USER=<your_user> IMAGE_TAG=0.1.1 docker compose build && docker compose push chatbot.

⁠6. Diagnostics

docker compose ps                                   # status + healthcheck
docker compose logs -f chatbot                      # first line shows the Ollama URL in use
docker compose exec chatbot curl -s http://127.0.0.1:3000/ping
# can the container see the LLM?
docker compose exec chatbot curl -s http://host.docker.internal:11434/v1/models
docker compose exec chatbot curl -s http://ollama:11434/v1/models    # with an Ollama profile