> For the complete documentation index, see [llms.txt](https://docs.ipcheck.ing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipcheck.ing/developer/fr/getting-started/maxmind-setup.md). # Configuration de MaxMind (obligatoire) MyIP lit deux bases de données gratuites **GeoLite2** de MaxMind — `GeoLite2-City.mmdb` et `GeoLite2-ASN.mmdb` — pour la géolocalisation IP locale hors ligne et les recherches ASN. Elles sont **défiler** dans le dépôt et **défiler** dans l'image Docker. La licence GeoLite2 de MaxMind n'autorise pas la redistribution, donc chaque déploiement doit apporter sa propre copie. ## Ce qui casse sans elles Le serveur démarre quand même. Mais : * `/api/maxmind` renvoie **503** à chaque requête, donc la source IP MaxMind ne produit rien. * Les fonctionnalités construites sur cette source — y compris les badges de pays affichés pour les candidats ICE WebRTC — restent vides. * Chaque démarrage enregistre `❌ L’API MaxMind renverra 503 jusqu’à ce que les bases de données soient chargées avec succès`. Les autres sources IP continuent de fonctionner, donc l'application semble à moitié cassée plutôt que complètement cassée. C'est précisément pourquoi cette page est une lecture obligatoire. ## Obtenir les identifiants {% stepper %} {% step %} #### Créer un compte GeoLite2 gratuit Inscrivez-vous sur [maxmind.com/en/geolite2/signup](https://www.maxmind.com/en/geolite2/signup). Aucun moyen de paiement n'est requis. {% endstep %} {% step %} #### Notez votre identifiant de compte MaxMind l'affiche dans le tableau de bord de votre compte. C'est un numéro, pas votre adresse e-mail. {% endstep %} {% step %} #### Générez une clé de licence Ouvrez **Gérer les clés de licence** et créez une nouvelle clé. Copiez-la immédiatement — MaxMind ne l'affiche qu'une seule fois. {% endstep %} {% endstepper %} ## Option A — Téléchargement automatique (recommandé) Définissez trois variables et laissez MyIP récupérer et actualiser les bases de données lui-même. {% code title=".env" %} ```bash MAXMIND_ACCOUNT_ID="your-account-id" MAXMIND_LICENSE_KEY="your-license-key" MAXMIND_AUTO_UPDATE="true" ``` {% endcode %} Dans Docker, transmettez les trois mêmes avec `-e` — voir [Déployer avec Docker](/developer/fr/getting-started/deploy-with-docker.md). Que se passe-t-il alors : | Quand | Ce qui se passe | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Au démarrage, fichiers manquants | Le backend télécharge les deux bases de données **avant de commencer à écouter**, avec une limite de 5 minutes. Cela s'exécute chaque fois que les identifiants sont présents, même si `MAXMIND_AUTO_UPDATE` est `"false"`. | | Au démarrage, fichiers présents | Rien n'est téléchargé ; les fichiers existants sont chargés immédiatement. | | \~60 secondes après le démarrage | Le programme de mise à jour exécute sa première vérification planifiée. | | Toutes les 24 heures ensuite | Il vérifie à nouveau et ne télécharge que ce que MaxMind a effectivement mis à jour. | {% hint style="success" %} **Les mises à jour sont sûres par construction.** Les nouveaux fichiers sont téléchargés dans un répertoire temporaire, ouverts et validés, puis publiés de manière atomique avec un `.bak` repli. Un observateur de fichiers recharge ensuite les lecteurs en mémoire, de sorte qu'une actualisation de base de données ne redémarre jamais le serveur et ne sert jamais de fichier partiellement écrit. Un fichier de verrouillage empêche deux processus (par exemple deux instances pm2) de mettre à jour en même temps. {% endhint %} {% hint style="warning" %} **Les déploiements Docker doivent utiliser l'option A.** Un conteneur neuf n'a aucun `.mmdb` fichier du tout, et il n'y a rien dans quoi les copier à moins de construire votre propre image. {% endhint %} ## Option B — Placement manuel Pour les hôtes isolés d'Internet, ou si vous préférez ne pas donner à l'application un accès sortant à MaxMind. Cela ne fonctionne que si vous [déployez depuis le code source](/developer/fr/getting-started/deploy-with-nodejs.md). {% stepper %} {% step %} #### Téléchargez les bases de données Depuis votre compte MaxMind, téléchargez les **GeoLite2 City** et **GeoLite2 ASN** archives au format `.mmdb` (binaire) et extrayez-les. {% endstep %} {% step %} #### Placez-les au bon endroit Copiez les deux fichiers dans `common/maxmind-db/`, en conservant exactement leurs noms : ``` common/maxmind-db/GeoLite2-City.mmdb common/maxmind-db/GeoLite2-ASN.mmdb ``` {% endstep %} {% step %} #### Laissez la mise à jour automatique désactivée ```bash MAXMIND_AUTO_UPDATE="false" ``` Puis démarrez le backend. Il trouve les fichiers et les charge. {% endstep %} {% endstepper %} {% hint style="info" %} Avec l'option B, vous actualisez vous-même les fichiers au fur et à mesure que MaxMind publie de nouvelles versions. Vous n'avez pas besoin de redémarrer le serveur après les avoir remplacés — l'observateur de fichiers détecte le changement et recharge les lecteurs en quelques secondes. {% endhint %} ## Vérification Un démarrage sain consigne : ``` 📦 MaxMind databases loaded (startup) ``` Avec la mise à jour automatique activée, vous obtenez aussi le planning : ``` 🗓️ Plan de mise à jour automatique MaxMind : prochaine vérification à ..., puis toutes les 24 heures ``` ## Dépannage
❌ L’API MaxMind renverra 503 jusqu’à ce que les bases de données soient chargées avec succès Le backend n'a pas pu ouvrir les deux `.mmdb` fichiers. Remontez dans le journal — il y a toujours une ligne plus précise au-dessus indiquant pourquoi. Causes fréquentes : * Les identifiants manquent, donc rien n'a jamais été téléchargé. * Le téléchargement a échoué (voir les entrées ci-dessous). * Un seul des deux fichiers est présent. MyIP a besoin de **les deux** City et ASN.
⚠️ Les bases de données MaxMind sont manquantes et MAXMIND_ACCOUNT_ID / MAXMIND_LICENSE_KEY ne sont pas configurés Les variables n'ont jamais atteint le processus. Vérifiez que : * Votre `.env` se trouve à la racine du projet et que vous avez redémarré après l'avoir modifié. * Dans Docker, les `-e` options sont sur la `docker run` commande (ou dans le `environment:` bloc) — et non dans `docker exec`. * Les noms de variables sont orthographiés exactement comme ci-dessus.
Échec de la vérification de GeoLite2-City : HTTP 401 MaxMind a rejeté les identifiants. L'identifiant de compte et la clé de licence sont utilisés comme authentification HTTP Basic auprès de `download.maxmind.com`, donc un 401 signifie que l'un des deux est incorrect. * Vérifiez que l'identifiant de compte est l'identifiant numérique, pas votre e-mail. * Régénérez la clé de licence — les clés peuvent être révoquées, et un copier-coller ayant supprimé un caractère ressemble exactement à une clé valide. * Assurez-vous que la clé a été créée pour **GeoLite2**, sous le même compte.
Échec du téléchargement initial de MaxMind : le téléchargement n'a pas été terminé en 5 min Le téléchargement au démarrage a atteint sa limite de temps. C'est un problème réseau, pas un problème d'identifiants — vérifiez que l'hôte peut atteindre `download.maxmind.com` (pare-feu, règles de sortie, proxy). Le serveur démarre quand même et le programme de mise à jour planifié réessaiera.
Plan de mise à jour automatique MaxMind : désactivé `MAXMIND_AUTO_UPDATE` n'est pas exactement `"true"`. Seule cette valeur littérale active l'actualisation périodique. Notez que cela concerne la **actualisation toutes les 24 heures** seulement. Le téléchargement au démarrage s'exécute toujours lorsque les fichiers sont manquants et que les identifiants sont présents.
Mise à jour automatique MaxMind ignorée : MAXMIND_ACCOUNT_ID ou MAXMIND_LICENSE_KEY est manquant La mise à jour automatique a été demandée mais l'un des deux identifiants est vide. Les deux sont requis.
Mise à jour MaxMind ignorée : un autre processus met à jour les bases de données Attendu lorsque vous exécutez plusieurs instances du backend — l'une détient le verrou de mise à jour, les autres s'écartent. Sans danger. Si vous le voyez à chaque tentative, une exécution précédente a probablement planté et laissé le verrou derrière elle. Il est supprimé automatiquement une fois qu'il a 2 heures ; pour le supprimer maintenant, supprimez `.maxmind-update.lock` depuis `common/maxmind-db/`.
## Étapes suivantes * [Déployer avec Docker](/developer/fr/getting-started/deploy-with-docker.md) — où se trouvent les bases de données dans le conteneur * [Clés API facultatives](/developer/fr/configuration/optional-api-keys.md) — sources de données IP supplémentaires au-delà de MaxMind * [Sources de données IP](/developer/fr/architecture/ip-data-sources.md) — comment MyIP combine ses sources --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.ipcheck.ing/developer/fr/getting-started/maxmind-setup.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.