Effi/docs/LEANTIME-INSTALLATION.md

# Installation Leantime + MCP Integration

Ce document decrit l'installation complete de Leantime sur XPenology NAS et l'integration MCP avec Effi (Open WebUI via MCPO).

## Architecture

```
Open WebUI (effi-server:3000)
    → MCPO (effi-server:8000)
        → leantime-mcp (effi-server:8079, SSE)
            → Leantime API (XPenology NAS:8380)
```

## Partie 1 : Installation Leantime sur XPenology NAS

### Prerequis

- XPenology NAS avec Docker (DSM 7.2+)
- Acces SSH au NAS
- Reseau local : XPenology sur `192.168.1.25`

### 1. Creer le repertoire de configuration

```bash
ssh admin@192.168.1.25
sudo mkdir -p /volume1/docker/leantime
cd /volume1/docker/leantime
```

### 2. Creer le fichier `.env`

```bash
cat > .env << 'EOF'
LEANTIME_HOST=http://leantime:8380
LEAN_DB_HOST=mysql-leantime
LEAN_DB_USER=leantime
LEAN_DB_PASSWORD=CHANGEZ_MOI_mot_de_passe_securise
LEAN_DB_DATABASE=leantime
LEAN_DB_PORT=3306
LEAN_DEFAULT_TIMEZONE=Europe/Paris
MYSQL_ROOT_PASSWORD=CHANGEZ_MOI_mot_de_passe_root_securise
MYSQL_DATABASE=leantime
MYSQL_USER=leantime
MYSQL_PASSWORD=CHANGEZ_MOI_mot_de_passe_securise
EOF
```

**Important :** `LEAN_DB_PASSWORD` et `MYSQL_PASSWORD` doivent etre identiques. `MYSQL_ROOT_PASSWORD` est distinct.

### 3. Creer le `docker-compose.yml`

```yaml
version: '3.8'

services:
  mysql-leantime:
    image: mysql:8.4
    container_name: mysql-leantime
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    volumes:
      - leantime-db-data:/var/lib/mysql
    networks:
      - leantime-net

  leantime:
    image: leantime/leantime:latest
    container_name: leantime
    restart: unless-stopped
    depends_on:
      - mysql-leantime
    environment:
      LEAN_DB_HOST: ${LEAN_DB_HOST}
      LEAN_DB_USER: ${LEAN_DB_USER}
      LEAN_DB_PASSWORD: ${LEAN_DB_PASSWORD}
      LEAN_DB_DATABASE: ${LEAN_DB_DATABASE}
      LEAN_DB_PORT: ${LEAN_DB_PORT}
      LEAN_DEFAULT_TIMEZONE: ${LEAN_DEFAULT_TIMEZONE}
    ports:
      - "8380:80"
    networks:
      - leantime-net

volumes:
  leantime-db-data:

networks:
  leantime-net:
    driver: bridge
```

**Notes :**
- Port 8380 pour eviter les conflits avec DSM (port 80/443)
- Volume nomme `leantime-db-data` (pas bind mount) pour eviter les problemes de permissions Synology
- Reseau interne `leantime-net` pour isolation

### 4. Lancer Leantime

```bash
# Premier lancement (initialisation de la base)
docker compose up -d

# Attendre ~30s que MySQL s'initialise, puis verifier :
docker logs mysql-leantime --tail 5
docker logs leantime --tail 10
```

### 5. Creer le compte admin

1. Ouvrir `http://192.168.1.25:8380`
2. Suivre l'assistant de premier lancement
3. Creer le compte admin

### 6. Generer la cle API

