Héberger Medusa : une alternative open source à Shopify (e-commerce headless)

L’e-commerce headless sépare le moteur commercial du site visible par les clients. Le catalogue, les paniers, les commandes et les promotions sont gérés par un backend accessible par API, tandis que le frontend est développé et déployé indépendamment. Cette architecture offre une grande liberté sur l’expérience utilisateur, les performances et les canaux de vente.

Medusa applique cette approche avec une plateforme open source en Node.js et TypeScript. Pour une startup ou une équipe de développement, c’est une alternative à Shopify qui permet de maîtriser le code, les données et l’hébergement. Cette liberté implique toutefois davantage de responsabilités techniques : Medusa demande de construire le storefront, de déployer plusieurs services et de maintenir l’ensemble.

L’e-commerce headless, c’est quoi et pour qui ?

Dans une boutique traditionnelle, le moteur e-commerce et les pages du site sont étroitement liés. Une solution headless découple ces deux couches :

• Le backend fournit le catalogue, les prix, les paniers, les clients, les commandes et les promotions.
• Le storefront affiche la boutique et communique avec le backend par API.
• D’autres canaux, comme une application mobile, une borne ou un espace B2B, peuvent consommer la même API.

Cette séparation permet de choisir librement la technologie du frontend, par exemple Next.js, Nuxt ou une application mobile. Elle facilite aussi l’optimisation des performances, les expériences sur mesure et les stratégies omnicanales.

Medusa reste néanmoins une solution orientée développeurs. Il faut construire ou adapter un storefront, le déployer, configurer les intégrations et parfois personnaliser le backend. Une équipe maîtrisant Node.js, TypeScript et les API web pourra exploiter cette flexibilité. Pour une personne non technique qui souhaite administrer une boutique uniquement par clics, WooCommerce, PrestaShop ou Shopify seront généralement plus simples.

Medusa face à WooCommerce, PrestaShop et Shopify

WooCommerce et PrestaShop proposent une approche relativement intégrée. Le CMS, le thème, les extensions et l’administration sont regroupés dans un même environnement. Cela accélère la mise en ligne d’une boutique classique, mais peut rendre les expériences très personnalisées plus difficiles à maintenir.

Shopify est un service SaaS fermé. L’infrastructure, les mises à jour et une grande partie de la sécurité sont prises en charge. En contrepartie, la plateforme impose son environnement, ses règles et certaines limites de personnalisation ou d’intégration.

Medusa est une boîte à outils e-commerce open source à assembler. L’équipe contrôle le backend, la base de données, le storefront et l’hébergement. Ce modèle convient particulièrement aux startups et aux équipes techniques qui veulent créer une expérience spécifique, connecter plusieurs canaux ou éviter une dépendance forte à une plateforme SaaS.

Architecture d’une plateforme Medusa

Une installation Medusa complète repose sur plusieurs composants :

• Le backend Medusa en Node.js et TypeScript expose les API et porte la logique commerciale.
• PostgreSQL stocke les produits, clients, paniers, commandes, régions et autres données structurées.
• Redis prend en charge des fonctions de cache, de coordination et de traitement asynchrone selon la configuration.
• Le dashboard admin permet de gérer le catalogue, les commandes, les promotions et les paramètres.
• Un ou plusieurs storefronts affichent la boutique et consomment l’API Store.

Le storefront n’est pas une simple page intégrée au backend. C’est une application distincte, avec son propre cycle de développement et de déploiement. Elle peut fonctionner sur le même serveur que Medusa ou sur une infrastructure séparée.

Prérequis pour auto-héberger Medusa

Une installation de production demande un serveur avec suffisamment de marge en mémoire pour exécuter Node.js, PostgreSQL, Redis et éventuellement le storefront. Il faut éviter de dimensionner la machine uniquement sur la consommation observée au repos, car les builds, migrations et pics de trafic augmentent rapidement les besoins.

Prévoyez également :

• Docker et Docker Compose (voir installer Docker sur un VPS), ou un environnement Node.js correctement maintenu.
• Une instance PostgreSQL.
• Une instance Redis.
• Un nom de domaine et un accès DNS.
• Un reverse proxy capable de gérer HTTPS.
• Des compétences en Node.js, TypeScript, Linux et déploiement web.

Les VPS TalCloud répondent à ce type de besoin avec des serveurs situés en France, du stockage NVMe, une protection Anti-DDoS Netrix et un support humain. L’hébergement en France facilite aussi la construction d’une infrastructure cohérente avec les exigences RGPD, sans remplacer le travail de conformité applicative.

Déployer le backend avec Docker Compose

Commencez avec un projet Medusa déjà initialisé et versionné. Le Dockerfile suivant construit le backend puis démarre sa version de production :

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

EXPOSE 9000

CMD ["npm","run","start"]

