Portabase : Sauvegarde automatique de bases de données en auto-hébergé

Vous avez un script pg_dump qui tourne dans un coin de votre cron, et vous espérez ne jamais avoir à vous en servir — ou pire, vous n'avez rien du tout. La réalité des sauvegardes de bases de données, c'est qu'elles sont trop souvent bricolées, oubliées, ou confiées à des SaaS tiers qui stockent vos credentials quelque part dans un cloud que vous ne contrôlez pas. Portabase change la donne : une interface centralisée, un agent léger, un déploiement Docker en moins de 30 minutes, et une restauration en un clic.

Qu'est-ce que Portabase ?

Portabase est un outil open source de sauvegarde et restauration de bases de données, prenant actuellement en charge PostgreSQL, MySQL, SQLite, MsSQL, MariaDB et MongoDB.

L'écosystème Portabase repose sur trois composants principaux :

• Le dashboard : une interface web qui sert de plan de contrôle central pour toutes les opérations de sauvegarde et de restauration. On y enregistre les agents, configure les politiques de rétention, consulte l'historique et surveille l'espace de stockage.
• Les agents : des connecteurs légers déployés sur les hôtes hébergeant les bases de données. Ils opèrent en mode outbound pull, ce qui signifie qu'ils n'exposent aucun port entrant — vos bases ne sont jamais accessibles depuis l'extérieur.
• La CLI : un utilitaire en ligne de commande qui automatise l'installation et la configuration du dashboard et des agents.

Fait notable : l'agent, initialement écrit en Python, a été entièrement réécrit en Rust, tirant parti du runtime asynchrone Tokio. Cette réécriture réduit la taille de l'image Docker par 4, minimise les erreurs à l'exécution et garantit des opérations de sauvegarde et restauration fiables et concurrentes.

Côté licence, Portabase est distribué sous Apache-2.0 : gratuit, sans frais cachés, et auditables ligne à ligne.

Prérequis avant de déployer

Avant de lancer votre premier docker compose up, vérifiez que votre environnement remplit les conditions suivantes :

• Docker & Docker Compose v20+ (Compose file format v3.8 minimum)
• Serveur Linux / VPS avec au moins 2 Go de RAM et 10 Go de disque (plus selon le volume de données à sauvegarder)
• Accès aux bases de données que vous souhaitez protéger (PostgreSQL, MySQL/MariaDB, MongoDB,...)
• Connaissances de base en YAML — pas de panique, tout est commenté

Optionnel mais recommandé pour la production :

• Un reverse proxy (Traefik ou Nginx) avec terminaison TLS
• Un bucket S3 ou une instance MinIO pour le stockage des dumps
• Un compte SMTP, une instance NTFY ou un webhook Slack/Discord pour les notifications

Création d'un sous-domaine pour accéder à portabase

Mon domaine étant hébergé chez OVH, je dois créer mon sous-domaine depuis leur interface. Il faut aller dans WebCloud → Zones DNS → Ajouter une entrée

J'utilise un CNAME car je ne dispose pas d'adresse IP fixe. J'utilise la fonctionnalité DynHost de OVH et le client sur ma Livebox pour héberger des applications chez-moi

Déploiement via Docker Compose

Structure du projet

Créez un répertoire dédié et placez-y deux fichiers : docker-compose.yml et .env.

mkdir ~/portabase && cd ~/portabase

Pour ma part j'utilise Portainer pour gérer mes stacks.

Je n'utilise plus le fichier docker-compose.yml, tout se fait via l'interface graphique de Portainer. Vous devez aller dans Stacks → Editor

De plus on peut gérer les variables d'environnement d'un stack directement dans Portainer. Vous devez aller dans Stacks → Environment variables

Le fichier docker-compose commenté

Voici un exemple commenté du fichier docker compose de Portabase. Retrouver celui que j'utilise sur mon compte github : github-portabase

name: portabase

