Héberger Umami sur un VPS géré : vos statistiques web sur votre serveur

Ce que fait Umami

Umami est une plateforme open source de mesure d'audience web et produit. Sa documentation la décrit comme un outil qui réunit le trafic, les campagnes, le comportement des visiteurs, les conversions, la fidélité et le chiffre d'affaires, de la première visite jusqu'aux résultats qui comptent pour votre activité. Elle est écrite en TypeScript sur Next.js, et son image Docker tourne sous un compte sans privilèges.

• L'acquisition : pages vues, visiteurs, sites référents, pays, appareils et activité en temps réel, avec les campagnes UTM, les liens courts et les pixels de suivi.
• Le comportement : événements personnalisés, parcours, rediffusions de sessions, cartes de chaleur, segments, cohortes et fidélité.
• La conversion : objectifs, entonnoirs, attribution et suivi du chiffre d'affaires par page et par campagne.
• Le partage : tableaux de bord, équipes, adresse de partage publique, API et serveur MCP en lecture seule pour votre assistant IA.
• Les sites modernes : la FAQ précise qu'Umami suit de lui-même la navigation des applications à page unique, sans réglage de plus.

Une instance suit plusieurs sites : chacun reçoit son identifiant et son script de suivi, et vos collaborateurs s'y retrouvent par comptes et par équipes.

Ce que permet la licence MIT

Umami est publié sous licence MIT, au nom d'Umami Software, Inc. Elle accorde gratuitement le droit d'utiliser, de copier, de modifier, de fusionner, de publier, de distribuer, de sous-licencier et de vendre des copies du logiciel. Vous pouvez donc le faire tourner pour votre entreprise et pour les sites de vos clients, sans licence à acheter.

Sa seule condition : la mention de copyright et le texte de la permission accompagnent toute copie ou partie substantielle du logiciel. Comme toute licence MIT, elle fournit le logiciel « tel quel », sans garantie.

Témoins et données personnelles : ce que dit le projet

La documentation présente Umami comme une mesure d'audience sans témoins, sans suivi d'un site à l'autre et sans collecte automatique de données personnelles. Auto-hébergé, il garde vos statistiques sur votre propre serveur : vous décidez où elles vivent et combien de temps elles restent.

Trois réglages du script de suivi vont plus loin, si vous le souhaitez : data-exclude-search retire les paramètres de recherche des adresses relevées, data-exclude-hash en retire l'ancre, et data-do-not-track coupe le suivi pour les navigateurs qui expriment la préférence Do Not Track. La documentation rappelle que ce dernier réglage n'est pas, à lui seul, une solution complète de gestion du consentement.

Si vous identifiez les visiteurs connectés avec data-distinct-id ou umami.identify(), la documentation recommande un identifiant interne ou une empreinte plutôt qu'une adresse e-mail : la valeur se lit dans le code HTML de la page.

L'installation avec Docker Compose et PostgreSQL

Le dépôt fournit un docker-compose.yml qui lance Umami et sa base PostgreSQL. Depuis la version 3, PostgreSQL est la seule base prise en charge, en version 12.14 au minimum, et la documentation recommande de la régler sur le fuseau UTC. Sur un serveur où Docker est installé, créez un dossier et commencez par ses secrets, tirés au hasard avec openssl, comme le conseille la documentation :

cat > .env <<EOF
POSTGRES_PASSWORD=$(openssl rand -hex 24)
APP_SECRET=$(openssl rand -hex 32)
TWO_FACTOR_ENCRYPTION_KEY=$(openssl rand -hex 32)
EOF
chmod 600 .env

Placez ensuite ce compose.yaml à côté. Il reprend le fichier du projet à la version 3.4.1, avec deux changements : les secrets viennent du fichier .env, et le port n'est publié que sur 127.0.0.1.

services:
  umami:
    image: ghcr.io/umami-software/umami:latest
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:${POSTGRES_PASSWORD}@db:5432/umami
      APP_SECRET: ${APP_SECRET}
      TWO_FACTOR_ENCRYPTION_KEY: ${TWO_FACTOR_ENCRYPTION_KEY}
    depends_on:
      db:
        condition: service_healthy
    init: true
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "curl http://localhost:3000/api/heartbeat"]
      interval: 5s
      timeout: 5s
      retries: 5
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - umami-db-data:/var/lib/postgresql/data
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5
volumes:
  umami-db-data:

docker compose up -d
curl -s http://127.0.0.1:3000/api/heartbeat

