Skip to content

Docker Support

Note

Docker setup is now intentionally simplified and does not include vLLM. The same ChemGraph image can be launched in three modes: JupyterLab, Streamlit UI, or MCP server.

Prerequisites

Files

  • Dockerfile: standard ChemGraph container image
  • Dockerfile.arm: ARM-friendly variant (same runtime goals, no vLLM)
  • docker-compose.yml: profile-based launcher for Jupyter/Streamlit/MCP

Build Image

From project root:

docker compose build

If you previously built the image before this update, rebuild so the Git safe-directory setting for /app is included.

Run JupyterLab

docker compose --profile jupyter up

Access: http://localhost:8888

Run Streamlit App

docker compose --profile streamlit up

Access: http://localhost:8501

Run MCP Server (HTTP transport)

docker compose --profile mcp up

MCP endpoint: http://localhost:9003

The compose service launches:

python -m chemgraph.mcp.mcp_tools --transport streamable_http --host 0.0.0.0 --port 9003

Environment Variables

The compose file forwards these variables into the container when set on host:

  • OPENAI_API_KEY
  • ANTHROPIC_API_KEY
  • GEMINI_API_KEY
  • GROQ_API_KEY
  • CHEMGRAPH_LOG_DIR (default in compose: /app/cg_logs)
  • PYTHONPATH is set to /app/src in compose so bind-mounted source code is used.

Example:

export OPENAI_API_KEY="your_key"
docker compose --profile streamlit up

Stop Services

docker compose down

Run Without Compose (Optional)

Build once:

docker build -t chemgraph:local .

Jupyter:

docker run --rm -it -p 8888:8888 -v "$PWD:/app" chemgraph:local \
  jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root --LabApp.token=

Streamlit:

docker run --rm -it -p 8501:8501 -v "$PWD:/app" chemgraph:local \
  streamlit run src/ui/app.py --server.address=0.0.0.0 --server.port=8501

MCP (HTTP):

docker run --rm -it -p 9003:9003 -v "$PWD:/app" chemgraph:local \
  python -m chemgraph.mcp.mcp_tools --transport streamable_http --host 0.0.0.0 --port 9003

Notes

  • This setup avoids local model-serving dependencies and keeps Docker usage focused on ChemGraph tooling.
  • If you need local LLM serving, run it as a separate service outside this Docker setup and point ChemGraph to that endpoint via model/base URL configuration.
  • Compose startup also runs git config --global --add safe.directory /app to avoid Git "dubious ownership" errors in notebooks/Streamlit when the repo is bind-mounted.
  • The default Dockerfile installs nwchem and tblite with conda-forge.

Publish to GHCR

A GitHub Actions workflow (.github/workflows/ghcr-publish.yml) publishes the Docker image to:

  • ghcr.io/<org-or-user>/chemgraph:<tag>
  • ghcr.io/<org-or-user>/chemgraph:sha-<commit>

How to publish:

git tag v0.3.0
git push origin v0.3.0

You can also trigger the workflow manually from Actions with workflow_dispatch.