Add a Docker container

This topic is a quick guide for installing Docker and adding a container to a tailnet. For more detailed information, see Using Tailscale with Docker. For more information about using Docker products in general, see the official Docker documentation.

Install Docker

Download Docker on a Linux device or a cloud VM:

curl -fsSL https://get.docker.com -o install-docker.sh

Run the Docker installation script:
```
sudo sh install-docker.sh
```
Enter your password when prompted.
Modify your user Linux user group permission for Docker to interact with it without needing to use sudo.
```
sudo usermod -aG docker username
```

We highly recommend you also refer to the Docker topic Manage Docker as a non-root user for more information.

Log out of the terminal session then log back in to allow the permission change to occur.
Run the follow command to verify that the Docker Engine is installed:
```
docker run --rm hello-world
```

Create a container for Tailscale

You can use Docker to deploy containers for many kinds of use cases. The instructions below explain how to configure an Ngnix web server and connect it to your tailnet.

Create a Docker compose yaml file using your preferred terminal text editor:
```
vi docker-compose.yaml
```

Edit the yaml file with the details needed for your environment. The sample file below instructs Docker to create an Nginx web server container with a hostname of banana and connects it to the tailnet automatically using an auth key.

services:
  tailscale-authkey1:
    image: tailscale/tailscale:latest
    container_name: ts-authkey-test
    hostname: banana
    environment:
      - TS_AUTHKEY=tskey-auth-kJDnLXE8sT11CNTRL-GX3ZFEnSii8KCrmkf3amk87JG4VGXzP1
      - TS_STATE_DIR=/var/lib/tailscale
      - TS_USERSPACE=false
    volumes:
      - ts-authkey-test:/var/lib/tailscale
      - /dev/net/tun:/dev/net/tun
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    restart: unless-stopped
  nginx-authkey-test:
    image: nginx
    network_mode: service:tailscale-authkey1
volumes:
  ts-authkey-test:
    driver: local

In the yaml file, replace the sample auth key tskey-auth-kc4MhA5vzX11CNTRL-example with your own auth key. To do this, open the Keys page of the admin console, select Generate auth key, provide a key name, toggle Resusable to on, and select Generate key. Copy the key and paste it into the TS_AUTHKEY field.
In the yaml file, make sure the service name (immediately below services) matches the network_mode field. In the example above, the service name is tailscale-authkey1.
Save your yaml file.
Start up the container and wait for the process to complete:
```
docker compose up -d
```
Open the Machines page of the admin console, and you should now see the node banana in the list.

You can now verify that the Nginx web server is available by going to http://hostname and you should see a "Welcome to ngnix" page display. Using the example hostname above, the URL would be http://banana.

Last updated Apr 4, 2025