DOCSEARCHbyAlgolia
Submit Docs

Wiredoor Documentation

repository·main·Indexed 23 days ago

https://github.com/wiredoor/wiredoor

An open-source ingress-as-a-service platform that uses WireGuard VPN tunnels and NGINX to securely expose private services to the internet without opening firewall ports. Features include a Web UI for management, a CLI client (wiredoor-cli) for node registration and service exposure, OAuth2-based authentication via oauth2-proxy, and automatic SSL/TLS certificates via Let's Encrypt. Supports deployment via Docker and integration with Cloudflare and GoDaddy DNS.

Tokens
18.4K
Snippets
53
Records
116
Agent score
82%

What's inside Wiredoor

  1. Overview of Wiredoor

    main

    Wiredoor is a self-hosted, open-source ingress-as-a-service platform. It allows you to securely expose applications and services running in private or local networks to the internet using a reverse VPN tunnel powered by WireGuard and an NGINX reverse proxy.

    Key features include:

    • Secure VPN tunnel: Low latency WireGuard connections.
    • Reverse proxy: Built-in NGINX support.
    • Authentication: OAuth2-based support (Google, GitHub, etc.) via oauth2-proxy.
    • SSL/TLS: Automatic Let's Encrypt certificates or self-signed fallbacks.
    • Websocket Support: Out-of-the-box support for WebSocket connections.
    • Management: Web UI for nodes/services/domains and a CLI client (wiredoor-cli).
    • Multi-environment: Supports Kubernetes, Docker, legacy servers, and IoT.

  2. What is Wiredoor?

    main

    Wiredoor is a self-hosted, open-source Ingress-as-a-Service platform that allows you to expose internal services (Docker containers, on-prem servers, IoT devices, etc.) from private networks to the public internet without opening firewall ports.

    It works by creating a reverse VPN tunnel using WireGuard. Instead of requiring inbound access to your local environment, your internal services establish outbound, encrypted connections to a public-facing Wiredoor Server. Traffic from the internet is then routed through this secure tunnel to your services based on domain-based rules.

  3. Key features of Wiredoor

    main

    Wiredoor provides several capabilities for managing secure ingress:

    • Secure Tunneling: Lightweight VPN via WireGuard.
    • Reverse Proxying: Built-in NGINX reverse proxy support.
    • Authentication: OAuth2-based authentication per domain and service (supporting Google, GitHub, etc.) via oauth2-proxy.
    • SSL/TLS: Automatic SSL certificate provisioning with Let's Encrypt support.
    • Protocol Support: Ability to expose HTTP, TCP, or UDP services, including Websocket support.
    • Versatility: Works with Docker, Kubernetes, legacy servers, and IoT; supports both single-node and gateway (site-to-site) modes.
    • Automation: CLI tools for scripting and automation.

  4. Manage Wiredoor access tokens

    main

    Every node (CLI clients, gateways, etc.) uses a unique access token for identification and permission scoping.

    Best practices for token management:

    • Store tokens securely in config.ini or Kubernetes Secrets.
    • Never hardcode tokens in public repositories.
    • Rotation: Use the wiredoor regenerate command to rotate tokens regularly.
    • Revocation: If a node is compromised, revoke the token immediately or regenerate the node configuration.
    wiredoor regenerate

  5. How Wiredoor Kubernetes Gateway works

    main

    The Wiredoor Kubernetes Gateway establishes a secure, low-latency reverse VPN tunnel using WireGuard between a private Kubernetes cluster and a public Wiredoor server.

    Workflow:

    1. An agent (the Gateway) is installed inside your cluster via Helm.
    2. The agent connects to your public Wiredoor server over the WireGuard tunnel.
    3. The Wiredoor server proxies incoming internet traffic through the tunnel into your cluster.
    4. The Gateway routes that traffic to specific internal Kubernetes services.

    This allows you to expose services from clusters behind NAT, firewalls, or in air-gapped/on-prem environments without opening inbound ports or using bastion hosts.

    flowchart LR
  public[(Internet)]
  wiredoor(Wiredoor Server)
  subgraph Private Network
    direction TB
    subgraph Kubernetes Network
      direction TB
      gateway[Kubernetes Client Gateway]
      services@{ shape: procs, label: "Services"}
      pods@{ shape: procs, label: "Pods"}
    end
  end

  public <-- Traffic -->
  wiredoor <--> |Traffic| gateway
  gateway == Tunnel ==> wiredoor 
  gateway <-- Traffic --> services
  services <-- Traffic --> pods

  6. Understand Node Types and Connectivity

    main

    Nodes are devices that expose services to Wiredoor. Most connect via a WireGuard VPN tunnel.

    TypeDescriptionConnectivity
    Local NodeRuns on the same server as Wiredoor. Used for services hosted on the Wiredoor host itself.No WireGuard tunnel (Direct)
    Client NodeA remote system that exposes services from that specific machine.WireGuard tunnel
    Gateway NodeA remote system acting as a site-to-site VPN bridge. Forwards traffic to any IP in its local subnet.WireGuard tunnel

    Node Lifecycle States

    • 🟢 Connected: VPN tunnel is active.
    • 🟠 Idle: Tunnel is up, but the server cannot reach the node (e.g., ICMP blocked).
    • 🔴 Disconnected: VPN tunnel is disabled.

  7. How Wiredoor's core security architecture works

    main

    Wiredoor secures services through a multi-layered approach designed for private networking and NAT traversal without opening inbound ports:

    • VPN-based reverse tunneling: Uses WireGuard to establish secure tunnels between nodes and the Wiredoor server.
    • End-to-end encryption: Traffic is encrypted between the node and the Wiredoor server.
    • TLS/SSL termination: Supports both Let's Encrypt (for public domains) and self-signed certificates (for internal domains or IP-based access).
    • Access control: Provides fine-grained restriction via CIDR/IP filters.
    • Threat detection: Integrates with CrowdSec to block malicious IPs based on NGINX access logs.

  8. Configure Domains for Traffic Routing

    main

    Domains define how traffic is routed from the public internet to your internal services. You can register multiple domains and map multiple services to each.

    Public Domains (Recommended)

    • Requirement: Must point to your Wiredoor server's public IP via A or CNAME DNS records.
    • Benefits: Automatically receive SSL certificates via Let's Encrypt. Ideal for production.

    Internal or Local Domains

    • Usage: For non-DNS registered domains (e.g., dashboard.lan, test.internal).
    • Note: Uses self-signed certificates and may trigger browser warnings unless manually trusted.

    Automatic DNS Providers

    If you configure a DNS provider (e.g., Cloudflare, GoDaddy) in the Wiredoor Server settings, Wiredoor can automatically create or update DNS records when you expose a service. This includes detecting the correct DNS zone and triggering TLS certificate issuance via Let's Encrypt.

  9. Core components of Wiredoor

    main

    Wiredoor consists of four primary components that work together to provide secure ingress:

    ComponentRole
    WireGuard VPNEstablishes the encrypted tunnel between your private nodes and the Wiredoor Server.
    NGINX ProxyRoutes incoming internet traffic to the appropriate internal services.
    Admin PanelA web UI and API used to manage domains, nodes, and SSL certificates.
    Wiredoor CLIA command-line tool used to register, connect, and expose services from your local devices.

  10. Choose between Normal and Gateway nodes

    main

    Wiredoor provides two node types depending on your exposure needs:

    • Normal Nodes: Only expose services from the local machine. Best for standalone apps, dev servers, or small deployments.
    • Gateway Nodes: Can expose services from an entire subnet. These require careful scoping using subnet definitions (e.g., 10.96.0.0/12), network policies (in Kubernetes), and IP filtering.

  11. Configure SSL certificate modes

    main

    Wiredoor automatically handles certificate renewal. Choose a mode based on your deployment:

    ModeUse Case
    Let's EncryptUse when exposing services on a valid public domain. Requires valid DNS records (A or CNAME) pointing to your Wiredoor Server.
    Self-signedUse for internal domains or IP-based access.

    Recommendation: For production-grade services, always prefer Let's Encrypt over self-signed certificates.

  12. Expose Grafana securely using the Wiredoor_Local node

    main

    By default, Grafana is only accessible on the local network (port 3000 inside the container). To access it securely over the internet, use the Wiredoor_Local node to expose it as an HTTP service. Since Grafana runs on the same Docker network as the Wiredoor server, you can use grafana as the hostname.

    Steps to expose Grafana:

    1. Open your Wiredoor Dashboard.
    2. Navigate to the Wiredoor_Local node.
    3. Add a new HTTP Service with these settings:
      • Service Name: My-Grafana-Service (or your preferred name)
      • Public Domain: grafana.yourdomain.com (ensure this domain points to your Wiredoor server's public IP)
      • Hostname/IP: grafana
      • Backend Port: 3000
    4. Click Save.

    Grafana will then be accessible at https://grafana.yourdomain.com.