{"id":28092390,"url":"https://github.com/hhftechnology/failover-newt-tc","last_synced_at":"2025-05-13T13:10:02.964Z","repository":{"id":290060969,"uuid":"969157635","full_name":"hhftechnology/failover-newt-tc","owner":"hhftechnology","description":"This solution provides seamless failover between two popular networking tools without dropping connections or requiring manual intervention.","archived":false,"fork":false,"pushed_at":"2025-05-07T17:07:55.000Z","size":487,"stargazers_count":37,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-07T18:24:25.336Z","etag":null,"topics":["newt","pangolin","tailscale"],"latest_commit_sha":null,"homepage":"https://forum.hhf.technology/t/complete-setup-guide-for-newt-tailscale-failover-gateway/","language":"JavaScript","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,"zenodo":null}},"created_at":"2025-04-19T14:16:54.000Z","updated_at":"2025-05-07T17:07:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"58d6265f-a795-4de0-bdc1-31c874ad38ef","html_url":"https://github.com/hhftechnology/failover-newt-tc","commit_stats":null,"previous_names":["hhftechnology/failover-newt-tc"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hhftechnology%2Ffailover-newt-tc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hhftechnology%2Ffailover-newt-tc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hhftechnology%2Ffailover-newt-tc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hhftechnology%2Ffailover-newt-tc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hhftechnology","download_url":"https://codeload.github.com/hhftechnology/failover-newt-tc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253948437,"owners_count":21988957,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["newt","pangolin","tailscale"],"created_at":"2025-05-13T13:09:17.740Z","updated_at":"2025-05-13T13:10:02.941Z","avatar_url":"https://github.com/hhftechnology.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Newt-Tailscale Failover Gateway\n\nThis project provides an automatic failover solution between Newt and Tailscale. If the Newt tunnel fails, traffic is automatically redirected to Tailscale without interruption.\n\n\u003cimg src=\"images/image.png\" alt=\"Preview\"/\u003e\n\n## Features\n\n- **Automatic Failover**: Seamlessly switches to Tailscale when Newt becomes unavailable\n- **Self-healing**: Automatically returns to Newt when service is restored\n- **Configurable Health Checks**: Customize monitoring parameters\n- **Zero Downtime Switching**: Maintains connections during failover\n- **Comprehensive Logging**: Track all failover events and health status\n- **Multiple Failover Modes**: Choose between immediate or gradual failover\n\n## How It Works\n\n1. The system continuously monitors the health of the Newt tunnel connection\n2. When a failure is detected (based on configurable thresholds), the failover mechanism is triggered\n3. Traffic is automatically redirected through Tailscale while Newt is unavailable\n4. Once Newt service is restored, traffic can either be immediately switched back or gradually migrated\n\n### Important: Route Advertisement Configuration\n\nFor seamless failover, Tailscale must be configured to advertise routes to the same private network that Newt connects to. This ensures that when traffic switches from Newt to Tailscale, it can still reach the same internal services.\n\n1. Identify the private IP range(s) that your services use (e.g., 192.168.1.0/24)\n2. Configure Tailscale to advertise these routes using the `TAILSCALE_ADVERTISE_ROUTES` parameter\n3. Ensure that your Tailscale account has subnet routing enabled (may require a business plan)\n4. Approve the route advertisement in the Tailscale admin console after first deployment\n\nWithout proper route advertisement, failover may appear to work but traffic won't reach your internal services.\n\n## Prerequisites\n\n- Docker and Docker Compose\n- Tailscale account with an auth key\n- Pangolin deployment with Newt credentials\n- Basic understanding of networking concepts\n\n## Environment Variables\n\n```env\n# Core Configuration\nENABLE_FAILOVER=true\nFAILOVER_MODE=immediate  # immediate or gradual\nPRIMARY_SERVICE=newt     # newt or tailscale (which one is primary)\n\n# Health Check Configuration\nHEALTH_CHECK_INTERVAL=10        # seconds between checks\nHEALTH_CHECK_TIMEOUT=5          # seconds before a check times out\nHEALTH_CHECK_FAILURES_THRESHOLD=3  # failures before triggering failover\nHEALTH_CHECK_RECOVERY_THRESHOLD=5  # successes before switching back\n\n# Newt Configuration\nNEWT_ID=your-newt-id\nNEWT_SECRET=your-newt-secret\nPANGOLIN_ENDPOINT=https://your-pangolin-server.com\n\n# Tailscale Configuration\nTAILSCALE_AUTH_KEY=tskey-auth-xxxxx-xxxxxxxxxxxxx\nTAILSCALE_HOSTNAME=failover-gateway\nTARGET_PORTS=80,443,3000,8080  # Ports to forward via Tailscale\n\n# *** IMPORTANT: Configure route advertisement for proper failover ***\n# Advertise the same private subnets that Newt is connecting to\nTAILSCALE_ADVERTISE_ROUTES=10.0.0.0/8,172.16.0.0/12,192.168.0.0/16  # Customize to match your network\n\n# Optional Tailscale Settings\nTAILSCALE_ACCEPT_DNS=true\nTAILSCALE_ACCEPT_ROUTES=false\nTAILSCALE_ADVERTISE_EXIT_NODE=false\nTAILSCALE_SSH=false\n\n# Notification Settings (optional)\nENABLE_NOTIFICATIONS=false\nNOTIFICATION_WEBHOOK=https://your-webhook-url.com\n```\n\n## Usage Examples\n\n### Basic Failover Setup\n\n```yaml\nversion: '3'\nservices:\n  failover-gateway:\n    image: hhftechnology/failover-newt-tc:latest:latest\n    cap_add:\n      - NET_ADMIN\n    environment:\n      - ENABLE_FAILOVER=true\n      - FAILOVER_MODE=immediate\n      - PRIMARY_SERVICE=newt\n      - HEALTH_CHECK_INTERVAL=10\n      - HEALTH_CHECK_FAILURES_THRESHOLD=3\n      - NEWT_ID=your-newt-id\n      - NEWT_SECRET=your-newt-secret\n      - PANGOLIN_ENDPOINT=https://your-pangolin-server.com\n      - TAILSCALE_AUTH_KEY=tskey-auth-xxxxx-xxxxxxxxxxxxx\n      - TAILSCALE_HOSTNAME=failover-gateway\n      - TARGET_PORTS=80,3000\n      # CRITICAL: Configure Tailscale to advertise the network your services are on\n      - TAILSCALE_ADVERTISE_ROUTES=192.168.1.0/24\n    volumes:\n      - ./data/tailscale:/var/lib/tailscale\n    devices:\n      - /dev/net/tun:/dev/net/tun\n    restart: unless-stopped\n\n  webapp:\n    image: nginx:alpine\n    expose:\n      - \"80\"\n    restart: unless-stopped\n    # The internal IP range must match what's configured in TAILSCALE_ADVERTISE_ROUTES\n    networks:\n      - frontend\n\nnetworks:\n  frontend:\n    driver: bridge\n    ipam:\n      config:\n        - subnet: 192.168.1.0/24  # This subnet must be advertised in Tailscale\n```\n\n### Gradual Failover with Notifications\n\n```yaml\nversion: '3'\nservices:\n  failover-gateway:\n    image: hhftechnology/failover-newt-tc:latest:latest\n    cap_add:\n      - NET_ADMIN\n    environment:\n      - ENABLE_FAILOVER=true\n      - FAILOVER_MODE=gradual\n      - PRIMARY_SERVICE=newt\n      - HEALTH_CHECK_INTERVAL=5\n      - HEALTH_CHECK_FAILURES_THRESHOLD=5\n      - HEALTH_CHECK_RECOVERY_THRESHOLD=10\n      - NEWT_ID=your-newt-id\n      - NEWT_SECRET=your-newt-secret\n      - PANGOLIN_ENDPOINT=https://your-pangolin-server.com\n      - TAILSCALE_AUTH_KEY=tskey-auth-xxxxx-xxxxxxxxxxxxx\n      - TAILSCALE_HOSTNAME=failover-gateway\n      - TARGET_PORTS=80,443,8080\n      - ENABLE_NOTIFICATIONS=true\n      - NOTIFICATION_WEBHOOK=https://your-webhook-url.com\n    volumes:\n      - ./data/tailscale:/var/lib/tailscale\n    devices:\n      - /dev/net/tun:/dev/net/tun\n    restart: unless-stopped\n\n  api:\n    image: node:alpine\n    expose:\n      - \"80\"\n    restart: unless-stopped\n```\n\n## Architecture\n\nThe failover gateway follows this architecture:\n\n1. **Health Monitor**: Continuously checks the Newt tunnel's health\n2. **Failover Controller**: Manages switching between Newt and Tailscale\n3. **Connection Manager**: Maintains and routes active connections\n4. **Notification System**: Alerts administrators of failover events\n5. **Statistics Collector**: Tracks performance metrics and failover history\n\n## Monitoring Dashboard\n\nA simple monitoring dashboard is available at `http://[gateway-ip]:9095` showing:\n\n- Current active service (Newt or Tailscale)\n- Health status of both services\n- Failover history\n- Connection statistics\n- System resource usage\n\n## Failover Modes\n\n### Immediate Failover\n\nAll traffic is instantly redirected to the backup service when a failure is detected. This minimizes downtime but may cause some active connections to drop.\n\n### Gradual Failover\n\nNew connections are routed through the backup service, while existing connections continue through the primary service until they naturally terminate. This prevents connection disruption but may take longer to complete the failover.\n\n## Customizing Health Checks\n\nThe health monitoring system can be configured to check various aspects:\n\n- Connection status\n- Latency thresholds\n- Packet loss rates\n- Bandwidth availability\n- External endpoint accessibility\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT License - See LICENSE file for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhhftechnology%2Ffailover-newt-tc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhhftechnology%2Ffailover-newt-tc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhhftechnology%2Ffailover-newt-tc/lists"}