Dépanner la base intégrée du Hub

Mémoire trop petite, disque plein, « la base intégrée n'a pas démarré » : les messages de la console quand la base de données du Hub, installée dans ton serveur de panel, pose problème, et le geste qui les corrige.

Mis à jour le 4 oct. 2026, 17 h 45

Sur cette page

Avant de commencer
Étapes
Tu sais que c'est réussi quand…
Si ça ne marche pas
Les messages d'erreur (ligne ✗)
Les avertissements et les lignes normales
Pour aller plus loin
Où est la base, et ce qu'elle expose
Arrêter et couper
La copie de fichiers du panel n'est pas une sauvegarde
Passer à une base PostgreSQL externe (option avancée)
Les chiffres à retenir

En bref. Quand tu installes Agora par un œuf de panel, ou sur un serveur Node.js, le Hub fournit sa propre base de données PostgreSQL à l'intérieur de ton serveur : c'est la « base intégrée ». Elle démarre toute seule. Si elle n'y arrive pas, la console du panel le dit en rouge (✗), avec une ligne de conseil (→). Cette page traduit chaque message en geste à faire.

Avant de commencer #

Vérifie que tu utilises bien la base intégrée. C'est le cas quand la variable Base de donnees (DATABASE_URL) du serveur est vide, ou, sur un serveur Node.js, quand agora.env ne contient pas de ligne DATABASE_URL. Si tu as renseigné une base PostgreSQL toi-même, cette page ne te concerne pas : relis Les deux bases d'Agora et les questions fréquentes.
Garde la console du panel ouverte : c'est là que tout s'affiche.
Les mots (panel, console, PostgreSQL, quota) sont dans le glossaire.

Étapes #

Ouvre la console du serveur dans ton panel et remonte jusqu'à l'étape [5/6] Base de données — base intégrée, puis migrations. C'est l'étape où la base se prépare.
Cherche la première ligne rouge. Elle commence par ✗ ; la ligne suivante, précédée de →, donne le conseil. Les lignes avec un ! orange sont des avertissements : le démarrage continue.
Retrouve le message dans le tableau ci-dessous et applique le geste.
Redémarre le serveur avec Start. Le démarrage reprend là où il s'est arrêté : une base déjà créée n'est jamais effacée, et un démarrage interrompu se reprend tout seul.

Tu sais que c'est réussi quand… #

La console affiche ✓ base PostgreSQL intégrée prête, puis ✓ schéma à jour, puis ✓ Ready in ….
L'adresse /api/health de ton Hub répond "ok": true et "db": "ok".

Si ça ne marche pas #

Les messages d'erreur (ligne `✗`) #

Message dans la console	Ce que ça veut dire	Que faire
`mémoire du serveur trop petite pour la base intégrée (… Mo)`	Le serveur dispose de moins de 768 Mo : Agora et sa base ne tiennent pas	Dans l'administration du panel, donne 2 Go de mémoire au serveur (1,5 Go au minimum), puis redémarre
`pas assez de place sur le disque pour la base intégrée (… Mo libres, 400 Mo nécessaires)`	Premier démarrage : le disque du serveur est trop petit	Augmente le disque du serveur à 5 Go (10 Go sont plus confortables), puis redémarre
`plus de place sur le disque pour créer la base intégrée`	Le disque s'est rempli pendant la création de la base	Même geste : augmente le disque, redémarre
`pas de base intégrée pour cette machine (…)`	Le serveur n'est pas un Linux 64 bits Intel/AMD standard (ARM, ou image sans glibc)	La base intégrée ne marche pas ici : choisis une autre machine, ou apporte une base PostgreSQL (voir plus bas)
`téléchargement de PostgreSQL impossible : …`	Le serveur ne joint pas `registry.npmjs.org`	Vérifie la sortie Internet du serveur (DNS, pare-feu), puis redémarre. Si ça se répète, apporte ta propre base
`installation de PostgreSQL impossible : …`	L'extraction a échoué, souvent faute de place	Libère de la place (400 Mo libres au premier démarrage), puis redémarre
`création de la base intégrée impossible (initdb)`	PostgreSQL n'a pas pu initialiser ses fichiers	Lis la ligne `Détail :` juste dessous ; si elle ne parle pas de disque ou de mémoire, ouvre un billet avec cette ligne : voir Ouvrir un billet de support
`création de la base « agora » impossible` ou `mot de passe de la base intégrée non reposé`	Une étape de préparation a échoué	Redémarre une fois. Si ça se répète, ouvre un billet avec la ligne `Détail :`
`la base intégrée ne peut pas tourner en administrateur (root)`	Le serveur lance Agora en `root`, ce que PostgreSQL refuse	Sur un panel, c'est normalement un utilisateur ordinaire : demande à l'administrateur du panel, ou apporte ta propre base
`dossier de données inadapté à la base intégrée (…)`	Le chemin du dossier de données est trop long ou contient des caractères inhabituels	Garde les dossiers par défaut (`/home/container`) ; sinon ouvre un billet
`la base intégrée n'a pas démarré`	PostgreSQL a été lancé mais ne répond pas. Les dernières lignes de son journal (`postgres.log`) suivent	Cause la plus fréquente : mémoire ou disque insuffisants. Augmente l'un ou l'autre, redémarre ; lis les lignes affichées, elles nomment souvent la cause
`la base de données n'a pas répondu`, dans l'étape des migrations	La base s'est arrêtée en route, ou n'a pas eu le temps de répondre. Le conseil affiché parle de `DATABASE_URL` : avec la base intégrée, ce n'est pas la cause (la variable doit rester vide)	Redémarre. Si ça revient, regarde la mémoire (le panel a pu arrêter le processus) et les lignes `postgres.log`
`sauvegarde de la base impossible : les migrations n'ont PAS été appliquées`	La sauvegarde d'avant migration n'a pas pu s'écrire (disque plein)	Libère ou ajoute de l'espace, puis redémarre : la sauvegarde sera retentée avant de migrer