Un fichier compose.yaml peut ensuite réunir le backend, PostgreSQL et Redis :

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: medusa
      POSTGRES_USER: medusa
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redis_data:/data

  medusa:
    build: .
    restart: unless-stopped
    depends_on:
      - postgres
      - redis
    environment:
      NODE_ENV: production
      DATABASE_URL: postgres://medusa:${POSTGRES_PASSWORD}@postgres:5432/medusa
      REDIS_URL: redis://redis:6379
      JWT_SECRET: ${JWT_SECRET}
      COOKIE_SECRET: ${COOKIE_SECRET}
      STORE_CORS: https://boutique.example.fr
      ADMIN_CORS: https://api.example.fr
      AUTH_CORS: https://api.example.fr,https://boutique.example.fr
    ports:
      - "127.0.0.1:9000:9000"

volumes:
  postgres_data:
  redis_data:

Les variables doivent être lues par medusa-config.ts. Adaptez ce fichier à la version de Medusa utilisée et ne placez jamais les secrets directement dans le dépôt Git.

Générez des valeurs fortes pour PostgreSQL, les jetons JWT et les cookies :

openssl rand -hex 32
openssl rand -hex 32
openssl rand -hex 32

Placez-les dans un fichier .env protégé, puis construisez et démarrez les services :

docker compose up -d --build
docker compose ps

Exécutez ensuite les migrations de base de données :

docker compose exec medusa npx medusa db:migrate

Créez enfin un compte administrateur :

docker compose exec medusa npx medusa user --email admin@example.fr --password 'mot-de-passe-long-et-unique'

Les commandes exactes peuvent évoluer entre les versions majeures de Medusa. Verrouillez les versions de vos dépendances et validez la procédure sur un environnement de préproduction avant chaque mise à jour.

L’administration et les API Medusa

Le dashboard admin sert à gérer les produits, variantes, stocks, commandes, clients, promotions et régions. Sur les versions récentes, il est généralement servi par le backend, notamment sous le chemin /app, selon la configuration du projet.

Le storefront utilise principalement l’API Store. Les intégrations internes peuvent aussi exploiter les autres API et modules fournis par Medusa. Ne rendez accessibles que les routes nécessaires et contrôlez soigneusement les clés de publication, les sessions d’administration et les règles CORS.

Déployer le storefront séparément

Un storefront Next.js peut être déployé sur le même VPS ou ailleurs. Il doit connaître l’URL publique du backend et, selon la version de Medusa, utiliser une clé de publication associée au bon canal de vente.

Par exemple, l’application pourra recevoir des variables telles que :

MEDUSA_BACKEND_URL=https://api.example.fr
NEXT_PUBLIC_MEDUSA_BACKEND_URL=https://api.example.fr
NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_example

Le domaine du storefront doit figurer dans STORE_CORS et, si l’authentification client l’exige, dans AUTH_CORS. Toute différence de protocole, de sous-domaine ou de port constitue une origine distincte. Une configuration CORS approximative provoque souvent des échecs de connexion, de panier ou de paiement.

Configurer les paiements et les régions

Medusa s’intègre aux prestataires de paiement par modules ou plugins. Stripe est un choix courant, mais d’autres prestataires peuvent être ajoutés selon les besoins du projet et les extensions disponibles pour la version installée.

Les données de carte ne doivent jamais être stockées par Medusa ou dans votre base PostgreSQL. Utilisez les composants et jetons sécurisés du prestataire afin que le traitement PCI reste pris en charge par celui-ci.

Configurez aussi les régions commerciales, l’euro, les pays livrés, les taxes, les moyens de paiement et les options de livraison. Ces paramètres doivent être testés ensemble : une région mal associée peut rendre un produit indisponible ou empêcher la validation du panier.

Activer HTTPS avec un reverse proxy

Le port 9000 est lié à 127.0.0.1, donc inaccessible directement depuis Internet. Un reverse proxy comme Nginx, Caddy ou Traefik doit publier le backend sous une adresse HTTPS, par exemple api.example.fr.

Le storefront peut utiliser boutique.example.fr. Les certificats TLS, les redirections HTTP vers HTTPS et les en-têtes transmis au backend doivent être configurés pour les deux applications. Vérifiez ensuite que les URL publiques correspondent exactement aux valeurs CORS et aux URL de retour du prestataire de paiement.

Sécurité, sauvegardes et mises à jour

Utilisez des secrets JWT et COOKIE longs, uniques et générés aléatoirement. N’exposez jamais PostgreSQL ou Redis sur une interface publique. Limitez les accès SSH, activez un pare-feu, appliquez les mises à jour de sécurité et surveillez les journaux ainsi que l’espace disque. Notre guide sur la gestion des secrets complète ces pratiques.

Sauvegardez régulièrement PostgreSQL et les fichiers téléversés, qu’ils soient conservés localement ou dans un stockage objet. Un volume Docker n’est pas une sauvegarde. Conservez plusieurs versions sur un emplacement distinct et testez réellement la restauration. Notre guide sur les sauvegardes chiffrées avec restic aide à l’automatiser.

Medusa évolue rapidement. Versionnez le backend, le storefront, la configuration et les fichiers de déploiement. Épinglez les versions, lisez les notes de migration et testez les mises à niveau en préproduction. Avec cette discipline, Medusa offre une base solide pour construire une plateforme e-commerce headless flexible, auto-hébergée et adaptée aux équipes qui veulent conserver la maîtrise de leur architecture.