docktail README

项目的 README,来自 github.com/marvinvr/docktail。合并为一个 markdown 文件:README.md。

🍸 DockTail

Unleash your containers as Tailscale Services.

Latest release License: AGPL-3.0 Image on ghcr.io CI status

Add docktail labels to a Compose service, run docker compose up -d, and open https://myapp.your-tailnet.ts.net

Featured on Tailscale Community

DockTail watches Docker containers, reads docktail.* labels, and exposes matching containers as Tailscale Services. App containers do not need published Docker ports by default; DockTail proxies directly to their Docker network IPs.

Watch "I'm Running Docker Apps Differently Now" on Tailscale's YouTube channel
▶ I'm Running Docker Apps Differently Now: DockTail, featured on Tailscale's YouTube channel

Why DockTail?

DockTail uses native Tailscale Services, not per-container Tailscale devices.

DockTail TSDProxy ScaleTail tsbridge Plain Services
Native Tailscale Services ✅ ❌ ❌ ❌ ✅
Configured via Docker labels ✅ ✅ ❌ ✅ ❌
Apps do not consume separate Tailscale device slots ✅ ❌ ❌ ❌ ✅
No app port publishing ✅ ⚠️¹ ⚠️² ⚠️¹ ⚠️³
Automatic Docker reconciliation ✅ ✅ ❌ ✅ ❌
Low manual setup after install ✅ ✅ ⚠️⁴ ✅ ❌

Features

Quick Start

services:
  docktail:
    image: ghcr.io/marvinvr/docktail:latest
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /var/run/tailscale:/var/run/tailscale
    environment:
      # Optional but recommended. Enables automatic service creation.
      - TAILSCALE_OAUTH_CLIENT_ID=${TAILSCALE_OAUTH_CLIENT_ID}
      - TAILSCALE_OAUTH_CLIENT_SECRET=${TAILSCALE_OAUTH_CLIENT_SECRET}

  myapp:
    image: nginx:latest
    # No ports needed. DockTail proxies directly to the container IP.
    labels:
      - "docktail.service.enable=true"
      - "docktail.service.name=myapp"
      - "docktail.service.port=80"
docker compose up -d
curl http://myapp.your-tailnet.ts.net

This assumes the Docker host is connected to Tailscale and allowed to advertise services. See the full docs for host setup, sidecar setup, rootless Docker, OAuth permissions, ACLs, labels, Funnel, and examples. docker-compose.yaml is a ready-to-run version of this setup; for Podman, Synology, Unraid, TrueNAS, macOS, Windows, Swarm and Kubernetes see the platform guides, and for a read-only Docker socket proxy and dropped capabilities see Hardening.

For Docker secrets or other mounted secret files, set FILE__TAILSCALE_OAUTH_CLIENT_ID / FILE__TAILSCALE_OAUTH_CLIENT_SECRET or TAILSCALE_OAUTH_CLIENT_ID_FILE / TAILSCALE_OAUTH_CLIENT_SECRET_FILE to the mounted file paths instead of putting the values directly in the environment.

Common Examples

Expose an app with Tailscale HTTPS:

labels:
  - "docktail.service.enable=true"
  - "docktail.service.name=api"
  - "docktail.service.port=3000"
  - "docktail.service.service-port=443"

Expose a database over TCP:

labels:
  - "docktail.service.enable=true"
  - "docktail.service.name=db"
  - "docktail.service.port=5432"
  - "docktail.service.protocol=tcp"
  - "docktail.service.service-port=5432"

Preserve the tailnet client IP on a TCP reverse proxy:

labels:
  - "docktail.service.enable=true"
  - "docktail.service.name=traefik"
  - "docktail.service.port=443"
  - "docktail.service.protocol=tcp"
  - "docktail.service.service-port=443"
  - "docktail.service.proxy-protocol=2"

Expose a service publicly with Tailscale Funnel:

labels:
  - "docktail.funnel.enable=true"
  - "docktail.funnel.port=3000"
  - "docktail.funnel.funnel-port=8443"

Mount an HTTP(S) Funnel at a path:

labels:
  - "docktail.funnel.enable=true"
  - "docktail.funnel.port=3000"
  - "docktail.funnel.path=/webhook"

DockTail Cloud (optional)

