Tailscale in Docker Ubuntu Guide: Secure Networking Made Easy

Running Tailscale within a Docker container on Ubuntu is a powerful way to extend your private network and secure your applications. This comprehensive guide will walk you through setting up Tailscale in Docker on Ubuntu, leveraging the official Tailscale Docker image for a seamless and secure networking experience. We’ll cover everything from pulling the image to advanced configurations, ensuring your Ubuntu Docker containers are securely connected to your Tailscale network.

Pulling the Tailscale Docker Image

The first step is to pull the official Tailscale Docker image. Tailscale maintains and builds this image directly from source, ensuring you get the latest features and security updates. You can find the image on both Docker Hub and GitHub Packages.

To pull the latest stable image from Docker Hub, use the following command in your Ubuntu terminal:

docker pull tailscale/tailscale:latest

Alternatively, you can pull the image from GitHub Packages:

docker pull ghcr.io/tailscale/tailscale:latest

Both commands achieve the same result, downloading the official Tailscale Docker image to your Ubuntu system.

Understanding Supported Tags

Tailscale Docker images are tagged according to Tailscale’s versioning scheme, offering flexibility in choosing the version that best suits your needs.

• Stable Releases: For production environments, it’s recommended to use stable releases.

  • stable or latest: Always points to the most recent stable Tailscale version.
  • vX.Y.Z, vX.Y: Allows you to target a specific stable version, like v1.58.2 or v1.58.

• Unstable Releases: For testing and early access to new features, unstable releases are available.

  • unstable: Provides the latest unstable version.
  • unstable-vX.Y.Z, unstable-vX.Y.W: Lets you select a specific unstable version, such as unstable-v1.59.37.

Choosing the right tag ensures you have the desired balance between stability and access to the newest features for your Tailscale in Docker setup on Ubuntu.

Configuring Tailscale Docker Container Parameters

The Tailscale Docker image offers a range of optional parameters to customize its behavior. These environment variables allow you to configure various aspects of your Tailscale connection within the Docker container on Ubuntu.

TS_ACCEPT_DNS

By default, the Tailscale Docker container does not accept DNS configurations from the Tailscale admin console. To enable this feature and use Tailscale DNS settings within your Ubuntu Docker container, set TS_ACCEPT_DNS to true. This is particularly useful for resolving hostnames within your Tailscale network.

TS_AUTH_ONCE

The TS_AUTH_ONCE parameter controls the login behavior of the Tailscale container. When set to false (default), the container will attempt to log in every time it starts, ensuring it remains connected. Setting it to true makes the container attempt login only if it’s not already logged in, which can be useful in specific scenarios.

TS_AUTHKEY

For automated node registration and secure authentication, the TS_AUTHKEY parameter is crucial. Providing a Tailscale auth key to this environment variable is equivalent to using tailscale login --auth-key= in the command line. This method is recommended for Docker deployments on Ubuntu, especially in automated setups.

You can also use an OAuth client secret with TS_AUTHKEY. In this case, you must also include the tag associated with the OAuth client using TS_EXTRA_ARGS=--advertise-tags=tag:ci. Furthermore, to mark the containerized node as ephemeral, append ?ephemeral=true to the auth key or OAuth client secret.

TS_DEST_IP

The TS_DEST_IP parameter allows you to proxy all incoming Tailscale traffic to a specific destination IP address. This can be useful for directing traffic to a particular service running within your Docker container or on your Ubuntu host.

TS_ENABLE_HEALTH_CHECK and TS_LOCAL_ADDR_PORT

Introduced in Tailscale version 1.78, TS_ENABLE_HEALTH_CHECK enables a /healthz endpoint for monitoring the Tailscale container’s health. When set to true, it exposes this endpoint at the address specified by TS_LOCAL_ADDR_PORT (defaulting to [::]:9002). The health check returns 200 OK if the node has a Tailscale IP address and 503 otherwise.

TS_ENABLE_METRICS and TS_LOCAL_ADDR_PORT

Also available from Tailscale 1.78 onwards, TS_ENABLE_METRICS enables a /metrics endpoint at the address defined by TS_LOCAL_ADDR_PORT (default: [::]:9002). Set TS_ENABLE_METRICS to true to expose Prometheus-formatted metrics about the Tailscale client, providing insights into its performance and connection status within your Ubuntu Docker environment. Refer to Tailscale client metrics documentation for details on available metrics.

TS_HOSTNAME

To customize the hostname of your Tailscale node within the Docker container, use the TS_HOSTNAME parameter. This is equivalent to using tailscale set --hostname=. Setting a descriptive hostname makes it easier to identify your Docker containerized node in the Tailscale admin console.

TS_KUBE_SECRET

