Skip to main content

​
Overview

Before deploying any ScaleTail service, you need to set up Tailscale authentication and configure your network. This guide walks you through generating auth keys and managing your Tailscale network (Tailnet).

​
Generating Authentication Keys

Tailscale auth keys allow your Docker containers to automatically join your Tailnet without manual intervention.

​
Steps to Create an Auth Key

1

Access the Admin Console

Navigate to the Tailscale Admin Console
2

Generate a New Key

Click on Generate auth key in the Keys section
3

Configure Key Settings

Set the following options based on your needs:
  • Reusable: Enable if you plan to use this key for multiple devices
  • Ephemeral: Enable if you want devices to be automatically removed when they go offline
  • Pre-approved: Enable to skip device authorization
  • Tags: Add tags to organize and apply ACL rules to your devices
4

Copy and Store

Copy the generated key and store it securely. You’ll use this as the TS_AUTHKEY environment variable.
Auth keys are sensitive credentials. Never commit them to version control. Always use environment variables or secrets management.
For ScaleTail deployments, we recommend the following settings:
​
Reusable
boolean
default:"true"
Enable this to use the same key across multiple service deployments
​
Ephemeral
boolean
default:"false"
Keep disabled for persistent services that should remain in your network
​
Pre-approved
boolean
default:"true"
Enable to allow automatic device authorization during deployment
​
Expiration
string
default:"90 days"
Set an appropriate expiration period. Consider using tags with never-expiring keys for production services

​
Using Auth Keys in ScaleTail

Once you have your auth key, add it to your .env file:
.env
TS_AUTHKEY=tskey-auth-xxxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SERVICE=jellyfin
TS_CERT_DOMAIN=jellyfin.your-tailnet.ts.net
IMAGE_URL=jellyfin/jellyfin:latest
The TS_AUTHKEY is automatically consumed by all ScaleTail service configurations through the Docker Compose environment variables.

​
Managing Devices in Admin Console

​
Viewing Your Devices

After deploying a service, it will appear in your Machines page:
  1. Machine Name: The hostname you specified in your compose.yaml
  2. IP Address: The Tailscale IP assigned to your container
  3. Status: Online/Offline status
  4. Last Seen: Timestamp of last activity

​
Key Management Tasks

If you didn’t use pre-approved keys, you’ll need to manually approve new devices:
  1. Go to the Machines page
  2. Find your device in the “Pending” section
  3. Click Approve to add it to your Tailnet
Tags help organize devices and apply ACL rules:
  1. Click on a device in the Machines page
  2. Navigate to the Tags section
  3. Add tags like tag:docker, tag:media, or tag:admin
  4. Save your changes
These tags can be referenced in your ACL policies for fine-grained access control.
To remove a device from your Tailnet:
  1. Click on the device in the Machines page
  2. Click the … menu
  3. Select Delete
  4. Confirm the deletion
Deleting a device will immediately revoke its access to your Tailnet.
To change a device’s display name:
  1. Click on the device in the Machines page
  2. Click on the current name
  3. Enter a new name
  4. Save your changes
This is cosmetic and doesn’t affect the device’s hostname or DNS entries.

​
Access Control Lists (ACLs)

ACLs define which devices can communicate with each other in your Tailnet. This is crucial for security when running multiple services.

​
Basic ACL Example

Here’s a simple ACL that allows all devices to communicate: 
{
  "acls": [
    {
      "action": "accept",
      "src": ["*"],
      "dst": ["*:*"]
    }
  ]
}

​
Tagged ACL Example

For more granular control using tags: 
{
  "tagOwners": {
    "tag:docker": ["autogroup:admin"],
    "tag:media": ["autogroup:admin"],
    "tag:admin": ["autogroup:admin"]
  },
  "acls": [
    {
      "action": "accept",
      "src": ["autogroup:admin"],
      "dst": ["tag:admin:*"]
    },
    {
      "action": "accept",
      "src": ["autogroup:member"],
      "dst": ["tag:media:*"]
    }
  ]
}
Edit your ACLs at https://login.tailscale.com/admin/acls

​
MagicDNS Configuration

MagicDNS automatically assigns DNS names to your devices based on their hostname.

​
Enabling MagicDNS

  1. Go to DNS Settings
  2. Enable MagicDNS
  3. Optionally configure a custom domain suffix

​
Using MagicDNS with ScaleTail

When MagicDNS is enabled, uncomment the TS_ACCEPT_DNS line in your compose files: 
environment:
  - TS_ACCEPT_DNS=true # Uncomment when using MagicDNS
Your services will be accessible via hostnames like:
  • jellyfin.your-tailnet.ts.net
  • portainer.your-tailnet.ts.net

​
Security Best Practices

Rotate Keys Regularly

Generate new auth keys periodically and update your deployments to minimize exposure from compromised keys.

Use Tagged Keys

Apply tags to auth keys to automatically assign ACL rules to new devices.

Enable Key Expiration

Set expiration dates on auth keys to limit their lifetime and reduce security risks.

Monitor Device Activity

Regularly review the Machines page to identify and remove unused or suspicious devices.

​
Troubleshooting

Symptoms: Container starts but doesn’t appear in Tailscale admin consoleSolutions:
  • Verify TS_AUTHKEY is correctly set in your .env file
  • Check that the auth key hasn’t expired
  • Ensure the container has the net_admin capability
  • Verify /dev/net/tun device is accessible
Symptoms: Error message about invalid or expired keySolutions:
  • Generate a new auth key from the admin console
  • Verify you copied the entire key string
  • Check if the key has reached its usage limit (for non-reusable keys)
Symptoms: Device appears in admin console but shows offline statusSolutions:
  • Check container logs: docker compose logs tailscale
  • Verify network connectivity from the container
  • Ensure health check is passing
  • Restart the Tailscale container

​
Next Steps

Sidecar Pattern

Learn how the Docker sidecar pattern works in ScaleTail

Environment Variables

Complete reference for all Tailscale environment variables

Serve vs Funnel

Understand when to use Serve or Funnel for exposing services

Deploy a Service

Deploy your first ScaleTail service

Build docs developers (and LLMs) love

Get started for freeTalk to us