services:

  # ─────────────────────────────────────────────
  # Service principal : le dashboard Portabase
  # ─────────────────────────────────────────────
  portabase:
    image: solucetechnologies/portabase:latest
    env_file:
      - .env                         # Toutes les variables sensibles dans un fichier séparé (Inutile si vous utiliser Portainer)
    ports:
      - '8887:80'                    # Exposez uniquement en local si vous utilisez un reverse proxy
    environment:
      - TIME_ZONE="Europe/Paris"     # Adaptez à votre fuseau horaire
    volumes:
      - portabase-private:/app/private  # Stockage des clés internes et données privées
    depends_on:
      db:
        condition: service_healthy   # Attend que PostgreSQL soit prêt avant de démarrer
    container_name: portabase-app
    restart: unless-stopped

  # ─────────────────────────────────────────────
  # Base de données interne de Portabase
  # (stocke les métadonnées, PAS vos backups)
  # ─────────────────────────────────────────────
  db:
    image: postgres:17-alpine
    ports:
      - "5433:5432"                  # Port 5433 côté hôte pour éviter les conflits
    volumes:
      - postgres-data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=portabase
      - POSTGRES_USER=portabase_user
      - POSTGRES_PASSWORD=YOUR_DB_PASSWORD   # Remplacez par un mot de passe fort
    healthcheck:
      # pg_isready vérifie que PostgreSQL accepte des connexions
      # interval : fréquence des vérifications
      # retries : nombre de tentatives avant de déclarer le service unhealthy
      test: ["CMD-SHELL", "pg_isready -U portabase_user -d portabase"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  postgres-data:        # Persistance des données PostgreSQL internes
  portabase-private:    # Persistance des fichiers privés du dashboard

Pourquoi service_healthy sur depends_on ? Sans cette condition, le conteneur Portabase pourrait démarrer avant que PostgreSQL soit prêt à accepter des connexions, ce qui provoque une erreur au lancement. Le healthcheck via pg_isready garantit l'ordre correct.

Le fichier .env commenté

# ── Environnement ──────────────────────────────
NODE_ENV=production

# ── Connexion à la BDD interne ─────────────────
DATABASE_URL=postgresql://portabase_user:YOUR_DB_PASSWORD@db:5432/portabase?schema=public

# ── Identité du projet ─────────────────────────
PROJECT_NAME="Portabase - NetworkPulse"
PROJECT_URL=https://backup.your-domain.com   # URL publique si reverse proxy activé
PROJECT_SECRET=YOUR_SECRET                   # Générez via : openssl rand -hex 32

# ── Exemple de configuration pour stockage des sauvegardes (S3 / MinIO) ──────
STORAGE_TYPE=s3
S3_ENDPOINT=https://s3.your-domain.com
S3_ACCESS_KEY=YOUR_S3_ACCESS_KEY
S3_SECRET_KEY=YOUR_S3_SECRET_KEY
S3_BUCKET_NAME=portabase-backups
S3_USE_SSL=true

# ── Notifications par mail (optionnel) ──────────────────
SMTP_HOST=smtp.your-domain.com
SMTP_PORT=587
SMTP_USER=alerts@your-domain.com
SMTP_PASSWORD=YOUR_SMTP_PASSWORD
SMTP_FROM=portabase@your-domain.com

# ── Rétention : nettoyage quotidien à 2h du matin ─
RETENTION_CRON="0 2 * * *"

⚠️ Ne commitez jamais votre .env dans Git. Ajoutez-le à votre .gitignore immédiatement.

Lancement

docker compose up -d
docker compose logs -f   # Suivez les logs en temps réel

Le dashboard est accessible sur http://localhost:8887 (ou votre domaine si vous avez configuré un reverse proxy). Le premier utilisateur inscrit obtient automatiquement les droits administrateur.

⚠️ Au premier démarrage de l'application vous devez créer un compte en cliquant sur Sign up.

Paramétrer votre application

Avant de vous lancer dans la sauvegarde de vos bases, voici les premiers paramètres à réaliser.

Définir une Organisation

Si vous gérer plusieurs serveurs avec plusieurs agents, je vous conseille de créer des Organisations pour classer vos sauvegardes. Par exemple pour ma part j'ai créé une organisation par serveur.

Pour créer une organisation, vous devez cliquer sur Create organization en dessous du log de Portabase sur la page d'accueil. Je n'utilise pas l'organisation par defaut.

Ma nomenclature est la suivante : LIEUX-NOM-SERVEUR

Création d'une notification

Attention, si vous gérez des organisations dans Portabase, chaque système de notification et stockage devra être recréés dans chaque organisation.

Pour l'envoie de notifications, j'utilise NTFY. Aller dans Organization → Settings → Notifiers → Add notification channel → ntfy.sh

Si comme moi vous avez une instance auto-hébergée, vous pouvez l'utiliser.

Définir un lieu de stockage

Dans ma configuration les sauvegardes des bases sont stockées localement, puis synchroniser sur mon compte Pcloud.

Par défaut le stockage local est sélectionné. Dans Organization → Settings → Storage

Le fichier databases.json : le registre de l'agent

Derrière l'interface graphique se cache un fichier JSON que l'agent lit au démarrage pour savoir exactement quelles bases de données il doit prendre en charge : databases.json. C'est la source de vérité de l'agent, sans lui, aucune sauvegarde n'est possible, car l'agent ne connaît vos bases que par ce fichier.

Ce fichier est monté dans le conteneur agent via un volume Docker. Il doit être placé sur l'hôte et référencé dans le docker-compose.yml de l'agent.

Lorsque vous rajoutez une base à sauvegarder dans le fichier databases.json, inutile de redémarrer le container, il découvre immédiatement la nouvelle base et la remonte dans le dashboard de Portabase que l'agent soit local ou distant.

Anatomie de databases.json

Voici un exemple couvrant trois types de bases supportés par Portabase, avec chaque champ commenté :

{
  "databases": [
    {
      "name": "MySQL App",          // Nom affiché dans le dashboard
      "database": "mydb",           // Nom de la base de données cible
      "type": "mysql",              // Type : "mysql", "postgresql", "mariadb", "mongodb", "sqlite"
      "host": "db-container",       // Hôte : nom de conteneur Docker, IP, ou "host-gateway" pour l'hôte local
      "port": 3306,                 // Port d'écoute du moteur (3306 MySQL, 5432 PostgreSQL, 27017 MongoDB)
      "username": "user",           // Utilisateur de connexion (idéalement dédié, droits minimaux)
      "password": "YOUR_PASSWORD",  // ⚠️ Remplacez par votre mot de passe — ne publiez jamais cette valeur
      "generated_id": "UUID-1"      // UUID unique obligatoire — identifiant interne de la base dans Portabase
    },
    {
      "name": "PostgreSQL App",
      "database": "postgres",
      "type": "postgresql",
      "host": "db-portabase",       // Peut pointer vers un conteneur sur le même réseau Docker
      "port": 5432,
      "username": "user",
      "password": "YOUR_PASSWORD",
      "generated_id": "UUID-2"
    },
    {
      "name": "SQLite App",
      "type": "sqlite",
      "path": "/data/app.sqlite",   // Chemin absolu du fichier SQLite DANS le conteneur agent
      "generated_id": "UUID-3"      // Pour SQLite, pas de host/port/username : c'est un fichier local
    }
  ]
}

Détail des champs clés

name saisissez le nom que vous donnez à votre sauvegarde. Ce nom est important car il sera affiché sur votre dashboard.

database c'est le nom de la base de données à sauvegarder

type détermine le moteur utilisé pour effectuer le dump. Portabase appellera mysqldump, pg_dump, mongodump ou lira directement le fichier selon la valeur renseignée. Une erreur ici et l'agent ne sait pas comment sauvegarder votre base.

host accepte plusieurs formes : un nom de service Docker (si l'agent et la base partagent le même réseau Compose), une adresse IP, ou host-gateway si la base tourne directement sur l'hôte Linux sans Docker. C'est la combinaison avec extra_hosts: host-gateway expliquée plus haut qui rend ce dernier cas possible.

port doit correspondre au port interne du conteneur ou du service, pas au port réexposé sur l'hôte. Si votre PostgreSQL tourne sur 5433 côté hôte mais 5432 côté conteneur, c'est 5432 qu'il faut indiquer ici.

path est exclusif à SQLite. Il pointe vers le fichier de base de données tel qu'il est vu depuis l'intérieur du conteneur agent. Si votre fichier .sqlite est sur l'hôte, montez-le en volume dans l'agent avant de renseigner ce chemin.

generated_id est un UUID v4 que Portabase utilise comme clé d'identification stable de la base dans son historique de sauvegardes. Il ne doit jamais changer une fois défini, sous peine de perdre le lien avec les snapshots existants. Générez-en un par base via uuidgen ou un générateur en ligne comme Online UUID Generator

Configuration de l'agent

L'agent est le composant qui s'exécute près de vos bases de données pour effectuer les sauvegardes et les restaurations réelles. Il peut tourner sur le même hôte que vos bases ou sur un serveur distant.

Déploiement de l'agent via Docker Compose

services:
  agent-portabase:
    image: solucetechnologies/portabase-agent:latest
    container_name: agent-portabase
    restart: unless-stopped
    environment:
      - EDGE_KEY=YOUR_EDGE_KEY   # Clé générée depuis le dashboard (voir ci-dessous)
    volumes: 
      - ./databases.json:/app/databases.json:ro # Montage en lecture seule
    extra_hosts:
      - "host-gateway:host-gateway"  # Permet à l'agent d'atteindre les services sur l'hôte

À quoi sert extra_hosts: host-gateway ? Si vos bases de données tournent directement sur la machine hôte (pas dans Docker), l'agent doit pouvoir les joindre depuis son conteneur. host-gateway est une entrée DNS spéciale qui résout vers l'IP de l'interface réseau de l'hôte, l'équivalent de host.docker.internal sur Docker Desktop, mais natif sur Linux.

Obtenir l'EDGE_KEY

1. Connectez-vous au dashboard Portabase
2. Naviguez vers Administration → Agents → Create Agent
3. Copiez la clé générée et collez-la dans votre .env ou directement dans le docker-compose.yml de l'agent

L'EDGE_KEY est le secret partagé qui authentifie l'agent auprès du dashboard. Ne la partagez jamais et régénérez-la si vous soupçonnez une compromission.

Tous vos agents se trouvent dans Administration → Agents

Automatiser les sauvegardes de vos bases de données

C'est ici que Portabase brille vraiment. Depuis le dashboard :

1. Allez dans Projects → Create Project
2. Choisissez la base de données cible et l'agent exécutant
3. Définissez le planning en syntaxe cron, par exemple 0 0 * * * pour tous les jours à minuit par exemple
4. Configurez les notifications et sur quels évènements vous souhaitez en recevoir (Error Backup, Success Backup, ...)
5. Configurez la rétention : nombre de backups à conserver ou durée (ex. 30 jours)
6. Sélectionnez le backend de stockage : dossier local, bucket S3, ou MinIO
7. Enregistrez la politique — les sauvegardes démarrent au prochain créneau planifié

Portabase prend également en charge les notifications via SMTP, Slack, Discord, ntfy et d'autres canaux, ce qui vous permet d'être alerté en cas d'échec ou de succès de chaque sauvegarde.

Vous pouvez aussi déclencher une sauvegarde manuelle à tout moment depuis le dashboard, utile avant une migration ou une mise à jour majeure.

Restaurer à la demande

Restaurer une base de données avec Portabase ne demande que quelques clics :

1. Dans le dashboard, naviguez vers Projects → (Sélectionner une base) -> Détail
2. Localisez le snapshot souhaité
3. Cliquez Restore et choisissez la cible de restauration (même base ou nouvelle instance)
4. Confirmez l'opération — l'agent prend le relais et applique le dump

Conseil : testez régulièrement vos restaurations sur un environnement de staging. Une sauvegarde non vérifiée est une sauvegarde dont vous ne pouvez pas garantir l'intégrité.

Vous avez en plus quelques statistiques sur vos sauvegardes régulières.

FAQ

L'agent doit-il être sur le même serveur que mes bases de données ?

Non, mais c'est recommandé pour les performances et la sécurité. L'agent peut se connecter à des bases distantes via le réseau, à condition que les ports soient accessibles. Dans tous les cas, il opère en mode outbound : c'est lui qui initie les connexions, jamais vos bases qui exposent un port vers l'extérieur.

Quelle est la différence entre STORAGE_TYPE=local et STORAGE_TYPE=s3 ?

Avec local, les dumps sont stockés dans un volume Docker sur votre serveur Portabase. Pratique pour débuter, mais risqué si votre serveur tombe. Avec S3, les dumps sont envoyés vers un bucket compatible S3 (AWS, Scaleway Object Storage, MinIO auto-hébergé…). C'est la configuration recommandée pour la production : vos sauvegardes survivent à la perte du serveur Portabase lui-même.

Portabase chiffre-t-il les dumps avant de les stocker ?

Le chiffrement en transit est assuré si vous utilisez HTTPS/TLS (ce qui devrait toujours être le cas en production). Pour le chiffrement au repos, il est recommandé d'activer le chiffrement côté bucket S3 ou de configurer votre stockage local avec LUKS. La roadmap Portabase prévoit du chiffrement natif des dumps — consultez le GitHub du projet pour l'état d'avancement.

Comment savoir si une sauvegarde a échoué ?

Via les notifications configurées dans .env (SMTP, Slack, Discord, ntfy). Le dashboard affiche également un historique complet avec le statut de chaque job. Vous pouvez aussi inspecter les logs de l'agent avec docker logs agent-portabase.

Puis-je gérer plusieurs équipes et projets avec une seule instance Portabase ?

Oui, Portabase supporte plusieurs bases de données, organisations et projets avec du RBAC (contrôle d'accès basé sur les rôles), ce qui en fait un outil adapté aussi bien aux équipes de développement qu'aux entreprises soumises à des contraintes de conformité.

Conclusion

Portabase répond à un problème concret avec une approche pragmatique : pas de SaaS imposé, pas de credential envoyé dans le cloud, pas de script shell fragile. Un dashboard propre, un agent Rust performant, et une configuration Docker reproductible. C'est exactement le genre d'outil que l'on devrait mettre en place dès le premier jour d'un projet — et non après la première perte de données.

Passez à l'action :

• ⭐ Retrouvez nos configurations et scripts complémentaires sur github.com/networkpulse
• 📖 Consultez la documentation officielle Portabase pour les configurations avancées (reverse proxy, RBAC, OAuth)
• 💬 Rejoignez la communauté Portabase sur Discord pour poser vos questions