Tailscale side-car container that shares certs with other services

This repository provides a custom Docker image based on the official Tailscale image. It is designed to serve as a sidecar container, enabling secure Tailscale networking within your Docker Compose stack. This image also includes scripts to manage and regenerate Tailscale certificates periodically.

Available on Docker Hub

This container is available on Docker Hub at ericwastakenondocker/tailscale-sharing-certs.

Overview

This repository contains a Dockerfile and related scripts to create a custom Docker image that wraps the Tailscale client. The image serves as a sidecar container providing a secure Tailscale network for your services within a Docker Compose stack. It also includes cron jobs to ensure that Tailscale certificates are regularly updated.

Features

Tailscale Integration: Utilizes the official Tailscale image as the base.
Certificate Generation: Automatically generates and updates Tailscale certificates.
Cron Jobs: Manages cron jobs to regularly regenerate certificates weekly (Sunday at 4 AM).

Getting Started

To build this image, use the included x_build.sh script. The script will build the container and tag it with the version number in the build-manifest.env file. Edit the manifest file to change the version number and image name as needed. The build script supports a multi-architecture build using the buildx feature of Docker.

When you're ready to publish the image to Docker Hub, use the x_deploy.sh script. This script will tag "latest" and push the image to the Docker Hub repository specified in the build-manifest.env file. The deploy script supports a multi-architecture push using the buildx feature of Docker.

Scripts baked into the image

These are the key scripts included in the image once it is built:

ts-entrypoint.sh: The main entrypoint script for the Docker container. It starts the Tailscale daemon, generates the initial certificate, and sets up the cron job to regenerate the certificate periodically.
ts-certgen.sh: This script is invoked to generate a Tailscale certificate for the specified domain name. It should be run as a cron job to keep the certificate up to date.
ts-manage-cron.sh: Ensures that a cron job is set up to run ts-certgen.sh at regular intervals (every Sunday at 4 AM) to keep the certificate updated.

How to share the certificates with other services

To share the certificates with other services in your Docker Compose stack, you can bind mount or use a volume pointing to the /certs directory. You will want to do this on the tailscale container and any other services that need access to the certificates. This will allow the other services to use the Tailscale certificates generated by this container.

The certificates will be given a name using the domain name specified in the TS_HOST_FQDN environment variable.

A typical example using Docker volumes would look like the following:

services:
  # This is the Tailscale service that will host the Tailscale network and share the certificates with other services
  ts-nginx:
    image: ericwastakenondocker/tailscale-sharing-certs:latest
    container_name: ts-$TS_HOSTNAME
    restart: unless-stopped
    hostname: $TS_HOSTNAME
    environment:
      - TS_AUTHKEY=$TS_AUTHKEY
      - TS_STATE_DIR=/var/lib/tailscale
      - TS_DOMAIN_NAME=$TS_HOST_FQDN
    volumes:
      # Persist Tailscale State so that the service can be restarted without losing the network authentication
      - ts-nginx-state:/var/lib/tailscale
      # Persist Tailscale Certificates so that other services can use them
      - ts-nginx-certs:/certs
      # Networking Juju
      - /dev/net/tun:/dev/net/tun
    # More networking Juju
    cap_add:
      - net_admin
      - sys_module

  # This is the service we want to expose on the Tailscale network
  nginx:
    image: nginx:latest
    container_name: ts-$TS_HOSTNAME-nginx
    restart: unless-stopped
    # Networking for this service is provided by the Tailscale service above
    network_mode: service:ts-nginx
    depends_on:
      - ts-nginx
    volumes:
      # Map in the persisted Tailscale Certificates
      - ts-nginx-certs:/certs
      # Map in the nginx configuration template (which has variables that need to be replaced)
      - ./nginx_conf/nginx-template.conf:/etc/nginx/nginx-template.conf:ro
    environment:
      - TS_HOST_FQDN=${TS_HOST_FQDN}
    # Change the entrypoint to use envsubst to replace the variables in the template for nginx.conf
    # This makes it easier to subst in the certificate names from Tailscale
    entrypoint: [
      "sh", "-c",
      "envsubst < /etc/nginx/nginx-template.conf > /etc/nginx/nginx.conf && nginx -g 'daemon off;'"
    ]

# Persist the Tailscale State and Certificates
volumes:
  ts-nginx-state:
  ts-nginx-certs:

Notice:

Environment variables are used which you should set in your .env file or in your Docker Compose file.
The volume ts-nginx-ceets is used to share the certificates with the nginx service and is mapped into both services. You can call this volume whatever you like, so long as it's mapped properly inside the services that need it. For the tailscale service, it should be mapped to /certs and for the other services, it should be mapped to the directory where the certificates are needed by that other service.

Examples

The examples directory contains examples of how to use the Tailscale sidecar container. Please refer to the README file in each example for the particular setup details for each.

Examples:

Tailscaled Nginx

Contributing

Contributions are welcome! Please fork the repository and submit a pull request with your changes.

License

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

ericwastaken/docker-tailscale-sharing-certs