---
title: DockTail
created: 2026-06-07
updated: 2026-06-07
type: app
tags: [catalogue, vpn, tailscale, docker, declarative, go, auto-hebergement]
confidence: high
contested: false
sources: [https://selfh.st/apps/?tag=VPN, https://github.com/marvinvr/docktail]
---

# 🔐 DockTail

> **L'auto-discovery Docker pour Tailscale** : exposez vos conteneurs en Tailscale Services simplement en ajoutant des **labels**, sans configuration manuelle. Le « Traefik du mesh VPN ».

## 📋 Informations Générales

| Champ | Valeur |
| :--- | :--- |
| **Site web** | (GitHub) |
| **GitHub** | [marvinvr/docktail](https://github.com/marvinvr/docktail) |
| **License** | MIT |
| **Langage** | Go |
| **Étoiles GitHub** | 759 ⭐ |
| **Dernière MAJ** | 2026-05 |
| **Catégorie** | [[cat-vpn|VPN]] |

## 📝 Description

**DockTail** est un petit binaire Go qui se branche sur le **socket Docker** et qui expose automatiquement vos conteneurs comme **Tailscale Services**, simplement en lisant des **labels Docker**. L'idée est la même que ce que fait **Traefik** pour le HTTPS automatique : un contrôleur déclaratif qui surveille les événements Docker et synchronise l'état.

Concrètement, vous annotez un conteneur avec `docktail.enable=true` et `docktail.hostname=mon-app`, et DockTail crée automatiquement l'entrée correspondante dans votre **tailnet** (réseau Tailscale) — avec HTTPS automatique si vous utilisez [[app-headscale|Headscale]] + Tailscale, ou avec le HTTPS natif de Tailscale en SaaS.

DockTail supporte aussi bien **Tailscale** que **Headscale** (controller self-hosted) : il suffit de pointer l'auth key vers la bonne instance. C'est un outil particulièrement utile pour les homelabs qui veulent bénéficier de la simplicité de Tailscale (MagicDNS, HTTPS auto, ACL) sur leur stack Docker, sans avoir à maintenir manuellement un mapping port ↔ service.

**Public cible** : utilisateurs Tailscale/Headscale qui ont une stack Docker et qui veulent éviter de dupliquer la config réseau entre leurs `docker-compose.yml` et le panneau Tailscale.

- ✅ **Approche déclarative** : piloter par labels, comme Traefik
- ✅ **Watch Docker events** : ajout/retrait de conteneur, scale up/down
- ✅ **Support Tailscale ET Headscale** : self-hosted friendly
- ✅ **HTTPS automatique** : via Let's Encrypt + Tailscale
- ✅ **Binaire unique Go** : pas de runtime, image Docker légère
- ✅ **Multi-host** : un seul DockTail peut piloter des services sur plusieurs tailnets
- ✅ **Filtrage par labels** : `docktail.enable=true` pour opt-in
- ✅ **ACL Tailscale** : exploite les ACL existantes du tailnet
- ✅ **Zéro base de données** : state directement dans Tailscale
- ✅ **Healthcheck** intégré

## 🚀 Installation

### Docker Compose (mode sidecar)

```yaml
# docker-compose.yml
version: '3.8'
services:
  docktail:
    image: ghcr.io/marvinvr/docktail:latest
    container_name: docktail
    restart: unless-stopped
    environment:
      - TAILSCALE_AUTHKEY=tskey-auth-xxxxxxxxxxxxx
      - TAILSCALE_HOSTNAME=docktail-gateway
      - DOCKTAIL_DOCKER_HOST=unix:///var/run/docker.sock
      - DOCKTAIL_TAILNET=tail.ts.net  # ou votre domaine Headscale
      - DOCKTAIL_DEFAULT_TAGS=tag:container
      - DOCKTAIL_HTTPS=true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - docktail-state:/var/lib/tailscale
    labels:
      - "traefik.enable=false"  # DockTail parle directement à Tailscale

  # Exemple : service exposé automatiquement via DockTail
  whoami:
    image: traefik/whoami
    container_name: whoami
    labels:
      - "docktail.enable=true"
      - "docktail.hostname=whoami.tail.ts.net"
      - "docktail.port=80"
      - "docktail.https=true"

volumes:
  docktail-state:
```

> **Note** : DockTail a besoin d'un **auth key Tailscale** (ou Headscale) avec les permissions `device:write` et `services:write`. Le socket Docker est monté **en lecture seule**. Le `docker.sock` doit être accessible — sur Mac/Windows avec Docker Desktop, ajuster le chemin ou activer le socket TCP.

## ⚙️ Configuration Initiale

1. **Générer un auth key** Tailscale/Headscale réutilisable (reusable + ephemeral OK, mais **non-ephemeral** recommandé pour le service DockTail lui-même)
2. **Déployer DockTail** avec le socket Docker monté et l'auth key
3. **Vérifier l'authentification** : `docker logs docktail` doit afficher `logged in` et le hostname apparaître dans `tailscale status`
4. **Annoter un premier conteneur** : ajouter `docktail.enable=true` et `docktail.hostname=mon-app.tail.ts.net` à un `docker-compose.yml` existant
5. **Redéployer** : `docker compose up -d` — DockTail détecte le label et crée automatiquement le service Tailscale
6. **Tester** : `https://mon-app.tail.ts.net` doit répondre depuis n'importe quel client du tailnet, avec HTTPS valide

## 🔄 Alternatives

### Open Source

- [[app-tailscale]] — Le client mesh VPN lui-même
- [[app-headscale]] — Controller Tailscale self-hosted
- [[app-traefik]] — Équivalent pour le HTTPS « Internet », pas mesh
- **tsnet** (lib Go Tailscale) — Approche plus bas niveau, pas déclarative
- **caddy-tailscale** — Plugin Caddy + Tailscale (pas d'auto-discovery Docker)
- **k8s-ingress-tailscale** — Variante Kubernetes
- **glauth** — Pas VPN, mais approche déclarative comparable

### Comparaison DockTail vs approches manuelles

| Critère | DockTail | Manuel (`tailscale serve`) | Tailscale Provider (Traefik) | Annotations k8s |
| :--- | :--- | :--- | :--- | :--- |
| Self-hosted friendly | ✅ | ✅ | ✅ | ✅ |
| Découverte auto Docker | ✅ | ❌ | Partielle (Traefik) | ❌ (k8s) |
| Configuration | Labels YAML | CLI à la main | Providers Traefik | Ingress k8s |
| HTTPS auto | ✅ | ✅ (Tailscale) | ✅ | ✅ |
| MagicDNS | ✅ | ✅ | ✅ | ✅ |
| Licence | MIT | BSD-3 | MIT | Apache-2.0 |
| Cible | Docker Compose | Bare-metal | Stack Traefik | Kubernetes |

**Verdict** : DockTail est **le chaînon manquant** entre Docker et Tailscale pour les stacks `docker-compose`. C'est l'équivalent exact de ce que Traefik fait pour le reverse proxy, mais dans le monde du mesh VPN. Pour un homelab Docker + Tailscale, c'est l'outil le plus ergonomique.

### Propriétaires (ce que DockTail complète)

- **Tailscale** (SaaS) — DockTail est un add-on, pas un remplaçant
- **Cloudflare Tunnel** + WARP — Approche concurrente
- **ngrok** (commercial) — Tunneling classique, pas mesh
- **Cato Networks**, **Zscaler** — SD-WAN entreprise

## 🔐 Sécurité

- **Cryptographie** : hérite intégralement de **Tailscale** / **Headscale** — WireGuard pour le transport (ChaCha20-Poly1305, Curve25519), Noise protocol pour le handshake, certificats courts automatiquement renouvelés. DockTail n'implémente **aucun crypto** lui-même, il orchestre.
- **Clés privées** : la clé Tailscale du node DockTail est stockée dans `/var/lib/tailscale`, dans un volume Docker. **Chiffrement au repos** recommandé (LUKS, ZFS natif) puisque cette clé donne accès au tailnet.
- **Auth key** : l'auth key Tailscale est très sensible — un attaquant qui l'obtient peut enregistrer un node à votre place. Stocker dans un **secrets manager** (Doppler, Vault, ou variable chiffrée) plutôt qu'en clair dans le `docker-compose.yml`.
- **Socket Docker** : DockTail a besoin de **lire** les événements Docker. Monter `docker.sock` en `:ro` (lecture seule) ne suffit pas à empêcher un RCE si l'image est compromise. Solution : utiliser un **proxy Docker socket** (Tecnativa/docker-socket-proxy) avec filtre.
- **ACL Tailscale** : configurer des **tags** sur les services exposés (`docktail.tags=tag:web`) et restreindre dans l'ACL Tailscale qui peut y accéder. Le tag `tag:container` est volontairement restrictif.
- **HTTPS obligatoire** : `DOCKTAIL_HTTPS=true` garantit que les services sont servis en TLS, avec certificats auto-gérés par Tailscale.
- **Audit** : les événements Docker sont journalisés, et l'API Tailscale trace toutes les créations/modifications de services.
- **Ephemeral vs persistent** : utiliser un auth key **non-ephemeral** pour DockTail lui-même (sinon le node disparaît après expiration), et **ephemeral** pour les services jetables.

## 📚 Ressources

- [GitHub marvinvr/docktail](https://github.com/marvinvr/docktail)
- [Tailscale — Service documentation](https://tailscale.com/kb/1281/services/)
- [Headscale — service exposure](https://headscale.net/)
- [Docker socket proxy — Tecnativa](https://github.com/Tecnativa/docker-socket-proxy)
- [Blog selfh.st — Docker + Tailscale](https://selfh.st/)

## Pages Liées

- [[cat-vpn]] — Catégorie VPN
- [[app-wireguard]] — Le transport utilisé par Tailscale
- [[app-tailscale]] — Le client mesh VPN piloté
- [[app-headscale]] — Controller self-hosted compatible
- [[app-traefik]] — L'inspiration conceptuelle (labels déclaratifs)
- [[securisation-home-lab]] — Bonnes pratiques sécurité