Portspan: A Self-Hosted ngrok Alternative with Wildcard Subdomains
Secure and customizable HTTP tunneling for developers
1Introduction to Portspan
Portspan is a self-hosted alternative to ngrok, designed for developers needing secure HTTP tunneling. It allows exposing local ports with predictable hostnames, such as https://app.your-base-domain. The solution is built for servers you control, combining Nginx, frp, and wildcard DNS. Portspan's architecture ensures encrypted client/server transport and token authentication. It's ideal for development environments where security and customization are priorities.
2Key Components
Portspan's stack includes Nginx for TLS termination, frp for subdomain routing, and wildcard DNS for hostname management. Nginx handles public TLS and forwards HTTP to a loopback-only frp vhost. This separation keeps the frp control port and application traffic on different boundaries. The system supports both IPv4 and IPv6, with Host-header rewriting for compatibility. The architecture is documented in detail, covering components, ports, and request flow for transparency and ease of setup.
3Setup Process
Setting up Portspan requires creating DNS A records for wildcard and control-plane subdomains. The install-server.sh script generates a server token locally, which must be securely copied to clients. Clients use a wrapper script for installation and configuration. Nginx is configured for HTTP first, with HTTPS added later using Cloudflare DNS-01 for wildcard certificates. The process emphasizes security, with explicit steps for secret handling and rollback boundaries to prevent misconfigurations.
4Security Measures
Portspan enforces strict security practices, including token authentication and encrypted transport. Server tokens are generated locally and must be copied securely, never stored in Git or chat. The system uses Nginx to terminate TLS, keeping frp control ports isolated. Documentation covers threat models, secret handling, and rotation guidance. The design avoids automatic provisioning of domains or DNS records, requiring manual steps to ensure environment-specific security.
5Client Configuration
Clients install Portspan using a checksum-verified script and configure it with a server token and base domain. The tunnel command exposes local ports with optional hostname and Host-header overrides. The wrapper supports both IPv4 and IPv6, rewriting headers to avoid common dev-server issues. Configuration files are stored with strict permissions, and the client includes validation to prevent misconfigurations. This ensures reliable and secure tunneling for development workflows.
6Operational Guidance
Portspan provides detailed runbooks for setup, verification, and troubleshooting. Operators follow a checklist for preflight discovery, safe sequencing, and rollback. The system includes hygiene checks for local shell/config and templates for Nginx, systemd, and certificate renewal. Documentation covers operations, security, and architecture, ensuring transparency. This level of detail reduces risks and supports maintainability in production-like environments.
7Comparison to Cloudflare Tunnel
While Cloudflare Tunnel excels for static ingress, Portspan offers a command-driven workflow for dynamic subdomains. Portspan uses frp's native subdomain routing, allowing each client to register its own label over a single connection. This eliminates the need for dispatchers or control-plane updates per label. The solution is tailored for developers needing flexibility and security, with a focus on self-hosting and minimal external dependencies.
8Why Portspan Matters
Portspan addresses the need for a secure, self-hosted tunneling solution in development environments. Unlike ngrok, it offers full control over infrastructure and data flow. The design prioritizes security, with clear documentation and operational guidelines. By leveraging frp and Nginx, Portspan provides a customizable alternative for teams requiring predictable hostnames and encrypted transport. It's a valuable tool for developers focused on security and reproducibility.