Installation

Guide rapide : voir Guide Démarrage Rapide (installation en 2 minutes).

Termes techniques : voir Glossaire pour uv, S3, Docker, etc.

Prérequis

  • Python 3.13.7

  • uv (gestionnaire de paquets)

  • Accès S3 (Garage Storage) - voir Stockage S3 Garage

Installation Locale

1. Cloner le Repository

git clone https://github.com/julienlafrance/backtothefuturekitchen.git ~/mangetamain
cd ~/mangetamain/10_preprod

2. Créer l’Environnement Virtuel

uv sync

Cette commande installe automatiquement toutes les dépendances définies dans pyproject.toml.

3. Configuration S3

Copier les credentials S3 dans 96_keys/credentials :

[s3fast]
aws_access_key_id = YOUR_KEY
aws_secret_access_key = YOUR_SECRET

Les données sont chargées automatiquement depuis S3 au démarrage de l’application.

4. Lancer l’Application

uv run streamlit run src/mangetamain_analytics/main.py

L’application est accessible sur http://localhost:8501

Installation avec Docker

1. Cloner le Repository

git clone https://github.com/julienlafrance/backtothefuturekitchen.git ~/mangetamain
cd ~/mangetamain/30_docker

2. Lancer avec Docker Compose

# Environnement PREPROD (port 8500)
docker-compose up -d

# OU Environnement PRODUCTION (port 8501)
docker-compose -f docker-compose-prod.yml up -d

Accès aux Environnements

Volumes Docker

Les volumes Docker mappent le code local vers le conteneur :

Avantages :

  • Code source en lecture seule (évite modifications accidentelles)

  • Modifications visibles immédiatement (hot reload Streamlit)

  • Données DuckDB persistantes

Gestion Docker

Voir les logs :

docker-compose logs -f mangetamain_preprod

Redémarrer après nouvelle dépendance :

# 1. Ajouter dépendance localement
cd ~/mangetamain/10_preprod
uv add nouvelle-dependance

# 2. Redémarrer conteneur
cd ~/mangetamain/30_docker
docker-compose restart

Arrêter les services :

docker-compose down

Reconstruire complètement :

docker-compose up -d --force-recreate --build

Debug Docker

Entrer dans le conteneur :

docker-compose exec mangetamain_preprod bash
# Puis dans le conteneur:
uv run python -c "import streamlit; print(streamlit.__version__)"

Vérifier santé du conteneur :

docker-compose ps
# Doit afficher: healthy

Logs en temps réel :

docker-compose logs -f --tail=100

Workflow Développement Docker

  1. Modifier code : Éditer fichiers dans 10_preprod/src/

  2. Voir changements : Streamlit recharge automatiquement

  3. Ajouter dépendance : uv add package puis docker-compose restart

  4. Debug : docker-compose logs -f ou entrer dans conteneur

Nettoyage

Arrêter et supprimer conteneur :

docker-compose down

Nettoyage complet (images, volumes, réseaux) :

docker system prune -a
# Attention: Supprime TOUTES les images Docker inutilisées

Tests

Lancer les Tests Unitaires

cd ~/mangetamain/10_preprod
uv run pytest tests/unit/ -v --cov=src

Résultat attendu : 93% coverage (118 tests)

Vérifier la Qualité du Code

# PEP8
uv run flake8 src/ tests/ --config=../.flake8

# Formatage
uv run black --check src/ tests/

# Docstrings
uv run pydocstyle src/ --config=../.pydocstyle

Dépendances Principales

  • streamlit >= 1.50.0

  • plotly >= 5.24.1

  • pandas >= 2.2.3

  • numpy >= 2.2.6

  • duckdb >= 1.4.0

  • polars >= 1.19.0

  • loguru >= 0.7.3

  • pytest >= 8.5.0 (dev)

  • pytest-cov >= 6.0.0 (dev)

La liste complète est disponible dans 10_preprod/pyproject.toml.

Vérification de l’Installation

Vérifier uv

uv --version
# Attendu: uv 0.8.22 ou supérieur

Si uv n’est pas installé :

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Vérifier Python

python3 --version
# Attendu: Python 3.13.7

Le projet nécessite Python 3.13+ pour compatibility avec toutes les dépendances.

Vérifier l’Environnement

Après uv sync, vérifier que l’environnement est activé :

uv run python --version
# Attendu: Python 3.13.7

uv run python -c "import streamlit; print(streamlit.__version__)"
# Attendu: 1.50.0 ou supérieur

Vérifier S3

Tester la connexion S3 :

cd ~/mangetamain/50_test
pytest test_s3_parquet_files.py -v

Si le test échoue, vérifier :

  1. Le fichier 96_keys/credentials existe et contient les bonnes clés

  2. L’endpoint S3 est accessible : ping s3fast.lafrance.io

  3. Les règles iptables DNAT sont configurées (si applicable)

Voir : Stockage S3 Garage pour configuration détaillée S3 Garage.

Troubleshooting

Erreur : « uv: command not found »

Solution : Installer uv avec le script officiel :

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.cargo/env  # Recharger le PATH

Erreur : « Python 3.13 not found »

Solution : uv peut installer Python automatiquement :

uv python install 3.13

Ou installer manuellement depuis https://www.python.org/downloads/

Erreur : « No credentials found »

Symptôme : Message « Credentials S3 introuvables » dans l’app

Solution :

  1. Créer le répertoire : mkdir -p 96_keys

  2. Créer le fichier 96_keys/credentials avec format INI :

[s3fast]
aws_access_key_id = VOTRE_CLE
aws_secret_access_key = VOTRE_SECRET

  1. Vérifier les permissions : chmod 600 96_keys/credentials

Erreur : « Connection timeout » S3

Causes possibles :

  1. Réseau : Vérifier la connectivité : curl -I http://s3fast.lafrance.io

  2. Firewall : Vérifier que le port 80 est ouvert

  3. DNAT : Configurer le bypass pour performance maximale

Solution DNAT (optionnelle, gain 10x performance) :

sudo iptables -t nat -A OUTPUT -p tcp -d 192.168.80.202 --dport 80 \\
     -j DNAT --to-destination 192.168.80.202:3910

Voir : Stockage S3 Garage section « Optimisation Performance DNAT ».

Erreur : Tests pytest échouent

Solution :

  1. Vérifier que l’environnement est à jour :

cd ~/mangetamain/10_preprod
uv sync
uv run pytest --version  # Attendu: pytest 8.5.0+

  1. Lancer les tests avec verbosité :

uv run pytest tests/unit/ -vv

  1. Si un module spécifique échoue, tester isolément :

uv run pytest tests/unit/test_color_theme.py -v

Port 8501 déjà utilisé

Symptôme : « Address already in use » au démarrage

Solution :

  1. Identifier le processus utilisant le port :

# Linux/macOS
lsof -i :8501

# Windows
netstat -ano | findstr :8501

  1. Arrêter le processus ou utiliser un autre port :

uv run streamlit run src/mangetamain_analytics/main.py --server.port 8502

Application charge lentement

Premier lancement : 5-10 secondes (chargement S3 normal)

Lancements suivants lents : Vérifier le cache Streamlit

Solution :

  1. Dans l’app, cliquer menu (⋮) > « Clear cache »

  2. Ou supprimer le cache manuellement :

rm -rf ~/.streamlit/cache

Performance S3 < 100 MB/s

Solution : Configurer DNAT bypass pour atteindre 500-917 MB/s

Voir : Stockage S3 Garage section « DNAT Bypass Performance ».

Ressources Supplémentaires