DDEV Tailscale Router

• Overview
• Use Cases
• Prerequisites
• Installation
• Usage
• Advanced Customization
• Components of the Repository
• Testing
• Contributing
• License

Overview

Tailscale is a VPN service that creates a private and secure network between your devices.

This add-on integrates Tailscale into your DDEV project. Unlike temporary sharing solutions, this gives you permanent, human-readable URLs that work across all your Tailscale-connected devices.

Read the full blog post: Tailscale for DDEV: Simple and Secure Project Sharing

Use Cases

This add-on is particularly useful for:

• Cross-device testing: Test your sites on phones, tablets, or other devices without being on the same Wi-Fi network
• Stable webhook URLs: Use permanent Tailscale URLs as reliable endpoints for webhooks from payment gateways, APIs, etc.
• Team collaboration: Share your development environment with team members to show work in progress
• Remote development: Access your local development sites securely from anywhere

Prerequisites

Before installing the add-on:

1. Install Tailscale on any two devices (computer, phone, or tablet). This is required to generate the auth key.

2. Enable HTTPS in your DNS settings by clicking "Enable HTTPS..." (required for TLS certificate generation).

3. Generate an auth key in your Keys settings (ephemeral, reusable keys are recommended).

   Get the auth key and add it to your environment by updating ~/.bashrc, ~/.zshrc, or another relevant shell configuration file with this command:

   echo 'export TS_AUTHKEY=tskey-auth-your-key-here' >> ~/.bashrc

   Alternatively, you can set it per project (NOT RECOMMENDED, because .ddev/.env.tailscale-router is not intended to store secrets) using:

   ddev dotenv set .ddev/.env.tailscale-router --ts-authkey=tskey-auth-your-key-here

4. For public access: Configure your Access Control List (ACL) to enable Funnel. Add the funnel node attribute to your ACL policy in the Tailscale admin console:

   {
     "nodeAttrs": [
       {
         "target": ["*"],
         "attr": ["funnel"]
       }
     ]
   }

Installation

ddev add-on get atj4me/ddev-tailscale-router
ddev restart

# Launch your project's Tailscale URL in browser
ddev tailscale launch
# Or get your project's Tailscale URL
ddev tailscale url

Your project's permanent Tailscale URL will look like: https://<project-name>.<your-tailnet>.ts.net. Also, it can be found in your Tailscale admin console.

Configure Privacy (Optional)

By default, your project is only accessible to devices on your Tailscale network (private mode). You can make it publicly accessible:

# Switch to public mode (accessible to anyone on the internet)
ddev dotenv set .ddev/.env.tailscale-router --ts-privacy=public
ddev restart

# Switch back to private mode (default)
ddev dotenv set .ddev/.env.tailscale-router --ts-privacy=private
ddev restart

Usage

Access all Tailscale CLI commands plus helpful shortcuts:

Command	Description
ddev tailscale <anything>	Run any Tailscale CLI command
ddev tailscale launch	Launch your project's Tailscale URL in browser
ddev tailscale status	Show Tailscale status
ddev tailscale ping <device>	Ping a Tailscale device
ddev tailscale stat	Show status with self and active peers only
ddev tailscale proxy	Show funnel status
ddev tailscale url	Get your project's Tailscale URL
ddev logs -s tailscale-router	Show logs for the Tailscale router service

Advanced Customization

To change the used Docker image:

ddev dotenv set .ddev/.env.tailscale-router --ts-docker-image=tailscale/tailscale:latest
ddev restart

All customization options (use with caution):

Variable	Flag	Default
TS_DOCKER_IMAGE	--ts-docker-image	tailscale/tailscale:latest
TS_AUTHKEY	--ts-authkey	(none, required, not recommended to set in .ddev/.env.tailscale-router)
TS_PRIVACY	--ts-privacy	private (private/public)

Components of the Repository

• install.yaml - DDEV add-on installation manifest that copies necessary files and shows setup instructions
• docker-compose.tailscale-router.yaml - Core Docker Compose configuration defining the tailscale-router service with Tailscale authentication and socat traffic forwarding
• commands/host/tailscale - Custom DDEV host command providing access to Tailscale CLI with helpful shortcuts
• tailscale-router/config/ - JSON configuration files for Tailscale's serve command:
  • tailscale-private.json - Private sharing configuration (default)
  • tailscale-public.json - Public sharing configuration
• tests/test.bats - Automated test script for verifying Tailscale integration
• .github/workflows/tests.yml - GitHub Actions for automated testing on push and schedule
• .github/ISSUE_TEMPLATE/ and PULL_REQUEST_TEMPLATE.md - Templates for streamlined contributions

Testing

This add-on includes automated tests to ensure that the Tailscale router works correctly inside a DDEV environment.

To run tests locally:

bats tests/test.bats

Tests also run automatically in GitHub Actions on every push.

Contributing

Contributions are welcome! If you have suggestions, bug reports, or feature requests, please:

1. Fork the repository.
2. Create a new branch.
3. Make your changes.
4. Submit a pull request.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

---

Maintained by @atj4me 🚀

Let me know if you want any tweaks! 🎯