Configuring Tailscale Networking on Debian

This note documents a straightforward approach to deploying tailscale/tailscale on Debian with Docker Compose, allowing the current machine to join your Tailscale network for remote access, private network connectivity, and cross-device networking.

1. Objective

After completing the procedure, you will have:

  • a reusable compose.yml
  • a Tailscale container that starts automatically after reboot
  • the current Debian host joined to the tailnet
  • commands to verify both Tailscale status and the assigned overlay-network IP

2. Prerequisites

Before proceeding, confirm the following:

  • the system is Debian and Docker with Docker Compose is already installed
  • the host has working outbound Internet access
  • you are signed in to the Tailscale admin console
  • you have prepared a valid auth key

To obtain an auth key:

3. Create the Directory and Configuration File

First prepare the data directory:

sudo mkdir -p /volume1/docker/tailscale

Then create compose.yml:

services:
  tailscale:
    container_name: tailscale
    image: tailscale/tailscale:latest
    network_mode: host
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
      - NET_RAW
    volumes:
      - /volume1/docker/tailscale:/var/lib/tailscale
      - /dev/net/tun:/dev/net/tun
    environment:
      - TS_STATE_DIR=/var/lib/tailscale
      - TS_USERSPACE=false
      - TS_AUTHKEY=<your_key>

4. Configuration Notes

The main configuration items serve the following purposes:

  • network_mode: host Allows the container to use the host network stack directly, which is typically the more straightforward option for Tailscale networking.
  • restart: unless-stopped Ensures that the container comes back automatically after a reboot unless it was explicitly stopped.
  • NET_ADMIN and NET_RAW Grant the network-related capabilities that Tailscale generally requires in order to operate correctly.
  • /dev/net/tun:/dev/net/tun Exposes the TUN device to the container, which is essential for Tailscale to create its virtual network interface.
  • TS_STATE_DIR=/var/lib/tailscale Specifies the state directory used to persist login state and node metadata.
  • TS_USERSPACE=false Enables kernel TUN mode rather than userspace networking.
  • TS_AUTHKEY=<your_key> Used for automatic authentication and tailnet enrollment on first startup. Note that official Tailscale auth keys are valid for up to 90 days and must be regenerated after expiration.

5. Start the Container

Run the following command in the directory that contains compose.yml:

sudo docker compose up -d

If you want to confirm that the container has started successfully, run:

sudo docker ps
sudo docker logs tailscale

6. Check Status and Tailscale IP

After startup, run the following commands to confirm that the node has joined the network:

# Check current status
docker exec -it tailscale tailscale status

# Show the local Tailscale IP
docker exec -it tailscale tailscale ip

If the configuration is correct, tailscale status will typically display:

  • the current node name
  • the authenticated account
  • other nodes in the tailnet
  • the 100.x.x.x addresses assigned within the overlay network

The tailscale ip command will return the Tailscale IP address assigned to the current device.

7. Common Operations

Restart the container:

sudo docker compose restart

Stop and remove the container:

sudo docker compose down

View logs in real time:

docker logs -f tailscale

Open a shell inside the container:

docker exec -it tailscale sh