• DATABASE_URL : la seule variable obligatoire, l'adresse de connexion à la base. Le mot de passe tiré en hexadécimal s'y écrit tel quel ; un mot de passe à caractères spéciaux demanderait l'encodage pourcent.
• APP_SECRET : une chaîne aléatoire qui protège les jetons d'authentification, propre à chaque installation. Dans le code de la version 3.4.1, elle entre aussi dans le calcul des identifiants de session : gardez-la stable.
• TWO_FACTOR_ENCRYPTION_KEY : 64 caractères hexadécimaux qui chiffrent les secrets de double authentification. Sans elle, personne ne peut activer la double authentification.
• Au démarrage, le conteneur vérifie la connexion et la version de la base, puis applique lui-même les migrations du schéma. Au premier lancement, il crée les tables et le compte admin. La sonde /api/heartbeat répond {"ok":true} quand Umami est prêt.
• L'étiquette latest suit la dernière version publiée. Le registre du projet publie aussi des étiquettes par version, comme 3.4.1, pour fixer celle que vous faites tourner.

La documentation d'installation ne chiffre ni la mémoire ni le processeur. La taille dépend du trafic des sites suivis et du volume de données conservées. Sur un VPS géré, décrivez-nous votre usage et nous vous recommandons la taille qui convient.

HTTPS : le mandataire inverse

Umami écoute en HTTP sur le port 3000, et la documentation propose de le servir derrière votre serveur web, par un mandataire inverse. Donnez-lui son propre sous-domaine, comme stats.example.com, pointé vers le serveur par des enregistrements A et AAAA. Servir Umami sous un chemin passe par BASE_PATH, une variable lue à la construction de l'application : avec l'image publiée, le sous-domaine est la voie directe.

Le mandataire doit aussi transmettre l'adresse du visiteur. Umami la lit dans les en-têtes qu'il reçoit, dont X-Real-IP et X-Forwarded-For : elle lui sert à distinguer les visiteurs et à situer leur pays. Si votre mandataire utilise un autre en-tête, CLIENT_IP_HEADER le désigne.

Avec Caddy

Caddy obtient lui-même le certificat Let's Encrypt et active HTTPS. Sa directive reverse_proxy ajoute X-Forwarded-For d'office : ces trois lignes suffisent.

stats.example.com {
  reverse_proxy 127.0.0.1:3000
}

Avec Nginx et Certbot

Ce bloc reprend l'exemple Nginx de la documentation d'Umami, en écoute sur le port 80 pour laisser Certbot installer HTTPS :

server {
  listen 80;
  listen [::]:80;
  server_name stats.example.com;

  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}

Certbot installe ensuite le certificat et se charge de le renouveler :

sudo certbot --nginx

La première connexion : le compte admin et la double authentification

À la création de sa base, Umami ouvre un compte administrateur : identifiant admin, mot de passe umami. La documentation demande de changer ce mot de passe dès la première connexion.

1. Ouvrez votre adresse HTTPS et connectez-vous avec admin et umami.
2. Ouvrez Settings depuis le bouton de profil de la barre latérale, puis Profile, et cliquez sur Change password.
3. Dans l'onglet Security, activez la double authentification : scannez le code QR avec votre application d'authentification, saisissez le code à six chiffres, puis rangez en lieu sûr les dix codes de secours, affichés une seule fois.

• Exiger la double authentification : un administrateur peut l'imposer à toute l'instance, à un utilisateur ou à une équipe, depuis la page d'administration.
• Les tentatives : cinq codes faux bloquent les essais pendant 15 minutes.
• Les comptes de votre équipe : la page d'administration gère les utilisateurs, les sites et les équipes de toute l'instance.

Gardez TWO_FACTOR_ENCRYPTION_KEY avec vos sauvegardes : la documentation prévient que perdre ou changer cette clé rend illisibles les secrets déjà enregistrés, et chaque utilisateur doit alors réactiver sa double authentification.

Ajouter un site et son script de suivi

1. Dans Websites, cliquez sur Add website.
2. Donnez un nom au site, puis son domaine : Umami s'en sert pour écarter vos propres pages de la liste des sites référents.
3. Ouvrez Edit sur ce site et copiez le code de la section Tracking code.
4. Collez-le dans le <head> de vos pages, puis visitez votre site : les données paraissent aussitôt dans le tableau de bord.

<script defer src="https://stats.example.com/script.js" data-website-id="identifiant-du-site"></script>

