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

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`

Enable a health check endpoint by setting TS_HEALTHCHECK_ADDR_PORT to a [<addr>]:<port> value. The container will serve an unauthenticated HTTP health check at the /healthz path of that address.

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

`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
      - /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.