Les avertissements et les lignes normales #

Message dans la console	Ce que ça veut dire	Que faire
`! mémoire juste (… Mo) : avec la base intégrée, 1,5 Go sont un minimum et 2 Go sont recommandés`	Le serveur démarre, mais il manque de marge : le panel peut l'arrêter	Passe à 2 Go de mémoire
`! disque presque plein (… Mo libres) : la base risque de s'arrêter`	Moins de 100 Mo libres	Libère de la place (anciennes sauvegardes) ou augmente le disque
`première installation de la base intégrée (scram-sha-256, aucune écoute réseau)…`	Normal au tout premier démarrage	Rien : la base se crée
`initialisation de la base interrompue au démarrage précédent : cluster vide effacé, on recommence`	Le serveur a été coupé pendant la toute première création de la base, qui n'avait encore rien contenu	Rien : elle est refaite
`verrou PostgreSQL orphelin (arrêt brutal) : retiré, la base rejouera son journal`	Le serveur a été coupé brutalement (Kill, mémoire, coupure)	Rien : PostgreSQL se rétablit tout seul
`mot de passe de la base intégrée introuvable : un nouveau est posé`	Le fichier du mot de passe a été perdu	Rien : un nouveau est posé, tes données sont gardées
`la base intégrée ne tourne plus : redémarrage`	PostgreSQL s'est arrêté en route (souvent faute de mémoire) ; Agora le relance	Rien si la ligne `base de données redémarrée` suit ; sinon vois la mémoire du serveur

Pour aller plus loin #

Où est la base, et ce qu'elle expose #

Ses données sont dans le dossier .agora/pg du serveur (dossier data/pg sur un serveur Node.js). C'est le seul dossier qui survit aux redémarrages.
Elle n'écoute sur aucun port réseau : elle ne parle à Agora que par un fichier local. Il n'y a rien à ouvrir au pare-feu, et rien n'est atteignable depuis Internet.
Son mot de passe est tiré au sort une fois, rangé dans un fichier fermé et jamais affiché.
Son journal, postgres.log, est borné (environ 5 Mo). Quand la base intégrée n'a pas démarré, la console en recopie les dernières lignes. Le dossier .agora est fermé au gestionnaire de fichiers du panel : n'attends donc pas de l'y ouvrir, mais ces lignes de la console suffisent.

Arrêter et couper #

Stop laisse Agora s'arrêter d'abord, puis la base : tu vois arrêt demandé puis base de données arrêtée proprement. Laisse-lui quelques secondes.
Kill (ou une coupure) est brutal mais sans danger pour les données : au démarrage suivant, PostgreSQL rejoue son journal tout seul.

La copie de fichiers du panel n'est pas une sauvegarde #

La sauvegarde du serveur, l'archive du dossier ou une copie par SFTP copient la base pendant qu'elle écrit : le résultat est incohérent, souvent inutilisable à la restauration. Et la copie contient le mot de passe de la base. Fais d'abord une sauvegarde d'Agora (un fichier .sql) et télécharge-la hors du serveur : voir Sauvegardes et restauration.

Passer à une base PostgreSQL externe (option avancée) #

À réserver au cas où la base intégrée ne peut pas tourner chez toi. Le principe : sauvegarder, changer de base, restaurer.

Dans Administration → Agora → Sauvegardes, crée une sauvegarde et télécharge le fichier .sql hors du serveur.
Crée ta base PostgreSQL externe (vide) et son utilisateur, chez ton hébergeur de bases.
Colle son adresse (postgresql://utilisateur:motdepasse@hote:5432/base?schema=public) dans la variable Base de donnees, puis redémarre. Agora démarre sur cette base vide comme une installation neuve.
Passe la mise en route si elle s'affiche, puis restaure le .sql dans Administration → Agora → Sauvegardes. La restauration est réservée au propriétaire de l'installation.
Quand tout marche, l'ancien dossier .agora/pg n'est plus utilisé : tu peux le supprimer pour libérer la place.

Poser DATABASE_URL ne touche pas à l'ancien dossier : si tu vides de nouveau la variable, tu retrouves l'ancienne base intégrée telle que tu l'avais laissée. Pour revenir de l'externe vers l'intégrée, même marche à suivre à l'envers.

Les chiffres à retenir #

	Valeur
Mémoire conseillée	2 Go
Mémoire minimale	1,5 Go (sous 768 Mo, Agora refuse de lancer la base)
Disque	5 Go ; 400 Mo libres au premier démarrage
Plateforme	Linux 64 bits Intel/AMD avec glibc (l'image Node standard d'un panel)

Cet article t'a aidé ?