Tailscale for DDEV: Simple and Secure Project Sharing

I’ve found that DDEV’s ddev share command is a great way to quickly share my local development environment. However, since it uses ngrok, it requires ngrok to be installed on the host system and generates a new, random URL every time unless you use a stable domain. As an alternative, I’ve created the ddev-tailscale-router add-on.

This add-on uses Tailscale, a VPN service that creates a private and secure network between your devices. It is free for personal use and doesn’t require any additional software to be installed on your host system!

As a result, you get a stable, human-readable URL for each of your DDEV projects, which you can access from any device on your Tailscale network.

I’ve found this approach to be particularly useful for:

Cross-device testing: I can easily test my sites on my phone or tablet without being on the same Wi-Fi network.
Stable webhook URLs: I can use the permanent Tailscale URL as a reliable endpoint for webhooks, such as those from payment gateways.
Team collaboration: I can share my development environment with team members so they can see my work in progress.

How it Works

The ddev-tailscale-router add-on works by installing Tailscale directly into your DDEV project’s web container using userspace networking. This approach provides better macOS compatibility and improved reliability compared to running a separate container. The add-on automatically connects to your Tailscale network and securely proxies requests to your project.

Update: Version 3.0.0 brought significant architectural improvements! The add-on now uses YAML-based configuration, improved command structure, and better error handling. If you’re upgrading from an earlier version, see the migration instructions in the release notes.

Prerequisites

Before installing the add-on, you need to set up Tailscale:

Install Tailscale on at least two devices (phone, tablet, or computer) by following the installation guide. This is required to generate an auth key.
Enable HTTPS by following the Tailscale HTTPS documentation. This is required for TLS certificate generation.
Generate an auth key by following the Tailscale auth keys documentation. Ephemeral, reusable keys are recommended.

Installation

To get started, follow these steps:

First, set up your auth key (recommended approach): Add the auth key to your shell environment:
```
echo 'export TS_AUTHKEY=tskey-auth-your-key-here' >> ~/.bashrc
source ~/.bashrc
```
Replace ~/.bashrc with ~/.zshrc if you use Zsh, or your relevant shell configuration file.

Alternatively, you can use interactive authentication after installation by running ddev tailscale login after your project starts.

Next, install the add-on:

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

Finally, restart DDEV:
```
ddev restart
```

Using Your Tailscale URL

Once installation is complete, you need to start sharing your project:

Start sharing your project:

ddev tailscale share

Launch your project’s Tailscale URL in browser:

ddev tailscale launch

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. You can also find it in your Tailscale admin console.

To see all available commands and options, run ddev tailscale help. This will show you both the DDEV-specific shortcuts and all native Tailscale CLI commands that you can use.

Public vs. Private Mode

The add-on offers two modes for sharing your project:

Private (default): Your project is only accessible to devices on your Tailscale network.
Public: Your project is accessible to anyone on the internet.

To switch between modes:

Share publicly (accessible to anyone on the internet):

ddev tailscale share --public

Share privately (default, only accessible to your Tailscale devices):

ddev tailscale share

Stop sharing:

ddev tailscale stop

Note: For public access, you need to configure your Access Control List (ACL) to enable Funnel. See the Tailscale Funnel documentation for details on setting up the required ACL policy.

Uninstalling the Add-on

If you need to remove the add-on from your project:

Stop any active sharing:
```
ddev tailscale stop
```
Remove the add-on:
```
ddev add-on remove tailscale-router
```
Restart DDEV:
```
ddev restart
```

Additional Resources

Here are some additional resources that you might find helpful:

Tailscale: A VPN service that creates a private and secure network between your devices.
Tailscale Download: Installation guide for Tailscale on various platforms.
Tailscale: Enabling HTTPS: Official documentation on enabling HTTPS for TLS certificate generation.
Tailscale Auth Keys: Detailed information about creating and managing auth keys.
Tailscale Funnel: Documentation on enabling public access to your Tailscale services.
Tailscale DNS: DNS in Tailscale
DDEV dotenv: Documentation on managing environment variables with DDEV.
DDEV Docs: Sharing: The official DDEV documentation on how to share your projects.
Medium: My Journey with PHP Dev Environments: A blog post on setting up a PHP development environment.
LinkedIn: The Day My Development Environment Nearly Broke Me: An article on the importance of a reliable development environment.

I hope this add-on helps streamline your development workflow! If you run into any issues or have suggestions for improvements, feel free to open an issue on the GitHub repository.

This blog post was updated with the assistance of GitHub Copilot (Claude). I used it to help update the content based on the latest add-on changes, improve accuracy, and maintain consistency. The original version was written with assistance from Amazon Q and Google Gemini.