# render-examples/tailscale architecture

> Architecture diagram of the GitHub repository render-examples/tailscale, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/render-examples/tailscale
- Repository: https://github.com/render-examples/tailscale

## Overview

##### Project type and purpose
- This is an infrastructure‐as‐code example repo that deploys a single Docker service on Render.
- Purpose: run a Tailscale subnet router in a Render Private Network, allowing zero-config VPN access (WireGuard-based) to all internal `10.x.x.x` services.

##### File structure
- Dockerfile – builds the container image with Tailscale and helper scripts.
- install-tailscale.sh / run-tailscale.sh – shell scripts to install and launch the Tailscale daemon in the container.
- render.yaml – Render’s service definition (environment variables, build & run commands).
- README.md – usage instructions and high-level architecture.

##### README for additional insights
- Shows that the container needs a TAILSCALE_AUTHKEY (one-time key) set in Render.
- Describes the subnet-router role: advertise and enable subnet routes via the Tailscale admin panel.
- Mentions interaction with Render private services via DNS + `dig`.

##### Main components and their relationships
a. Render Platform
– Build & deploy pipeline (reads Dockerfile + render.yaml).
– Hosts the Docker container as a managed service.
b. Docker Container (Subnet Router)
– Contains Tailscale daemon (installed by install-tailscale.sh).
– run-tailscale.sh boots the daemon with the AUTHKEY and registers as a subnet router.
c. Tailscale Control Plane (Tailnet)
– Coordination servers that accept AUTHKEY, authenticate, and distribute peer info.
d. Render Private Network
– Virtual network overlay (10.x.x.x) where your private services live.
– Container advertises routes into this network.
e. Other Private Services on Render
– Any other Render services marked “private” (they get internal IPs).
– DNS names resolvable from within the subnet router container.
f. End Users / Clients
– Machines on your Tailscale Tailnet.
– Access private services through the subnet router.

##### Interactions & data flows
1. Deploy pipeline pushes container to Render.
2. Container starts and runs run-tailscale.sh:
– Connects to Tailscale control plane using AUTHKEY.
– Registers as a subnet router; advertises `10.x.x.x/` routes.
3. Tailscale admin panel: operator enables advertised subnets in Tailnet settings.
4. Tailnet clients query Tailscale DNS for private service hostnames → packets flow over WireGuard tunnels to the subnet router.
5. Subnet router forwards traffic into the Render private network to the target service IPs.

##### Architectural patterns & design principles
- Single‐purpose container: minimal OS + scripts + Tailscale daemon.
- Clear separation of control plane (Tailscale servers) vs. data plane (WireGuard tunnels).
- Infrastructure‐as‐code: Dockerfile + shell scripts + render.yaml define build and deploy.
- Use of environment variables (TAILSCALE_AUTHKEY) for secrets injection.

##### Final checklist
[ ] Clear labels on all six main components
[ ] Annotation of any manual/admin steps (e.g., “Enable subnet routes in Tailnet admin UI”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Render Platform
    RP["Render Platform\n(build & deploy)"]:::platform
    click RP "https://github.com/render-examples/tailscale/blob/main/render.yaml"

    %% Docker Container
    subgraph "Docker Container"
        DF["Dockerfile"]:::container
        click DF "https://github.com/render-examples/tailscale/tree/main/Dockerfile"
        IT["install-tailscale.sh"]:::script
        click IT "https://github.com/render-examples/tailscale/blob/main/install-tailscale.sh"
        RT["run-tailscale.sh"]:::script
        click RT "https://github.com/render-examples/tailscale/blob/main/run-tailscale.sh"
    end

    %% Tailscale Control Plane
    TC["Tailscale Control Plane"]:::external

    %% Render Private Network
    RN["Render Private Network\n(10.x.x.x)"]:::network

    %% Private Services
    PS["Private Services on Render"]:::service

    %% Tailnet Clients
    TCli["Tailnet Clients"]:::client

    %% Admin Manual Step
    Admin["Enable subnet routes\nin Tailnet Admin UI"]:::manual

    %% Documentation
    Doc["README.md"]:::doc
    click Doc "https://github.com/render-examples/tailscale/blob/main/README.md"

    %% Connections
    RP -->|"Docker build & deploy"| DF
    DF -->|"includes install script"| IT
    IT -->|"prepares daemon"| RT
    RT -->|"auth + register"| TC
    TC -->|"peer exchange"| RT
    RT -->|"advertise routes"| RN
    Admin -.->|"manual enable"| TC
    TCli -->|"WireGuard tunnel"| RT
    RT -->|"forward traffic"| PS

    %% Styles
    classDef platform fill:#dbf4ff,stroke:#009,stroke-width:1px;
    classDef container fill:#fff4c2,stroke:#b07,stroke-width:1px;
    classDef external fill:#d0e6a5,stroke:#5a5,stroke-width:1px;
    classDef network fill:#ffddb3,stroke:#d97706,stroke-width:1px;
    classDef service fill:#f0e6ff,stroke:#6a0dad,stroke-width:1px;
    classDef client fill:#ffd1d1,stroke:#d12,stroke-width:1px;
    classDef manual fill:#e2e2e2,stroke:#888,stroke-width:1px,stroke-dasharray: 5 5;
    classDef script fill:#f9f,stroke:#c06,stroke-width:1px;
    classDef doc fill:#d0f0fd,stroke:#07a,stroke-width:1px;
```
