Skip to content

Commit 83a6af9

Browse files
gzileniclaude
gzileni
and
claude
committed
docs: add GHCR docker-compose and README section for pre-built images
- Add docker-compose.ghcr.yml: runs the full stack using images published to ghcr.io/agent-engineering-studio/* (no source clone or build needed) Supports three Ollama modes: host, cpu profile, gpu profile - Update README: new "Running with pre-built images (GHCR)" section with step-by-step instructions, service URLs, and useful commands - Fix stale tech-stack table entries (next lint → ESLint, LangGraph → MAF) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent cb4b5c0 commit 83a6af9

2 files changed

Lines changed: 314 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 87 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ Companion repository del libro **_"AI che Ragiona"_**: implementazione productio
3636
- [Quick start](#quick-start)
3737
- [Local development (without Docker)](#local-development-without-docker)
3838
- [Running with Docker](#running-with-docker)
39+
- [Running with pre-built images (GHCR)](#running-with-pre-built-images-ghcr)
3940
- [Repository structure](#repository-structure)
4041
- [API Reference](#api-reference)
4142
- [Agent API Reference](#agent-api-reference)
@@ -122,12 +123,12 @@ Data flows through three main paths:
122123
| **Embedding Model** | nomic-embed-text (768 dim) | latest |
123124
| **REST API** | FastAPI + uvicorn | 0.115+ |
124125
| **Data Models** | Pydantic v2 + pydantic-settings | 2.7+ |
125-
| **Multi-Agent** | LangGraph (StateGraph + routing) | 0.2+ |
126+
| **Multi-Agent** | Microsoft Agent Framework (MAF) | latest |
126127
| **Frontend** | Next.js + React + Tailwind CSS | 15 / 19 / 4 |
127128
| **Graph Visualisation** | react-force-graph-2d | 1.26+ |
128129
| **Logging** | structlog (JSON in prod, console in dev) | 24.1+ |
129130
| **Testing** | pytest + pytest-asyncio + pytest-mock | 8.2+ |
130-
| **Linting** | ruff (API/Agents), ESLint + next lint (UI) | 0.4+ |
131+
| **Linting** | ruff (API/Agents), ESLint (UI) | 0.4+ |
131132
| **Containerisation** | Docker + Docker Compose | 24+ / v2 |
132133

133134
---
@@ -335,6 +336,90 @@ GPU acceleration for Ollama is configured in `docker-compose.yml` under the `dep
335336

336337
---
337338

339+
## Running with pre-built images (GHCR)
340+
341+
The easiest way to run the full stack locally **without cloning the source code or building any image**. Every CI-green merge to `main` publishes four images to the GitHub Container Registry:
342+
343+
| Image | Description |
344+
| --- | --- |
345+
| `ghcr.io/agent-engineering-studio/kg-api:latest` | FastAPI backend |
346+
| `ghcr.io/agent-engineering-studio/kg-ui:latest` | Next.js frontend |
347+
| `ghcr.io/agent-engineering-studio/kg-mcp:latest` | MCP server |
348+
| `ghcr.io/agent-engineering-studio/kg-agents:latest` | Multi-agent API |
349+
350+
### 1. Download the compose file
351+
352+
```bash
353+
curl -O https://raw.githubusercontent.com/agent-engineering-studio/knowledge-graph/main/docker-compose.ghcr.yml
354+
curl -O https://raw.githubusercontent.com/agent-engineering-studio/knowledge-graph/main/.env.example
355+
cp .env.example .env
356+
# Edit .env: set NEO4J_PASSWORD and, if needed, OLLAMA_BASE_URL
357+
```
358+
359+
### 2. Choose your Ollama setup
360+
361+
**Option A — Ollama already running on the host** (recommended if you already have models):
362+
363+
```bash
364+
# Set in .env:
365+
# OLLAMA_BASE_URL=http://host.docker.internal:11434
366+
docker compose -f docker-compose.ghcr.yml up -d
367+
```
368+
369+
**Option B — Ollama CPU container** (no GPU):
370+
371+
```bash
372+
docker compose -f docker-compose.ghcr.yml --profile cpu up -d
373+
374+
# Pull models (first time only)
375+
docker compose -f docker-compose.ghcr.yml exec ollama-cpu \
376+
sh -c "ollama pull llama3 && ollama pull nomic-embed-text"
377+
```
378+
379+
**Option C — Ollama GPU container** (NVIDIA, requires [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)):
380+
381+
```bash
382+
docker compose -f docker-compose.ghcr.yml --profile gpu up -d
383+
384+
docker compose -f docker-compose.ghcr.yml exec ollama-gpu \
385+
sh -c "ollama pull llama3 && ollama pull nomic-embed-text"
386+
```
387+
388+
### 3. Access the services
389+
390+
| Service | URL |
391+
| --- | --- |
392+
| UI | <http://localhost:3000> |
393+
| API + Swagger | <http://localhost:8000/docs> |
394+
| Agent API + Swagger | <http://localhost:8002/docs> |
395+
| MCP Server (SSE) | <http://localhost:8080> |
396+
| Neo4j Browser | <http://localhost:7474> |
397+
| RedisInsight | <http://localhost:5540> |
398+
399+
### 4. Useful commands
400+
401+
```bash
402+
# Check all containers are up
403+
docker compose -f docker-compose.ghcr.yml ps
404+
405+
# Follow logs of a specific service
406+
docker compose -f docker-compose.ghcr.yml logs -f api
407+
408+
# Pull latest images and restart
409+
docker compose -f docker-compose.ghcr.yml pull
410+
docker compose -f docker-compose.ghcr.yml up -d
411+
412+
# Stop everything
413+
docker compose -f docker-compose.ghcr.yml down
414+
415+
# Stop and remove all data (WARNING: deletes Neo4j + Redis volumes)
416+
docker compose -f docker-compose.ghcr.yml down -v
417+
```
418+
419+
> **Note**: the GHCR packages for this repository are public. No `docker login` is required to pull them.
420+
421+
---
422+
338423
## Repository structure
339424

340425
```text

‎docker-compose.ghcr.yml‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
# ── Pre-built images from GitHub Container Registry ───────────────────────────
2+
#
3+
# Use this file to run the full Knowledge Graph stack locally without cloning
4+
# the source code or building any image.
5+
#
6+
# Images are published automatically on every CI-green merge to main:
7+
# ghcr.io/agent-engineering-studio/kg-api:latest
8+
# ghcr.io/agent-engineering-studio/kg-ui:latest
9+
# ghcr.io/agent-engineering-studio/kg-mcp:latest
10+
# ghcr.io/agent-engineering-studio/kg-agents:latest
11+
#
12+
# Quick start:
13+
# 1. Copy .env.example → .env and set your passwords / Ollama URL
14+
# 2. Pull and start (CPU, no GPU):
15+
# docker compose -f docker-compose.ghcr.yml --profile cpu up -d
16+
# Or if Ollama is already running on the host:
17+
# docker compose -f docker-compose.ghcr.yml up -d
18+
# 3. docker compose -f docker-compose.ghcr.yml exec ollama-cpu \
19+
# ollama pull llama3 && ollama pull nomic-embed-text
20+
# (skip if OLLAMA_BASE_URL points to a host-side Ollama)
21+
#
22+
# Profiles:
23+
# (none) → infra + app services; Ollama expected on the host at :11434
24+
# cpu → same + Ollama CPU container
25+
# gpu → same + Ollama GPU container (requires NVIDIA Container Toolkit)
26+
# ──────────────────────────────────────────────────────────────────────────────
27+
28+
services:
29+
# ── Neo4j (Graph DB) ──────────────────────────────────────────────────────────
30+
neo4j:
31+
container_name: kg-neo4j
32+
image: neo4j:5.18
33+
ports:
34+
- "7474:7474"
35+
- "7687:7687"
36+
environment:
37+
NEO4J_AUTH: "neo4j/${NEO4J_PASSWORD:-password}"
38+
NEO4J_PLUGINS: '["apoc"]'
39+
volumes:
40+
- neo4j_data:/data
41+
- neo4j_logs:/logs
42+
healthcheck:
43+
test:
44+
["CMD", "cypher-shell", "-u", "neo4j", "-p", "${NEO4J_PASSWORD:-password}", "RETURN 1"]
45+
interval: 30s
46+
timeout: 10s
47+
retries: 5
48+
restart: unless-stopped
49+
50+
# ── Redis Stack (Vector Store + RedisInsight) ─────────────────────────────────
51+
redis:
52+
container_name: kg-redis
53+
image: redis/redis-stack:latest
54+
ports:
55+
- "6379:6379"
56+
- "8001:8001"
57+
volumes:
58+
- redis_data:/data
59+
healthcheck:
60+
test: ["CMD", "redis-cli", "ping"]
61+
interval: 15s
62+
timeout: 5s
63+
retries: 3
64+
restart: unless-stopped
65+
66+
# ── Ollama CPU-only ───────────────────────────────────────────────────────────
67+
# Use profile "cpu" on machines without an NVIDIA GPU.
68+
# Skip both ollama profiles if Ollama is already running on the host and set
69+
# OLLAMA_BASE_URL=http://host.docker.internal:11434 in your .env.
70+
ollama-cpu:
71+
container_name: kg-ollama-cpu
72+
profiles: [cpu]
73+
image: ollama/ollama:latest
74+
ports:
75+
- "127.0.0.1:11434:11434"
76+
volumes:
77+
- ollama_models:/root/.ollama
78+
healthcheck:
79+
test: ["CMD", "curl", "-sf", "http://localhost:11434/api/tags"]
80+
interval: 30s
81+
timeout: 10s
82+
retries: 10
83+
start_period: 60s
84+
restart: unless-stopped
85+
86+
# ── Ollama GPU (NVIDIA) ───────────────────────────────────────────────────────
87+
# Use profile "gpu" on machines with an NVIDIA GPU.
88+
ollama-gpu:
89+
container_name: kg-ollama-gpu
90+
profiles: [gpu]
91+
image: ollama/ollama:latest
92+
ports:
93+
- "127.0.0.1:11434:11434"
94+
volumes:
95+
- ollama_models:/root/.ollama
96+
healthcheck:
97+
test: ["CMD", "curl", "-sf", "http://localhost:11434/api/tags"]
98+
interval: 30s
99+
timeout: 10s
100+
retries: 10
101+
start_period: 60s
102+
deploy:
103+
resources:
104+
reservations:
105+
devices:
106+
- driver: nvidia
107+
count: all
108+
capabilities: [gpu]
109+
restart: unless-stopped
110+
111+
# ── API — pre-built image from GHCR ──────────────────────────────────────────
112+
api:
113+
container_name: kg-api
114+
image: ghcr.io/agent-engineering-studio/kg-api:latest
115+
ports:
116+
- "8000:8000"
117+
env_file:
118+
- path: .env
119+
required: false
120+
environment:
121+
NEO4J_URI: "bolt://neo4j:7687"
122+
NEO4J_USER: "${NEO4J_USER:-neo4j}"
123+
NEO4J_PASSWORD: "${NEO4J_PASSWORD:-password}"
124+
REDIS_URL: "redis://redis:6379"
125+
OLLAMA_BASE_URL: "${OLLAMA_BASE_URL:-http://host.docker.internal:11434}"
126+
OLLAMA_LLM_MODEL: "${OLLAMA_LLM_MODEL:-llama3}"
127+
OLLAMA_EMBEDDING_MODEL: "${OLLAMA_EMBEDDING_MODEL:-nomic-embed-text}"
128+
depends_on:
129+
neo4j:
130+
condition: service_healthy
131+
redis:
132+
condition: service_healthy
133+
healthcheck:
134+
test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
135+
interval: 30s
136+
timeout: 10s
137+
retries: 3
138+
restart: unless-stopped
139+
140+
# ── UI — pre-built image from GHCR ───────────────────────────────────────────
141+
ui:
142+
container_name: kg-ui
143+
image: ghcr.io/agent-engineering-studio/kg-ui:latest
144+
ports:
145+
- "3000:3000"
146+
environment:
147+
NEXT_PUBLIC_API_URL: "${NEXT_PUBLIC_API_URL:-http://localhost:8000}"
148+
NEXT_PUBLIC_ENABLE_STREAMING: "${NEXT_PUBLIC_ENABLE_STREAMING:-true}"
149+
NEXT_PUBLIC_ENABLE_GRAPH_VIEW: "${NEXT_PUBLIC_ENABLE_GRAPH_VIEW:-true}"
150+
depends_on:
151+
api:
152+
condition: service_healthy
153+
healthcheck:
154+
test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000"]
155+
interval: 30s
156+
timeout: 10s
157+
retries: 3
158+
restart: unless-stopped
159+
160+
# ── MCP Server — pre-built image from GHCR ───────────────────────────────────
161+
mcp:
162+
container_name: kg-mcp
163+
image: ghcr.io/agent-engineering-studio/kg-mcp:latest
164+
ports:
165+
- "8080:8080"
166+
environment:
167+
KG_API_URL: "http://api:8000"
168+
MCP_TRANSPORT: "sse"
169+
MCP_HOST: "0.0.0.0"
170+
MCP_PORT: "8080"
171+
KG_API_TIMEOUT: "600"
172+
depends_on:
173+
api:
174+
condition: service_healthy
175+
healthcheck:
176+
test: ["CMD-SHELL", "python3 -c \"import socket; socket.create_connection(('localhost', 8080), 3).close()\""]
177+
interval: 15s
178+
timeout: 10s
179+
retries: 5
180+
start_period: 30s
181+
restart: unless-stopped
182+
183+
# ── Agents — pre-built image from GHCR ───────────────────────────────────────
184+
agents:
185+
container_name: kg-agents
186+
image: ghcr.io/agent-engineering-studio/kg-agents:latest
187+
ports:
188+
- "8002:8001"
189+
environment:
190+
KG_API_URL: "http://api:8000"
191+
KG_MCP_URL: "http://mcp:8080"
192+
OLLAMA_BASE_URL: "${OLLAMA_BASE_URL:-http://host.docker.internal:11434}"
193+
OLLAMA_LLM_MODEL: "${OLLAMA_LLM_MODEL:-llama3}"
194+
KG_API_TIMEOUT: "60"
195+
depends_on:
196+
mcp:
197+
condition: service_healthy
198+
healthcheck:
199+
test: ["CMD", "curl", "-f", "http://localhost:8001/agents/health"]
200+
interval: 30s
201+
timeout: 10s
202+
retries: 3
203+
restart: unless-stopped
204+
205+
# ── RedisInsight ──────────────────────────────────────────────────────────────
206+
redisinsight:
207+
container_name: kg-redisinsight
208+
image: redis/redisinsight:latest
209+
ports:
210+
- "5540:5540"
211+
volumes:
212+
- redisinsight_data:/data
213+
depends_on:
214+
redis:
215+
condition: service_healthy
216+
restart: unless-stopped
217+
218+
volumes:
219+
neo4j_data:
220+
neo4j_logs:
221+
redis_data:
222+
ollama_models:
223+
redisinsight_data:
224+
225+
networks:
226+
default:
227+
name: kg_network

0 commit comments

Comments
 (0)