When running Tailscale in Docker within a Kubernetes environment on Ubuntu, TS_KUBE_SECRET specifies the Kubernetes secret name where Tailscale state is stored. By default, it’s set to tailscale. If TS_AUTHKEY is not provided, and the specified Kubernetes secret contains an authkey field, that key will be used for Tailscale authentication.

TS_OUTBOUND_HTTP_PROXY_LISTEN and TS_SOCKS5_SERVER

These parameters allow you to configure HTTP and SOCKS5 proxies for outbound traffic from your Tailscale Docker container. TS_OUTBOUND_HTTP_PROXY_LISTEN sets the address and port for an HTTP proxy, while TS_SOCKS5_SERVER does the same for a SOCKS5 proxy. These parameters are passed to tailscaled --outbound-http-proxy-listen= and tailscaled --socks5-server= respectively. For example, setting TS_SOCKS5_SERVER to :1055 is equivalent to tailscaled --socks5-server=:1055.

TS_ROUTES

To advertise subnet routes from your Tailscale Docker container, use the TS_ROUTES parameter. This is equivalent to tailscale set --advertise-routes=. Specify routes in CIDR notation, separated by commas. To accept advertised routes from other nodes in your Tailscale network, you need to use TS_EXTRA_ARGS to pass in --accept-routes.

TS_SERVE_CONFIG

The TS_SERVE_CONFIG parameter allows you to programmatically configure Tailscale Serve and Funnel features by providing a JSON configuration file. This is useful for dynamically setting up web services and funnels exposed through Tailscale. If you bind mount this configuration file using a Docker volume on Ubuntu, ensure you mount it as a directory, not an individual file, for configuration updates to be detected correctly. You can export your current Serve configuration using tailscale serve status --json.

TS_SOCKET

TS_SOCKET defines the Unix socket path used by the Tailscale binary for the tailscaled LocalAPI socket. The default path is /var/run/tailscale/tailscaled.sock. This parameter corresponds to tailscaled tailscale --socket=.

TS_STATE_DIR

The TS_STATE_DIR parameter specifies the directory where tailscaled stores its state. It’s crucial to persist this directory across container restarts to maintain the Tailscale connection and node identity. This parameter is passed to tailscaled --statedir=. When running on Kubernetes, state is stored in a Kubernetes secret by default. To store state on the local disk of your Ubuntu host instead, set TS_KUBE_SECRET="" and TS_STATE_DIR=/path/to/storage/dir.

TS_USERSPACE

By default, Tailscale in Docker uses userspace networking. To explicitly enable or disable userspace networking, use the TS_USERSPACE parameter. Setting it to true enables userspace networking (equivalent to tailscaled --tun=userspace-networking), while setting it to false attempts to use kernel networking, which may require additional privileges.

Utilizing Extra Arguments for Advanced Configuration

For more advanced customization, the Tailscale Docker image provides parameters to pass extra arguments to both the tailscale CLI and the underlying tailscaled daemon.

TS_EXTRA_ARGS

The TS_EXTRA_ARGS parameter allows you to pass any additional flags to the tailscale up command, offering fine-grained control over the Tailscale client’s behavior. For example, you can use this to --accept-routes, --advertise-tags, or any other valid tailscale up flags.

TS_TAILSCALED_EXTRA_ARGS

For even deeper customization, TS_TAILSCALED_EXTRA_ARGS lets you pass flags directly to the tailscaled daemon. This can be used to configure low-level settings of the Tailscale daemon. Refer to the tailscaled documentation for available flags.

Code Example: Docker Compose for Tailscale and Nginx on Ubuntu

Here’s a practical Docker Compose example demonstrating how to use Tailscale with Nginx on Ubuntu. This snippet utilizes an OAuth client secret for authentication and tags the container.

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
    restart: unless-stopped
  nginx:
    image: nginx
    depends_on:
      - tailscale-nginx
    network_mode: service:tailscale-nginx

This Docker Compose file defines two services: tailscale-nginx and nginx. The tailscale-nginx service runs the Tailscale Docker image with specified environment variables for authentication, tagging, and state persistence. It also mounts the /dev/net/tun device and requires net_admin capabilities for kernel networking (if TS_USERSPACE=false). The nginx service is configured to use the network namespace of the tailscale-nginx service, effectively running Nginx within the Tailscale network.

For more comprehensive examples and use cases, refer to the tailscale-dev/docker-guide-code-examples repository on GitHub.

By following this guide, you can effectively set up Tailscale in Docker on Ubuntu, securing your containerized applications and extending your private network seamlessly. This approach provides a robust and flexible solution for secure remote access and network connectivity for your Docker workloads on Ubuntu.