• Rien ne paraît ? La documentation conseille l'onglet réseau des outils de développement : les requêtes vers votre instance doivent partir sans erreur.
• Next.js : insérez le code avec le composant next/script plutôt qu'une balise <script> simple.
• data-domains limite le suivi à vos domaines de production, ce qui garde hors des statistiques vos environnements de test.
• Vos propres visites s'écartent site par site, depuis la console du navigateur, avec localStorage.setItem('umami.disabled', 1).

Un nom de script à vous

Certains bloqueurs de publicité écartent tout ce qui ressemble à de la mesure d'audience. Auto-hébergé, Umami se sert déjà depuis votre propre domaine, et deux variables vont plus loin : TRACKER_SCRIPT_NAME donne un autre nom au script, au lieu de script.js, et COLLECT_API_ENDPOINT renomme l'adresse de collecte, au lieu de /api/send. Le script appelle alors de lui-même la nouvelle adresse ; seule la source du code de suivi change sur vos pages.

TRACKER_SCRIPT_NAME: "stats.js"
COLLECT_API_ENDPOINT: "/api/collect"

Les réglages utiles

Ces variables d'environnement se placent dans le service umami de compose.yaml, puis docker compose up -d recrée le conteneur pour les prendre en compte :

Les sauvegardes

Tout ce que garde Umami vit dans sa base PostgreSQL : comptes, sites, équipes et statistiques. Exportez-la chaque jour et juste avant chaque mise à jour : auto-hébergées, ces données sont conservées sans limite de durée. À côté de la base, le fichier .env porte les secrets qui la rendent utilisable :

Exporter la base, service en marche

pg_dump produit un export cohérent pendant que la base sert. Le format personnalisé, -Fc, est compressé et se restaure avec pg_restore :

docker compose exec -T db pg_dump -U umami -d umami -Fc > umami-$(date +%F).dump

Planifiez cette commande sur le serveur au moins une fois par jour, faites le tri parmi les exports, qui s'accumulent, et envoyez-en une copie ailleurs. Posés sur le disque du serveur, ces exports entrent aussi dans ses sauvegardes de nuit.

Restaurer

1. Arrêtez Umami, en laissant la base en marche : docker compose stop umami.
2. Restaurez l'export dans la base, en remplaçant les objets existants.
3. Relancez Umami, puis vérifiez que vos sites et leurs statistiques sont là.

docker compose stop umami
docker compose exec -T db pg_restore -U umami -d umami --clean --if-exists < umami-AAAA-MM-JJ.dump
docker compose start umami

Répétez cet exercice de temps en temps, sur une copie : c'est ainsi que vous vérifiez qu'une sauvegarde fonctionne.

Les mises à jour

La documentation donne deux commandes, depuis le dossier du compose.yaml. La base reste dans son volume :

docker compose pull
docker compose up --force-recreate -d

Au redémarrage, le conteneur applique de lui-même les migrations du schéma. La 3.4.0 du 17 septembre 2026 en portait deux, pour les annotations et les clés d'API ; la 3.4.1 du 23 octobre 2026 n'en porte aucune. Après une montée de version majeure, comme le passage à la version 3, la documentation conseille de lancer ANALYZE dans PostgreSQL, pour que les tableaux de bord retrouvent leur vitesse :

docker compose exec db psql -U umami -d umami -c "ANALYZE;"

• Les notes de version disent ce que chaque version change. La 3.4.1 est un correctif de sécurité, qui met à jour Next.js et l'image de base Node.js ; ses notes demandent à toutes les instances auto-hébergées de mettre à jour, en tirant de nouveau l'image.
• Depuis une version 2 sur MySQL : la version 3 ne prend plus MySQL en charge. Le guide de migration du projet fait passer les données vers PostgreSQL en version 2.19.0, avant la montée en version 3.
• PostgreSQL lui-même : gardez l'étiquette postgres:15-alpine du fichier. Changer de version majeure de PostgreSQL demande un export et une restauration, ou pg_upgrade.

Qui fait quoi sur un VPS géré

L'auto-hébergement demande de tenir le serveur en plus de l'application. Sur un VPS géré, nos équipes prennent le serveur en main et suivent votre instance de manière proactive ; Umami reste votre logiciel, avec ses réglages et ses données.

Si vous préférez que nos équipes interviennent dans l'application elle-même, cette prestation se facture à l'heure ou au forfait, avec un chiffrage communiqué avant l'intervention.