tailscale-dev/ScaleTail

ScaleTail is a collection of ready-to-run Docker Compose stacks that connect self-hosted applications to your Tailnet. Each stack runs a Tailscale sidecar container, so the application joins your Tailnet as its own device. Most stacks publish the application at an HTTPS address such as https://vaultwarden.<tailnet>.ts.net, reachable from your Tailnet only.

• Featured by Tailscale
• Quick Start
• Available configurations
  • Networking and security
  • Media and entertainment
  • Productivity and collaboration
  • Dashboards and visualization
  • Development tools
  • Monitoring and analytics
  • Smart home
  • Utilities
  • Food and wellness
• Update a stack
• Remove a stack
• Get help
• Tailscale Serve and Funnel
• Documentation
• Contributors
• Contributing
• Star history
• License

In this video from the Tailscale YouTube channel, Alex deploys a ScaleTail service in under 10 minutes.

You need:

• A Linux host with Docker Engine, Docker Compose 2.23.1 or later, and Git. Check the Compose version with docker compose version.
• MagicDNS and HTTPS certificates enabled for your Tailnet, on the DNS page of the admin console. Without them, the https:// address of a stack does not work. With HTTPS enabled, device names appear in public certificate transparency logs.

1. Create an auth key on the Keys page of the admin console.

   • Leave Ephemeral off. Tailscale removes an ephemeral device 30 to 60 minutes after it goes offline, for example when you stop the stack.
   • Turn on Pre-approved if your Tailnet uses device approval.
   • Turn on Reusable to use the key for more than one stack.

2. Get the stacks and choose a service.

   git clone https://github.com/tailscale-dev/ScaleTail.git
   cd ScaleTail/services/<service>

   Replace <service> with the directory from the Details link in Available configurations, for example uptime-kuma.

3. Read the service README. "Before you start" lists what the service needs beyond these steps, such as secrets to generate. Until you set them, Compose stops with an error such as required variable DB_PASSWORD is missing a value.

4. Edit .env. Open the hidden file .env, for example with nano .env. Paste your auth key after TS_AUTHKEY= and set the values that the service README asks for.

5. Start the stack.

   docker compose up -d
   docker compose ps

   The application starts after the tailscale container reports healthy. If a container is not running, read the logs with docker compose logs.

6. Open the service. From a device in your Tailnet, open the address from "At a glance" in the service README, usually https://<SERVICE>.<tailnet>.ts.net.

   • <SERVICE> is the value of SERVICE in .env.
   • <tailnet>.ts.net is your Tailnet DNS name, for example tail1234.ts.net.
   • The first request can take up to a minute, because Tailscale requests the certificate at that moment.

   Then follow "First run" in the service README. Some stacks have no web interface, and their service README says how to reach them.

7. Keep the device connected. Its node key expires after 180 days by default. To prevent that, disable key expiry for the device on the Machines page.

Every stack starts from the same standard setup, which explains the containers, the Tailnet address, the data folders, and the settings in .env.

Most stacks use the latest image tag. To get newer images, run this from the service directory:

docker compose pull
docker compose up -d

To get the latest version of the stacks, update your clone. Git does not overwrite files that you changed, such as .env, so set your changes aside first:

git stash
git pull
git stash pop

If git stash pop reports a conflict in .env, open the file, keep your values, delete the <<<<<<<, =======, and >>>>>>> lines, then run git reset and git stash drop.

Before you restart the stack, read the "Upgrading" section of the service README, if it has one.

From the service directory, run docker compose down --volumes. To remove the stack completely, also remove the device on the Machines page and delete the service directory. It contains the Tailscale state in ./ts/state and the application data. The containers create some of these folders as root, so deleting them may need sudo.

• Read the "Troubleshooting" section of the service README, and check the logs with docker compose logs.
• Ask questions in the Tailscale Discord.
• Report a problem with a stack in a GitHub issue.

Tailscale Serve routes traffic from other devices in your Tailnet to a service on one device. Tailscale Funnel routes traffic from the public internet to that service, so people without Tailscale can reach it.

Stacks that use Serve keep Funnel off ("AllowFunnel":{"$${TS_CERT_DOMAIN}:443":false} in compose.yaml), so they are reachable from your Tailnet only. Umami has an opt-in public mode; see its README.

To make a service reachable from the internet:

1. Add funnel to nodeAttrs in your Tailnet policy file for the device, as described in Tailscale Funnel.
2. In compose.yaml, change false to true in the AllowFunnel line.
3. Recreate the stack with docker compose up -d --force-recreate.

Funnel is in beta and listens only on ports 443, 8443, and 10000. It requires MagicDNS and HTTPS certificates, as in the Quick Start. Anyone on the internet can then reach the application, so turn on its login first.

In this repository:

• The standard ScaleTail setup
• Free up port 53 on the Docker host
• Install Tailscale on an OpenPLi set-top box (without Docker)

From Tailscale:

• Tailscale documentation
• Docker and its configuration parameters
• Tailscale Serve
• Tailscale Funnel
• A deep dive into using Tailscale with Docker

Thank you to everyone who has contributed to ScaleTail.

Made with contrib.rocks.

To add or update a service, follow CONTRIBUTING.md and start from the service template.

MIT