166 lines
3.7 KiB
Markdown
166 lines
3.7 KiB
Markdown
# Deployment Guide — Loyalty Agent Service
|
|
|
|
## Prerequisites
|
|
|
|
- Java 25+ (JRE)
|
|
- PostgreSQL 15+
|
|
- Ollama with `qwen3.5:4b` and `qwen2.5:1.5b` models
|
|
- Keycloak with OAuth2 Client Credentials configured
|
|
- Loyalty Core API running (`:8081`)
|
|
|
|
## Environment Variables
|
|
|
|
Copy `.env.example` to `.env` and configure all required values:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env with your production values
|
|
```
|
|
|
|
### Required Variables
|
|
|
|
| Variable | Service | Description |
|
|
|----------|---------|-------------|
|
|
| `KEYCLOAK_CLIENT_SECRET` | MCP Server | Keycloak client secret |
|
|
| `KEYCLOAK_TOKEN_URI` | MCP Server | Keycloak token endpoint |
|
|
| `LOYALTY_CORE_BASE_URL` | MCP Server | Loyalty Core API URL |
|
|
| `SPRING_DATASOURCE_PASSWORD` | Agent | PostgreSQL password |
|
|
| `MCP_SERVER_URL` | Agent | MCP SSE endpoint |
|
|
|
|
### Optional Variables (with defaults)
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `KEYCLOAK_CLIENT_ID` | `ols-cli` | OAuth2 client ID |
|
|
| `SPRING_DATASOURCE_URL` | `jdbc:postgresql://localhost:5433/loyalty_agent` | DB URL |
|
|
| `SPRING_DATASOURCE_USERNAME` | `postgres` | DB username |
|
|
| `OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama URL |
|
|
| `OLLAMA_MODEL` | `qwen3.5:4b` | Primary LLM model |
|
|
| `AGENT_REQUEST_TIMEOUT` | `120` | LLM request timeout (seconds) |
|
|
|
|
## Building
|
|
|
|
```bash
|
|
# Build both modules
|
|
./mvnw clean package -DskipTests
|
|
|
|
# Run tests
|
|
./mvnw test
|
|
```
|
|
|
|
## Running Locally
|
|
|
|
### Quick Start
|
|
|
|
```bash
|
|
./start-all.sh
|
|
```
|
|
|
|
### Manual Start
|
|
|
|
```bash
|
|
# 1. Start MCP Server (:9331)
|
|
cd loyalty-mcp-server
|
|
java -jar target/*.jar
|
|
|
|
# 2. Start Agent (:9332)
|
|
cd loyalty-agent
|
|
java -jar target/*.jar
|
|
|
|
# 3. Start Frontend (:9333)
|
|
npm run dev
|
|
```
|
|
|
|
## Docker Deployment
|
|
|
|
### Build Images
|
|
|
|
```bash
|
|
# MCP Server
|
|
cd loyalty-mcp-server
|
|
docker build -t loyalty-mcp-server:latest .
|
|
|
|
# Agent
|
|
cd loyalty-agent
|
|
docker build -t loyalty-agent:latest .
|
|
```
|
|
|
|
### Run Containers
|
|
|
|
```bash
|
|
# MCP Server
|
|
docker run -d --name loyalty-mcp-server \
|
|
-p 9331:9331 \
|
|
-e KEYCLOAK_CLIENT_SECRET=... \
|
|
-e KEYCLOAK_TOKEN_URI=... \
|
|
-e LOYALTY_CORE_BASE_URL=... \
|
|
loyalty-mcp-server:latest
|
|
|
|
# Agent
|
|
docker run -d --name loyalty-agent \
|
|
-p 9332:9332 \
|
|
-e SPRING_DATASOURCE_PASSWORD=... \
|
|
-e MCP_SERVER_URL=http://loyalty-mcp-server:9331/sse \
|
|
loyalty-agent:latest
|
|
```
|
|
|
|
## Health Checks
|
|
|
|
Both services expose health endpoints via Spring Boot Actuator:
|
|
|
|
| Endpoint | Purpose |
|
|
|----------|---------|
|
|
| `/actuator/health` | Overall health |
|
|
| `/actuator/health/liveness` | Liveness probe (is the process alive?) |
|
|
| `/actuator/health/readiness` | Readiness probe (can it handle requests?) |
|
|
| `/actuator/info` | Service info |
|
|
|
|
### Kubernetes Probes
|
|
|
|
```yaml
|
|
livenessProbe:
|
|
httpGet:
|
|
path: /actuator/health/liveness
|
|
port: 9332
|
|
initialDelaySeconds: 60
|
|
periodSeconds: 30
|
|
|
|
readinessProbe:
|
|
httpGet:
|
|
path: /actuator/health/readiness
|
|
port: 9332
|
|
initialDelaySeconds: 30
|
|
periodSeconds: 10
|
|
```
|
|
|
|
## JVM Configuration
|
|
|
|
Production JVM flags (included in Dockerfile):
|
|
|
|
```bash
|
|
java \
|
|
-XX:+UseContainerSupport \
|
|
-XX:MaxRAMPercentage=75.0 \
|
|
-Djava.security.egd=file:/dev/./urandom \
|
|
-jar app.jar
|
|
```
|
|
|
|
## Port Summary
|
|
|
|
| Service | Port |
|
|
|---------|------|
|
|
| Loyalty MCP Server | 9331 |
|
|
| Loyalty Agent | 9332 |
|
|
| Frontend (dev) | 9333 |
|
|
| Loyalty Core API | 8081 |
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **MCP Connection Timeout**: Increase `spring.ai.mcp.client.request-timeout` (default: 30000ms)
|
|
2. **LLM Not Responding**: Check Ollama is running: `curl http://localhost:11434/api/tags`
|
|
3. **OAuth2 Token Error**: Verify Keycloak credentials and token-uri
|
|
4. **DB Migration Failed**: Check Flyway logs, ensure PostgreSQL is accessible
|
|
5. **WebSocket Disconnect**: Frontend auto-reconnects with exponential backoff
|