Comment héberger Umami sur un VPS

Umami est une alternative légère à Google Analytics : open source, sans cookies de traçage, sans transfert de données vers des tiers. Sur un VPS, vous en gardez le contrôle total — aucun compte SaaS, aucune limite de sites, aucune donnée partagée. La stack Docker est minimaliste : un conteneur Node.js pour l'application et un conteneur PostgreSQL pour la base de données. Le tout s'installe en moins de dix minutes sur une VM standard avec accès root, et les données restent sur votre serveur.

Comparé à Google Analytics 4, Umami ne nécessite pas de configuration de consentement pour les statistiques anonymisées dans la majorité des juridictions européennes. Comparé à Matomo, son empreinte mémoire est nettement inférieure, et sa configuration Docker se résume à un fichier docker-compose.yml. Pour une agence qui gère dix clients, une seule instance Umami avec dix sites fait le travail d'un abonnement SaaS facturé par utilisateur ou par domaine. La version 2.14 (juillet 2026) a introduit la prise en charge native des événements personnalisés et un tableau de bord exportable en CSV — deux fonctionnalités longtemps attendues par les équipes marketing.

Umami tourne sur n'importe quel VPS avec Docker installé. Le minimum recommandé est 1 vCPU et 512 Mo de RAM pour un usage personnel ou une PME ; au-delà de 200 000 pages vues par mois, 1 Go de RAM évite les ralentissements de PostgreSQL. Vous aurez besoin de : Docker Engine (≥ 20.10) et Docker Compose V2 (docker compose, pas docker-compose), un nom de domaine ou sous-domaine pointant vers votre VPS, et un reverse proxy (nginx ou Caddy) pour servir Umami en HTTPS. Debian 12 et Ubuntu 22 sont les distributions de référence ; les commandes ci-dessous supposent un accès root ou sudo.

Côté serveur, ouvrez les ports 80 et 443 dans votre pare-feu (ufw allow 80/tcp && ufw allow 443/tcp). Umami n'a besoin que du port HTTPS exposé vers l'extérieur ; le port applicatif (3000 par défaut) reste interne et n'est jamais ouvert directement. Si vous utilisez un VPS ServOrbit, le groupe de sécurité par défaut autorise déjà 80 et 443.

Trois causes concentrent la quasi-totalité des échecs signalés en 2026 dans les guides communautaires. Les voici avec leur diagnostic et leur correctif.

1. Restart loop « Can't reach database server » — DATABASE_URL ne correspond pas à POSTGRES_PASSWORD

C'est le piège de copier-coller le plus fréquent : DATABASE_URL contient le mot de passe en clair dans la chaîne de connexion, et ce mot de passe doit être identique à la valeur de POSTGRES_PASSWORD dans le service db. Si vous changez l'un sans l'autre, Umami démarre, échoue à joindre la base, et redémarre en boucle — sans message d'erreur explicite dans les logs Docker.

Vérifiez que vos deux variables sont cohérentes :

# dans .env ou dans le compose
POSTGRES_PASSWORD=mot_de_passe_fort

# dans DATABASE_URL, le même mot de passe en position 3
DATABASE_URL=postgresql://umami:mot_de_passe_fort@db:5432/umami

Si vous utilisez une variable d'interpolation (${POSTGRES_PASSWORD}), assurez-vous que Docker Compose charge bien votre fichier .env.

2. Umami crashe 5 à 10 secondes après le démarrage — depends_on sans healthcheck

Par défaut, depends_on: db attend uniquement que le conteneur PostgreSQL soit démarré, pas qu'il soit prêt à accepter des connexions. Umami tente alors de se connecter alors que PostgreSQL initialise encore ses fichiers de données, échoue, et s'arrête.

Ajoutez un healthcheck sur le service db et un condition: service_healthy dans le depends_on d'Umami :

services:
  db:
    image: postgres:15-alpine
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U umami"]
      interval: 10s
      timeout: 5s
      retries: 5
  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest
    depends_on:
      db:
        condition: service_healthy

Avec cette configuration, Umami ne démarre qu'une fois que PostgreSQL répond sur son socket.

3. Erreur 502 après un docker compose pull — port publié modifié

Après une mise à jour (docker compose pull + docker compose up -d), nginx peut renvoyer une erreur 502 si la configuration a changé entre deux versions de l'image : le port interne peut avoir été redirigé ou le binding hôte modifié. Vérifiez d'abord l'état réel des conteneurs :

docker compose ps

Repérez la colonne PORTS pour confirmer que le conteneur Umami publie bien sur le port attendu (par défaut 3000). Si le port a changé, mettez à jour la directive proxy_pass (ou reverse_proxy) dans nginx ou Caddy pour qu'elle reflète le nouveau port, puis rechargez le service (nginx -s reload ou systemctl reload caddy).

4. docker-compose (v1) vs docker compose (v2) — commandes muettes

Les guides publiés avant 2025 utilisent souvent docker-compose (tiret), le client Python qui n'est plus maintenu. Sur une installation fraîche de Docker Engine, cette commande n'existe pas : le terminal rend simplement command not found, sans dire que v2 s'appelle docker compose (espace). Vérifiez avec docker compose version — si la commande répond, vous avez v2. Tous les exemples de ce guide utilisent docker compose (v2).