1. Se connecter en admin
2. Aller dans **Company > API Keys**
3. Creer une nouvelle cle
4. Noter la cle (elle sera utilisee dans `.env` d'Effi)

### Problemes connus (XPenology)

#### Erreur "Access denied for user"
- Verifier que `MYSQL_PASSWORD` et `LEAN_DB_PASSWORD` sont identiques
- Si la base existe deja, verifier les credentials : `docker exec -it mysql-leantime mysql -u leantime -p`

#### Erreur "data directory has files"
- Utiliser un volume nomme Docker (`leantime-db-data`) au lieu d'un bind mount
- Les permissions Synology sont incompatibles avec les bind mounts MySQL

---

## Partie 2 : Integration MCP sur effi-server

### Prerequis

- effi-server (192.168.1.27) avec docker-compose Effi operationnel
- Leantime operationnel sur `http://192.168.1.25:8380`
- Cle API Leantime generee

### 1. Ajouter les variables d'environnement

Sur effi-server, editer `~/effi/.env` :

```bash
# Leantime MCP
LEANTIME_URL=http://192.168.1.25:8380
LEANTIME_API_KEY=votre_cle_api_leantime_ici
LEANTIME_USER_EMAIL=votre_email@example.com
```

### 2. Construire l'image leantime-mcp

Le Dockerfile est dans `leantime-mcp/Dockerfile` :

```dockerfile
FROM python:3.12-slim

RUN apt-get update && apt-get install -y --no-install-recommends git && rm -rf /var/lib/apt/lists/*

WORKDIR /app

RUN git clone https://github.com/daniel-eder/leantime-mcp.git && \
    cd leantime-mcp && \
    pip install --no-cache-dir fastmcp && \
    pip install --no-cache-dir -e .

WORKDIR /app/leantime-mcp

EXPOSE 8079

CMD ["fastmcp", "run", "src/leantime_mcp/server.py:app", "--transport", "sse", "--port", "8079", "--host", "0.0.0.0"]
```

**Note :** Le transport SSE est obligatoire car MCPO ne supporte pas StreamableHTTP.

### 3. Configurer MCPO

Le fichier `mcpo-config/config.json` (sur le serveur, gitignore) :

```json
{
  "mcpServers": {
    "leantime": {
      "url": "http://leantime-mcp:8079/sse",
      "transport": "sse"
    }
  }
}
```

### 4. Lancer les conteneurs

```bash
cd ~/effi

# Construire leantime-mcp
docker compose build leantime-mcp

# Lancer tout
docker compose up -d leantime-mcp mcpo

# Verifier les logs
docker logs effi-leantime-mcp --tail 10
docker logs mcpo --tail 15
```

### 5. Verifier la connexion

```bash
# Tester l'endpoint MCPO
curl -s http://192.168.1.27:8000/v1/tools | jq '.[].name'

# Doit retourner les outils Leantime :
# list_projects, create_project, list_tickets, etc.
```

### 6. Tester dans Open WebUI

Dans un chat avec Effi, demander :
- "Liste mes projets Leantime"
- "Cree un projet blablabla"
- "Quelles sont les taches du projet X ?"

---

## Problemes connus (MCP)

#### Erreur 400 Bad Request entre MCPO et leantime-mcp
- **Cause** : Incompatibilite de protocole (SSE vs StreamableHTTP)
- **Solution** : Verifier que leantime-mcp utilise `--transport sse` dans le Dockerfile et que MCPO pointe vers `/sse`

#### mcpo-patch.sh est un dossier au lieu d'un fichier
- **Cause** : Conflit Docker quand le fichier n'existe pas encore
- **Solution** : `docker compose down`, supprimer le dossier, recreer le fichier, puis `docker compose up -d`

#### Module leantime_mcp introuvable
- **Cause** : Mauvais WORKDIR ou mauvais chemin dans CMD
- **Solution** : Verifier que WORKDIR est `/app/leantime-mcp` et que le module s'installe avec `pip install -e .`

---

## Ports recapitulatifs

| Service | Hote | Port | Protocole |
|---------|------|------|-----------|
| Leantime Web UI | XPenology NAS | 8380 | HTTP |
| Leantime MySQL | XPenology NAS | 3306 (interne) | MySQL |
| leantime-mcp | effi-server | 8079 | SSE (MCP) |
| MCPO | effi-server | 8000 | HTTP (OpenAI-compatible) |

---

## Reinstallation rapide

Si vous devez tout reinstaller :

```bash
# Sur effi-server
cd ~/effi

# Arreter les conteneurs concernes
docker compose down leantime-mcp mcpo

# Reconstruire leantime-mcp
docker compose build leantime-mcp --no-cache

# Relancer
docker compose up -d leantime-mcp mcpo

# Verifier
docker logs mcpo -f --tail 20
```

```bash
# Sur XPenology (si reinstalle completement)
cd /volume1/docker/leantime

# ATTENTION : detruit les donnees
docker compose down -v
docker compose up -d
```