Sujets Transverses

Conventions de nommage

Domaines

• Wildcard 33800 : *.33800.nowhere84.com → 82.65.119.221 (Bordeaux)
• Wildcard 86000 : *.86000.nowhere84.com → 82.67.42.47 (Raph - Poitiers)
• Format : {projet}-{service}-{env}.{stack}.nowhere84.com
• Exemples :
  • api.33800.nowhere84.com
  • grafana.33800.nowhere84.com
  • dashboard.nowhere84.com (O2switch)
  • future-service.86000.nowhere84.com (chez Raph)

Branches Git

Fichiers

ATTENTION : Le fichier de config est conf.{branch}.gouroubleu.yml (ex: conf.prod.gouroubleu.yml, conf.dev.gouroubleu.yml), PAS conf.gouroubleu.yml sans préfixe.

Schemas PostgreSQL

Convention : 1 projet = 1 schema dédié

Avantages :

• Isolation des données par projet
• Backup/restore simple : pg_dump --schema=X
• Nettoyage facile si projet abandonné

Ports standards

URLs importantes

Environnements

PROD

• Machine : prod-portainer (192.168.1.12)
• Docker data-root : /mnt/stock_8to/33800-stack/docker/prod/
• Secrets : /stock_8to/33800-stack/docker/secrets/prod.env
• Branche : main

DEV

• Machine : dev-portainer (192.168.1.51)
• Docker data-root : /stock_1to/dev-stack/docker/
• Secrets : /stock_8to/33800-stack/docker/secrets/dev.env
• Branche : develop

Bonnes pratiques

Déploiement

1. Code sur GitLab (jamais déployer manuellement)
2. CI/CD build et push vers registry
3. Smart-deploy avec health check
4. Rollback automatique si échec

Logging

1. Tous services → Loki
2. Labels : env, host, type, service
3. Rétention : 30j hot, 90j cold (O2switch)

Backup

1. stock_8to → stock_36to (rsync horaire)
2. GitLab → backup 6h
3. Snapshots ZFS manuels si besoin

Sécurité

1. SSL wildcard sur tous les services
2. Pas de credentials en clair dans le code
3. Secrets dans prod.env / dev.env
4. Validation avant actions destructives

URLs dans le code (CRITIQUE)

JAMAIS d'IP:port dans le code applicatif (callbacks, webhooks, URLs internes). Toujours utiliser les domaines HTTPS *.33800.nowhere84.com. Le split-DNS Pi-hole résout vers nginx en local automatiquement. Voir pihole-split-dns.md pour détails.

Ordre des opérations (CRITIQUE)

Règle : Toujours MIGRER/SAUVEGARDER avant SUPPRIMER

Exemple migration DEV → PROD :

1. Backup des données actuelles
2. Créer la cible (schema PROD, etc.)
3. Migrer les données vers PROD
4. Vérifier que PROD fonctionne
5. SEULEMENT APRÈS : nettoyer/supprimer DEV

JAMAIS supprimer avant d'avoir sécurisé les données ailleurs.

NE PAS CASSER CE QUI FONCTIONNE

Règle : Après une migration (DEV→PROD, changement d'IP, etc.), TOUJOURS mettre à jour :

1. Scripts de génération dashboard (generate.d/*.sh, generate-*.sh)
2. Configs avec IPs hardcodées
3. Fichiers de test/monitoring

Fichiers critiques avec IPs : | Fichier | Variable | Vérifier après migration | |---------|----------|--------------------------| | generate-needfinder.sh | API_URL | IP PROD NeedFinder | | generate.d/20-ai-jobs.sh | PROD_IP | IP prod-portainer | | collect.sh | Hosts | IPs des serveurs |

AVANT de modifier un fichier qui fonctionne :

1. Vérifier qu'on ne casse pas une fonctionnalité existante
2. Tester localement si possible
3. Garder une copie du fichier original

Proxy frontend → API (connectors-front)

IMPORTANT — PIÈGE RÉCURRENT : Le frontend (connectors-front.33800.nowhere84.com) et l'API (connectors.33800.nowhere84.com) sont sur des domaines différents. Toute URL relative /api/... dans le HTML rendu côté front sera résolue sur le domaine du front, PAS sur l'API.

Solution : entry.express.tsx contient un proxy Express qui forward certaines routes /api/* vers l'API backend. Quand on ajoute un nouveau endpoint API consommé par des URLs relatives dans le HTML (images, streams, fichiers), il FAUT ajouter la route proxy dans entry.express.tsx.

Routes proxy existantes :

• /api/ai/attachments/:id/file/* → proxy vers API (fichiers joints chat)
• /api/stream/* → proxy vers API (images/videos Jellyfin, médias)

Fichier : connectors-front/src/entry.express.tsx — fonction proxyToApi

Règle : Toute nouvelle URL relative /api/... utilisée dans un src, href, ou img côté front → ajouter dans le proxy Express.