Aller au contenu principal

Installation locale avec Docker

Répliquer un environnement distant en local

attention

Cette méthode est destinée à des environnements de développement ou de test.

Pour une utilisation en production, il est recommandé d'utiliser les services managés de Supabase ou de configurer un serveur dédié.

Notions théoriques​

Pourquoi utiliser Supabase en local ?​

Supabase est une plateforme open-source qui fournit une base de données PostgreSQL, un système d’authentification, un stockage de fichiers et des fonctions serverless.

En général, Supabase est utilisé en mode hébergé (cloud), mais il est également possible de le faire tourner en local grâce à Docker.

Cela permet de :

  • Travailler hors-ligne ou en environnement isolé
  • Tester des modifications sans impacter la base distante
  • Contrôler entièrement son environnement de développement
  • Automatiser des tests dans un environnement maîtrisé

Docker : une virtualisation légère​

Docker permet de lancer des applications dans des containers, c’est-à-dire des environnements isolés et reproductibles.

Supabase fournit un fichier docker-compose.yml qui décrit tous les services nécessaires à son bon fonctionnement :

  • PostgreSQL (la base de données)
  • Studio (interface graphique)
  • Auth (gestion des utilisateurs)
  • Realtime, Storage, Rest API, etc.

Avec une seule commande, il est possible de lancer tous ces services localement.

Rappel

Docker Compose est un outil qui permet de définir et de lancer plusieurs containers à partir d’un seul fichier de configuration.

Étapes de mise en place​

Voici les grandes étapes à suivre pour installer Supabase en local :

  1. Installer Docker et Docker Compose
  2. Cloner le dépôt officiel de Supabase
  3. Lancer les services avec docker-compose up
  4. Exporter la base distante avec pg_dump
  5. Importer la base dans l’environnement local avec psql

Export et import de la base de données​

Export avec pg_dump​

pg_dump est un outil qui permet d’exporter une base PostgreSQL sous forme de fichier .sql.

info

Il est possible d’exporter uniquement la structure, uniquement les données, ou les deux.

pg_dump --dbname=postgresql://user:password@host:port/dbname --format=plain --file=export.sql

Import avec psql​

Une fois le fichier exporté, on peut l’importer dans la base locale avec psql :

psql -U postgres -h localhost -p 54322 -d postgres < export.sql
attention

Le port 54322 est celui utilisé par Supabase en local par défaut (et non le port standard 5432).

Exemple pratique​

Étape 1 : Installer Docker​

docker --version
docker compose version
attention

Sur Linux, pensez à ajouter votre utilisateur au groupe docker pour ne pas avoir à utiliser sudo :

sudo adduser $USER docker

ou

sudo usermod -aG docker $USER && newgrp docker

Étape 2 : Cloner le dépôt Supabase​

Il est possible de cloner le dépôt officiel :

git clone https://github.com/supabase/supabase.git
cd supabase/docker

Ou d’utiliser un dépôt simplifié :

git clone https://github.com/supabase-community/supabase-docker.git
cd supabase-docker

Étape 3 : Lancer Supabase en local​

docker compose up

Cela lance tous les services Supabase localement. L’interface Studio est accessible à l’adresse :

http://localhost:54323

La base PostgreSQL est accessible sur :

  • Port : 54322
  • Utilisateur : postgres
  • Mot de passe : postgres

Étape 4 : Exporter la base distante​

Se connecter à la base distante Supabase et exécuter :

pg_dump --dbname=postgresql://USER:PASSWORD@HOST:PORT/DBNAME --file=export.sql
astuce

Il est possible de récupérer les paramètres de connexion dans l’interface Supabase, onglet Settings > Database.

Étape 5 : Importer dans la base locale​

Copier le fichier export.sql dans le dossier du projet local, puis exécuter :

psql -U postgres -h localhost -p 54322 -d postgres < export.sql

Vérifier que les tables, données et rôles sont bien présents dans la base locale.

Autres méthodes d'installation : Supabase CLI

Il existe 2 méthodes intégrées aux projets JavaScript, pour simplifier l'installation et la gestion de Supabase, en utilisant un gestionnaire de paquets (yarn ou npm).

Au lieu de cloner un dépôt Docker et de gérer manuellement les services via Docker Compose, on installe la Supabase CLI comme dépendance d'un projet JavaScript.

astuce

La Supabase CLI permet de lancer un environnement local Supabase (base de données PostgreSQL, API, authentification, etc.) directement depuis le terminal, sans avoir à manipuler des fichiers docker-compose.yml.

Commandes shell​

Comment installer et utiliser la Supabase CLI dans un projet JavaScript ?

1. Avec Yarn​

yarn add --dev supabase

Une fois installée, la CLI peut être utilisée avec yarn :

yarn supabase init
yarn supabase start

2. Avec npm​

npm install --save-dev supabase

Une fois installée, la CLI peut être utilisée avec npx :

