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.

Pull image

To pull the image, run:

docker pull tailscale/tailscale:latest

docker pull ghcr.io/tailscale/tailscale:latest

The current version of the Makefile required for the examples in this doc is in the tailscale repo.

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 --authkey=.

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_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_HOSTNAME`

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

`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 programatically configure Serve and Funnel functionality. Use tailscale serve -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 utlizing 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.