dropshell-templates/tailscale

Tailscale VPN Service Template
==============================

This template deploys Tailscale as a Docker container, providing secure network access
to your server through Tailscale's zero-config VPN.

REQUIREMENTS
------------
* A Tailscale account (free at https://tailscale.com)
* An auth key from https://login.tailscale.com/admin/settings/keys
* Docker installed on the host system

CONFIGURATION
-------------
Before installation, you MUST set the following in your service configuration:

1. TAILSCALE_AUTH_KEY (required)
   - Generate at: https://login.tailscale.com/admin/settings/keys
   - Can be reusable or one-time use
   - Required for automatic connection

2. TAILSCALE_HOSTNAME (optional)
   - Custom hostname for this node in your Tailscale network
   - If not set, uses the system hostname

3. TAILSCALE_EXTRA_ARGS (optional)
   - Additional Tailscale arguments
   - Examples:
     --advertise-exit-node       (make this an exit node)
     --accept-routes              (accept advertised routes)
     --advertise-routes=10.0.0.0/24  (advertise local routes)

4. TAILSCALE_USERSPACE (optional)
   - Set to "true" for environments without TUN device support
   - Useful for some container platforms or restricted environments

DEFAULT SETTINGS
----------------
* Container name: tailscale
* Image: tailscale/tailscale:stable
* State volume: tailscale_state (persistent across restarts)
* Network mode: Host networking with NET_ADMIN capability

USAGE
-----
After installation, your server will be accessible through your Tailscale network:

1. Access by Tailscale IP:
   - Find IP with: ./status.sh
   - Connect via: ssh user@100.x.x.x

2. Access by MagicDNS name:
   - Enable MagicDNS in Tailscale admin console
   - Connect via: ssh user@hostname

3. Use as exit node (if configured):
   - Configure with: --advertise-exit-node in TAILSCALE_EXTRA_ARGS
   - Approve in Tailscale admin console
   - Route traffic through this server

COMMANDS
--------
* ./install.sh  - Install and start Tailscale
* ./start.sh    - Start the Tailscale container
* ./stop.sh     - Stop the Tailscale container
* ./status.sh   - Check Tailscale connection status
* ./logs.sh     - View Tailscale logs
* ./ssh.sh      - Access container shell
* ./uninstall.sh - Remove container (preserves state)
* ./destroy.sh  - Complete removal including state

TROUBLESHOOTING
---------------
1. Container won't start:
   - Check TAILSCALE_AUTH_KEY is set correctly
   - Verify Docker has necessary permissions
   - Review logs with ./logs.sh

2. Not connecting to network:
   - Ensure auth key is valid and not expired
   - Check if key is reusable if using multiple times
   - Verify no firewall blocking outbound connections

3. Can't create TUN device:
   - Set TAILSCALE_USERSPACE=true for userspace mode
   - This is slower but works in restricted environments

4. Need to re-authenticate:
   - Generate new auth key
   - Update configuration
   - Restart with ./start.sh

SECURITY NOTES
--------------
* Auth keys should be kept secret
* Use ephemeral keys for temporary access
* Regularly review connected devices in admin console
* Consider using ACLs to restrict access

RESOURCES
---------
* Tailscale Documentation: https://tailscale.com/kb/
* Admin Console: https://login.tailscale.com/admin/
* ACL Guide: https://tailscale.com/kb/1018/acls/