Once you run DockTail on more than one machine, "is it still up?" gets tedious. DockTail Cloud is a hosted dashboard for that — and because it already has the Docker and Tailscale context, it tells you which kind of broken you're looking at:

● down · OOM-killed                   →  the container was killed for running out of memory
● local up · awaiting approval        →  the app is fine, the exposure isn't
● host offline · heartbeat missing    →  the box stopped reporting

It rides along with the agent you already run — no second binary. Set one environment variable and the same container starts reporting:

environment:
  - DOCKTAIL_CLOUD_KEY=${DOCKTAIL_CLOUD_KEY}   # from cloud.docktail.org

Without the key the module is completely inert: no connection is opened and DockTail behaves exactly as before. The link is outbound-only and metadata-only — the protocol has no exec, deploy, or shell message types, which you can verify in cloud/.

DockTail Cloud is a paid service (plans and pricing); Homelab and Team start with a 30-day free trial. Your AI agent can investigate incidents through its MCP server and API. docker-compose.cloud.yaml is a complete example.

Explore DockTail Cloud · open the dashboard · agent setup

Documentation

The canonical documentation source lives in docs/. The site at docktail.org is built from a separate repository, which pins this one as a submodule and renders those Markdown files with tools/docsgen at build time.

Build From Source

go build -o docktail .
docker build -t docktail:latest .

The image is published for linux/amd64, linux/arm64 and linux/arm/v7, and releases newer than 1.8.3 carry static Linux binaries for the same platforms; see Platforms And Release Binaries.

Star History

Star History Chart

License

AGPL v3


By @marvinvr

docktail (marvinvr/docktail)

正在搜索数据库…

这是什么?DockTail 会监控 Docker 容器,读取 docktail 标签,并将匹配的容器以 Tailscale Services 的形式对外提供。默认情况下,应用无需发布 Docker 端口,因为 DockTail 会代理到它们的 Docker 网络 IP。
它是每个容器对应一个 Tailscale 设备,还是另有方式?都不是。它使用原生的 Tailscale Services,而不是为每个容器分配一个 Tailscale 设备,因此你的应用不会占用单独的设备名额。
我该如何让它运行起来?在将 Docker 主机连接到 Tailscale 并允许其发布服务之后,从开箱即用的 docker-compose.yaml 开始。然后为需要对外提供的容器添加 docktail 标签。
开始之前我需要准备什么?一台已连接到 Tailscale 并被允许发布服务的 Docker 主机,以及 OAuth 客户端凭据或 API 密钥,以便 DockTail 自动创建 Tailscale 服务。
有哪些需要注意的地方?Tailscale Funnel 会将服务暴露到公共互联网,因此请有意识地启用它。清理未使用的 Tailscale 服务定义需要主动选择开启。
它能在群晖、Unraid、TrueNAS 或 Kubernetes 上运行吗?可以,已有针对 Podman、群晖、Unraid、TrueNAS、macOS、Windows、Swarm 和 Kubernetes 的平台指南,并且还有一份针对只读 Docker 套接字代理的加固指南。
它会把我的数据发送到别处吗?默认不会。DockTail Cloud 报告功能是可选的,只有设置一个环境变量才会开启。没有密钥时,不会建立任何连接;该链接仅为出站连接,且只传输元数据。
使用是免费的吗?核心项目采用 AGPL v3 许可证,免费使用。DockTail Cloud 是一项单独的付费服务,其 Homelab 和 Team 套餐均提供 30 天免费试用。
什么是 DockTail Cloud?这是一个可选的托管仪表板,用于监控运行 DockTail 的多台机器。它复用同一个容器,你的 AI 代理还可以通过其 MCP 服务器和 API 调查事件。
为什么不直接使用原生 Tailscale Services?原生 Tailscale Services 需要手动配置。DockTail 会读取 Docker 标签,并在容器重启或其 IP 变化时自动进行同步。
我能通过 TCP 对外暴露数据库吗?可以。支持 HTTP、HTTPS、TCP 以及 TLS 终止的 TCP,并且可选的 PROXY 协议能让 TCP 后端看到真实的 tailnet 客户端 IP。
作者
marvinvr
大小
5.6 MB
星标
1.6K
时长
1年
提交 · 90 天