npx supabase init
npx supabase start

Avantages​

  • Intégration directe dans un projet JavaScript ou TypeScript
  • Pas besoin de gérer des fichiers Docker manuellement
  • Configuration légère et rapide pour le prototypage

Inconvénients​

  • Nécessite Node.js et un gestionnaire de paquets (npm ou Yarn)
  • Moins isolé que Docker (dépend des ports et du système local)
  • Moins adapté aux environnements complexes ou à la production

Utiliser la Supabase CLI dans un projet NextJS

Pour utiliser la Supabase CLI dans un projet NextJS, veuillez consulter Intégrer l'API Supabase dans votre projet Next.js.

Test de mémorisation/compréhension​


Quel outil permet de lancer plusieurs containers en une seule commande ?


Quel port est utilisé par défaut par Supabase en local pour PostgreSQL ?


Quel outil permet d’exporter une base PostgreSQL ?


Quel outil permet d’importer un fichier SQL dans PostgreSQL ?


Quelle commande permet de lancer Supabase en local ?


Quel est le nom d’utilisateur par défaut pour PostgreSQL local avec Supabase ?


Quel est l’intérêt d’utiliser Supabase en local ?


Quel outil faut-il installer pour utiliser Supabase en local ?


Quelle commande permet de vérifier la version de Docker ?


Pourquoi ajouter son utilisateur au groupe docker sur Linux ?


Quelle commande permet d’installer la CLI Supabase avec npm dans un projet Javascript ?


Quel est l’avantage principal de l’installation de Supabase avec la CLI plutôt qu’avec Docker ?


Quelle commande initialise la configuration Supabase dans un projet Javascript ?


Peut-on installer la Supabase CLI sans utiliser Yarn ?


TP pour réfléchir et résoudre des problèmes​

Objectif du TP : Installer Supabase en local avec Docker, exporter la base distante (structure + données), l’importer dans la base locale, et vérifier que la base locale est une copie exacte de la base distante.

Étape 1 – Installer Docker et Docker Compose​

Vérifiez que Docker et Docker Compose sont bien installés sur votre poste.

  1. Si ce n’est pas fait, téléchargez Docker Desktop depuis :
    https://www.docker.com/products/docker-desktop

  2. Installez Docker Desktop et redémarrez votre ordinateur si nécessaire.

  3. Ouvrez un terminal et vérifiez les versions :

docker --version
docker compose version
  1. Sur Linux, ajoutez votre utilisateur au groupe docker pour éviter d’utiliser sudo :
sudo usermod -aG docker $USER && newgrp docker
Une solution

Étape 2 – Cloner le dépôt Supabase Docker​

Cloner un dépôt contenant une configuration Docker Compose pour Supabase.

git clone https://github.com/supabase-community/supabase-docker.git
cd supabase-docker
Une solution

Étape 3 – Lancer Supabase en local​

Lancez les services Supabase localement :

docker compose up

Attendez que tous les services soient démarrés (cela peut prendre 1 à 2 minutes).

Une solution

Étape 4 – Exporter la base distante Supabase​

  1. Connectez-vous à votre projet Supabase sur https://supabase.com

  2. Allez dans Settings > Database et récupérez l’URL de connexion PostgreSQL.

  3. Utilisez pg_dump pour exporter la base distante :

pg_dump --dbname=postgresql://USER:PASSWORD@HOST:PORT/DBNAME --file=export.sql

Remplacez USER, PASSWORD, HOST, PORT et DBNAME par les valeurs de votre projet.

Une solution

Étape 5 – Importer la base dans l’environnement local​

  1. Placez le fichier export.sql dans le dossier supabase-docker (ou un sous-dossier).

  2. Exécutez la commande suivante pour importer dans la base locale :

psql -U postgres -h localhost -p 54322 -d postgres < export.sql

Mot de passe : postgres

Une solution

Étape 6 – Vérifier que la base locale est identique à la base distante​

  1. Connectez-vous à la base locale avec DBeaver ou psql.

  2. Vérifiez que les tables suivantes sont bien présentes :

  • profiles
  • classes
  • class_members
  • messages
  • user_roles
  1. Vérifiez qu’elles contiennent les mêmes données que dans la base distante (au moins quelques lignes, UUID, timestamps, etc.).
Une solution

Étape 7 – Sauvegarder l’état local​

Créez un snapshot ou un dump de la base locale pour pouvoir la restaurer facilement si besoin.

pg_dump -U postgres -h localhost -p 54322 -d postgres -f local_backup.sql
Une solution

Étape 8 – Nettoyer les logs ou relancer les services​

Si besoin, vous pouvez arrêter et relancer les services :

docker compose down
docker compose up
Une solution

Résultat attendu à la fin du TP​

  • Supabase est installé et fonctionne en local.
  • La base locale contient exactement les mêmes tables et données que la base distante.
  • Vous êtes prêt à créer des migrations locales et à les appliquer ensuite à distance.