{"id":28493074,"url":"https://github.com/hhftechnology/alpine-tailscale-caddy","last_synced_at":"2026-01-30T11:24:36.404Z","repository":{"id":270207048,"uuid":"909633527","full_name":"hhftechnology/alpine-tailscale-caddy","owner":"hhftechnology","description":null,"archived":false,"fork":false,"pushed_at":"2024-12-29T11:44:28.000Z","size":12,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-08T05:40:49.958Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hhftechnology.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-29T10:21:44.000Z","updated_at":"2024-12-29T11:44:31.000Z","dependencies_parsed_at":"2024-12-29T11:37:53.236Z","dependency_job_id":null,"html_url":"https://github.com/hhftechnology/alpine-tailscale-caddy","commit_stats":null,"previous_names":["hhftechnology/alpine-tailscale-caddy"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hhftechnology/alpine-tailscale-caddy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hhftechnology%2Falpine-tailscale-caddy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hhftechnology%2Falpine-tailscale-caddy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hhftechnology%2Falpine-tailscale-caddy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hhftechnology%2Falpine-tailscale-caddy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hhftechnology","download_url":"https://codeload.github.com/hhftechnology/alpine-tailscale-caddy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hhftechnology%2Falpine-tailscale-caddy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28911821,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-30T08:15:08.179Z","status":"ssl_error","status_checked_at":"2026-01-30T08:14:31.507Z","response_time":66,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-08T09:07:25.449Z","updated_at":"2026-01-30T11:24:36.399Z","avatar_url":"https://github.com/hhftechnology.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tailscale-Caddy Proxy\n\n[![Docker Image CI/CD](https://github.com/hhftechnology/alpine-tailscale-caddy/actions/workflows/docker-publish.yml/badge.svg?branch=main)](https://github.com/hhftechnology/alpine-tailscale-caddy/actions/workflows/docker-publish.yml)\n\nA Docker image that seamlessly enables sharing of HTTP services over the Tailscale network with automatic HTTPS support. This solution combines the power of Tailscale's secure networking with Caddy's automated certificate management to provide a robust, maintenance-free way to expose web services to authorized users.\n\n## Overview\n\nIn today's containerized environments, sharing web services securely often involves complex configuration of firewalls, authentication systems, and SSL certificates. This project simplifies that process by leveraging Tailscale's secure networking capabilities and Caddy's automatic HTTPS features.\n\n### Key Features\n\nThe Tailscale-Caddy proxy provides several advantages over alternative solutions:\n\n- Automatic SSL certificate management with zero configuration\n- Seamless service container restarts without affecting the proxy\n- Simple environment variable-based configuration\n- Secure access limited to authorized Tailscale users\n- Support for multiple services and domains\n- Zero-trust security model through Tailscale's network\n\n## How It Works\n\nThe proxy container runs two main components:\n\n1. A Tailscale daemon that connects your service to the Tailscale network\n2. A Caddy server that handles HTTPS termination and proxying\n\nWhen started, the container:\n\n1. Establishes a connection to your Tailscale network\n2. Generates a Caddy configuration based on your environment variables\n3. Automatically obtains and manages SSL certificates through Tailscale\n4. Proxies incoming requests to your service container\n\n## Prerequisites\n\nBefore using this proxy, ensure you have:\n\n1. A Tailscale account with an active tailnet\n2. HTTPS and MagicDNS enabled in your Tailscale admin console\n3. Docker and Docker Compose installed on your host system\n4. Basic familiarity with Docker networking concepts\n\n## Configuration Options\n\n### Essential Environment Variables\n\n- `TS_HOSTNAME`: The device name in your Tailscale network\n  Example: `myapp-proxy`\n\n- `TS_TAILNET`: Your tailnet name (without the .ts.net suffix)\n  Example: `mycompany`\n\n- `CADDY_TARGET`: The service endpoint to proxy to\n  Example: `webapp:8080`\n\n### Optional Parameters\n\n- `TS_EXTRA_ARGS`: Additional arguments for the Tailscale daemon\n  Example: `--advertise-exit-node --hostname=custom-name`\n\n### Volume Mounts\n\n- `/var/lib/tailscale`: Stores Tailscale credentials (required for persistence)\n\n## Usage Scenarios\n\n### Scenario 1: Basic Web Application\n\nThis example shows how to expose a simple web application:\n\n```yaml\nversion: '3'\n\nnetworks:\n  app_network:\n    external: false\n\nvolumes:\n  tailscale_state:\n\nservices:\n  webapp:\n    image: nginx\n    volumes:\n      - ./website:/usr/share/nginx/html\n    networks:\n      - app_network\n\n  tailscale_proxy:\n    image: hhftechnology/alpine-tailscale-caddy:latest\n    volumes:\n      - tailscale_state:/var/lib/tailscale\n    environment:\n      - TS_HOSTNAME=webapp-proxy\n      - TS_TAILNET=mycompany\n      - CADDY_TARGET=webapp:80\n    networks:\n      - app_network\n    restart: always\n    init: true\n```\n\n### Scenario 2: Multiple Services\n\nYou can run multiple instances of the proxy to expose different services:\n\n```yaml\nversion: '3'\n\nnetworks:\n  internal_network:\n    external: false\n\nvolumes:\n  ts_state_app1:\n  ts_state_app2:\n\nservices:\n  app1:\n    image: ghost:latest\n    networks:\n      - internal_network\n\n  app2:\n    image: wordpress:latest\n    networks:\n      - internal_network\n\n  ts_proxy_app1:\n    image: hhftechnology/alpine-tailscale-caddy:latest\n    volumes:\n      - ts_state_app1:/var/lib/tailscale\n    environment:\n      - TS_HOSTNAME=blog-proxy\n      - TS_TAILNET=mycompany\n      - CADDY_TARGET=app1:2368\n    networks:\n      - internal_network\n\n  ts_proxy_app2:\n    image: hhftechnology/alpine-tailscale-caddy:latest\n    volumes:\n      - ts_state_app2:/var/lib/tailscale\n    environment:\n      - TS_HOSTNAME=wordpress-proxy\n      - TS_TAILNET=mycompany\n      - CADDY_TARGET=app2:80\n    networks:\n      - internal_network\n```\n\n### Scenario 3: Development Environment\n\nPerfect for local development with multiple services:\n\n```yaml\nversion: '3'\n\nnetworks:\n  dev_network:\n    external: false\n\nvolumes:\n  ts_dev_state:\n\nservices:\n  frontend:\n    image: node:latest\n    command: npm run dev\n    volumes:\n      - ./frontend:/app\n    networks:\n      - dev_network\n\n  backend:\n    image: python:3.9\n    command: python manage.py runserver 0.0.0.0:8000\n    volumes:\n      - ./backend:/app\n    networks:\n      - dev_network\n\n  ts_proxy:\n    image: hhftechnology/alpine-tailscale-caddy:latest\n    volumes:\n      - ts_dev_state:/var/lib/tailscale\n    environment:\n      - TS_HOSTNAME=dev-environment\n      - TS_TAILNET=mycompany\n      - CADDY_TARGET=frontend:3000\n    networks:\n      - dev_network\n```\n\n## Setup Process\n\n1. Create your docker-compose.yml file using one of the examples above\n2. Start the containers:\n   ```bash\n   docker-compose up\n   ```\n3. Look for the authentication URL in the proxy container logs\n4. Visit the URL to authenticate the device\n5. In the Tailscale admin console:\n   - Disable key expiry for the device\n   - Configure access controls as needed\n6. Restart the containers in detached mode:\n   ```bash\n   docker-compose up -d\n   ```\n\n## Accessing Your Services\n\nAfter setup, your services will be available at:\n- `https://[TS_HOSTNAME].[TS_TAILNET].ts.net`\n- `http://[TS_HOSTNAME].[TS_TAILNET].ts.net` (automatically redirects to HTTPS)\n\nFor example:\n- `https://webapp-proxy.mycompany.ts.net`\n\n## Troubleshooting\n\nCommon issues and solutions:\n\n1. Certificate errors:\n   - Ensure HTTPS is enabled in your Tailscale admin console\n   - Verify MagicDNS is enabled\n   - Check the Caddy logs: `docker-compose logs ts_proxy`\n\n2. Connection issues:\n   - Confirm the service container is running\n   - Verify network configuration\n   - Check Tailscale device status in admin console\n\n3. Authentication problems:\n   - Re-authenticate using the URL in logs\n   - Check key expiry settings\n   - Verify ACL permissions\n\n## Security Considerations\n\nThe Tailscale-Caddy proxy provides several security benefits:\n\n1. Zero-trust network access through Tailscale\n2. Automatic HTTPS encryption\n3. Access control through Tailscale ACLs\n4. Isolated Docker networks\n5. No exposed ports on the host machine\n\n## Advanced Usage\n\n### Custom Tailscale Configuration\n\nYou can pass additional arguments to Tailscale using `TS_EXTRA_ARGS`:\n\n```yaml\nenvironment:\n  - TS_EXTRA_ARGS=--hostname=custom-name --advertise-exit-node --advertise-tags=tag:web\n```\n\n### Network Isolation\n\nCreate separate networks for different service groups:\n\n```yaml\nnetworks:\n  frontend_net:\n    internal: true\n  backend_net:\n    internal: true\n```\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Acknowledgments\n\n- Original Tailscale Docker image team\n- Caddy web server project\n- lpasselin for the initial inspiration\n- The Tailscale community\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhhftechnology%2Falpine-tailscale-caddy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhhftechnology%2Falpine-tailscale-caddy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhhftechnology%2Falpine-tailscale-caddy/lists"}