Using Tailscale with Docker

Tailscale has a published Docker image that Tailscale manages and builds from source. It's available in Docker Hub and GitHub Packages. Watch the video below for a quick start guide on using Docker with Tailscale.

Pull image

To pull the image, run:

docker pull tailscale/tailscale:latest

or

docker pull ghcr.io/tailscale/tailscale:latest

Supported tags

Containers are tagged based on the Tailscale versioning scheme.

• Use stable or latest to get the latest stable version.
  • v1.58.2, v1.58 to get a specific stable version.
• Use unstable to get the latest unstable version.
  • unstable-v1.59.37, unstable-v1.59.44 to get a specific unstable version.

Parameters

You can set additional parameters for use with the image. All configuration is optional.

TS_ACCEPT_DNS

Accept DNS configuration from the admin console. Not accepted by default.

TS_AUTH_ONCE

Attempt to log in only if not already logged in. False by default, to forcibly log in every time the container starts.

TS_AUTHKEY

An auth key used to authenticate the container. This is equivalent to what you'd pass to tailscale login --auth-key=.

It is also possible to use an OAuth client secret here but the associated tag must be provided using TS_EXTRA_ARGS=--advertise-tags=tag:ci.

To mark a containerized node as ephemeral append ?ephemeral=true to the auth key or OAuth client secret.

TS_DEST_IP

Proxy all incoming Tailscale traffic to the specified destination IP.

TS_HEALTHCHECK_ADDR_PORT

Deprecated. Use TS_ENABLE_HEALTH_CHECK (and optionally TS_LOCAL_ADDR_PORT) instead from 1.78.

TS_LOCAL_ADDR_PORT

Specifies the [<addr>]:<port> on which to serve local metrics and health check HTTP endpoints if enabled through TS_ENABLE_METRICS or TS_ENABLE_HEALTH_CHECK. Defaults to [::]:9002 on all available interfaces.

TS_ENABLE_HEALTH_CHECK

Set to true to enable an unauthenticated /healthz endpoint at the address specified by TS_LOCAL_ADDR_PORT.

The health check returns 200 OK if the node has at least one tailnet IP address, otherwise it returns 503.

TS_ENABLE_METRICS

Set to true to enable an unauthenticated /metrics endpoint at the address specified by TS_LOCAL_ADDR_PORT.

Refer to client metrics for more information about the metrics.

TS_HOSTNAME

Use the specified hostname for the node. This is equivalent to tailscale set --hostname=.

TS_KUBE_SECRET

If running in Kubernetes, the Kubernetes secret name where Tailscale state is stored. The default is tailscale.

If TS_AUTHKEY is not set, and TS_KUBE_SECRET contains a secret with an authkey field, that key is used as a Tailscale auth key.

TS_OUTBOUND_HTTP_PROXY_LISTEN

Set an address and port for the HTTP proxy. This will be passed to tailscaled --outbound-http-proxy-listen=. For example, to set the SOCKS5 proxy to port 1055, this is :1055, which is equivalent to tailscaled --outbound-http-proxy-listen=:1055.

TS_ROUTES

Advertise subnet routes. This is equivalent to tailscale set --advertise-routes=. To accept advertised routes, use TS_EXTRA_ARGS to pass in --accept-routes.

TS_SERVE_CONFIG

Accepts a JSON file to programmatically configure Serve and Funnel functionality. Use tailscale serve status --json to export your current configuration in the correct format.

If this file is bind mounted using a Docker volume, it must be done so as a directory and not an individual file for configuration updates to be correctly detected.

TS_SOCKET

Unix socket path used by the Tailscale binary, where the tailscaled LocalAPI socket is created. The default is /var/run/tailscale/tailscaled.sock. This is equivalent to tailscaled tailscale --socket=.

TS_SOCKS5_SERVER

Set an address and port for the SOCKS5 proxy. This will be passed to tailscaled --socks5-server=. For example, to set the SOCKS5 proxy to port 1055, this is :1055, which is equivalent to tailscaled --socks5-server=:1055.

TS_STATE_DIR

Directory where the state of tailscaled is stored. This needs to persist across container restarts. This will be passed to tailscaled --statedir=.

When running on Kubernetes, state is stored by default in the Kubernetes secret with name:tailscale. To store state on local disk instead, set TS_KUBE_SECRET="" and TS_STATE_DIR=/path/to/storage/dir.

TS_USERSPACE

Enable userspace networking, instead of kernel networking. Enabled by default. This is equivalent to tailscaled --tun=userspace-networking.

Extra arguments

TS_EXTRA_ARGS

Any other flags to pass in to the Tailscale CLI in a tailscale set command.

TS_TAILSCALED_EXTRA_ARGS

Any other flags to pass in to tailscaled.

Code examples

Below is a complete Docker Compose code snippet utilizing an OAuth client secret.

---
version: "3.7"
services:
  tailscale-nginx:
    image: tailscale/tailscale:latest
    hostname: tailscale-nginx
    environment:
      - TS_AUTHKEY=tskey-client-notAReal-OAuthClientSecret1Atawk
      - TS_EXTRA_ARGS=--advertise-tags=tag:container
      - TS_STATE_DIR=/var/lib/tailscale
      - TS_USERSPACE=false
    volumes:
      - ${PWD}/tailscale-nginx/state:/var/lib/tailscale
    devices:
      - /dev/net/tun:/dev/net/tun
    cap_add:
      - net_admin
      - sys_module
    restart: unless-stopped
  nginx:
    image: nginx
    depends_on:
      - tailscale-nginx
    network_mode: service:tailscale-nginx

More examples can be found in tailscale-dev/docker-guide-code-examples.