From 5f671267730e2d73b951f7d97d437ce8e47873a2 Mon Sep 17 00:00:00 2001
From: Christophe Besson <cbesson@gmail.com>
Date: Sun, 9 Aug 2026 21:43:31 +0200
Subject: fix: document pip SSL_CERT_FILE workaround for Python 3.14 on
 Ubuntu/Fedora

pip + Python 3.14 fails with FileNotFoundError in certifi.where() on fresh
venvs (truststore bug). Fix: SSL_CERT_FILE pointing to system CA bundle.
Documented in CLAUDE.md (Python environment section) and QUICKSTART.md.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md          | 22 ++++++++++++----------
 docs/QUICKSTART.md | 21 +++++++++++++++++----
 2 files changed, 29 insertions(+), 14 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 306cad3..fc28305 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -29,21 +29,23 @@ Jamais de processus orphelins ni de ports ouverts après un test.
 ## Python environment
 
 - **Minimum Python:** 3.12
-- **Package manager:** uv (`uv sync` at root installs all workspace packages in editable mode)
 - **Build backend:** hatchling (per package `pyproject.toml`)
 
 ```bash
-# Install dev environment
-uv sync
-
-# Run hub (dev mode)
-uv run meshbay-hub
+# Créer le venv et installer les packages
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e packages/meshbay-common -e packages/meshbay-hub -e packages/meshbay-node
+pip install httpx blake3 uvicorn pytest pytest-asyncio
+```
 
-# Run node (dev mode)
-uv run meshbay-node
+> **Bug pip + Python 3.14** sur Ubuntu et Fedora : `FileNotFoundError` dans certifi.
+> Passer `SSL_CERT_FILE` avant le premier `pip install` :
+> - Ubuntu : `SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt pip install ...`
+> - Fedora  : `SSL_CERT_FILE=/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem pip install ...`
 
-# Run tests
-uv run pytest
+```bash
+# Lancer les tests
+.venv/bin/pytest
 ```
 
 ## Code conventions
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index 2f1a728..b5ca327 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -13,13 +13,26 @@ Le node tourne sur votre machine et héberge vos fichiers.
 - Un accès à `https://meshbay.org`
 
 ```bash
-git clone <url-du-repo> ~/meshbay
-cd ~/meshbay
+cd ~/meshbay              # le dépôt local (pas encore publié sur GitHub)
 python3 -m venv .venv && source .venv/bin/activate
-pip install -e packages/meshbay-common -e packages/meshbay-node
-pip install httpx blake3 uvicorn
 ```
 
+> **Bug pip + Python 3.14 (Ubuntu & Fedora)** : pip peut échouer avec
+> `FileNotFoundError` dans `certifi`. Fix : passer la variable `SSL_CERT_FILE`
+> pointant vers les CA système.
+
+```bash
+# Sur Ubuntu / meshbay.org
+SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt \
+  pip install -e packages/meshbay-common -e packages/meshbay-node httpx blake3 uvicorn
+
+# Sur Fedora (machine locale)
+SSL_CERT_FILE=/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem \
+  pip install -e packages/meshbay-common -e packages/meshbay-node httpx blake3 uvicorn
+```
+
+Une fois `certifi` correctement installé, les `pip install` suivants n'ont plus besoin de `SSL_CERT_FILE`.
+
 ---
 
 ## Étape 1 — Setup (alice crée le groupe et invite bob)
-- 
cgit v1.2.3