TunnelForge

TunnelForge is a lightweight, open-source, self-hosted alternative to ngrok that provides tunneling services for exposing local applications to the internet. It supports HTTP, WebSocket, and any other TCP-based protocols, allowing seamless integration with modern applications.

Demo Video

Click the image above to watch the TunnelForge demo and learn how it works in action!

Features

• Expose local services to the internet with unique subdomains.
• Support for HTTP, WebSocket, and other TCP-based protocols.
• Easy setup for local and public servers.
• Support for environment-based configurations.
• Daemonized server processes with PM2.
• DNS configuration support via Cloudflare.
• Future Docker support for containerized deployments.

Installation

1. Clone the repository:

   git clone https://github.com/elshadaghazade/tunnelforge.git
   cd tunnelforge
   Copy

2. Install dependencies:

   npm install
   Copy

3. Build the project:

   npm run build
   Copy

Usage

Development Mode

1. Start the server:

   npm run server:dev
   Copy

   The server will generate a static subdomain (sub1).
2. Add an entry to your local /etc/hosts file:

   127.0.0.1 sub1.myproxy.com
   Copy

3. Start the client:

   npm run client:dev -- -h myproxy.com -p [SERVER_PORT_FROM_ENV] -q [LOCAL_APP_PORT] -r [LOCAL_APP_HOST]
   Copy

4. Access your application using:

   http://sub1.myproxy.com:[INCOMING_PORT_FROM_ENV]
   Copy

Production Mode

1. On the server:
   • Open ports for CLIENT_SERVER_PORT and INCOMING_SERVER_PORT in your cloud environment (e.g., AWS EC2).
   • Configure DNS in Cloudflare:
     • Create an A record for *.yourdomain.com pointing to your server's IP.
   • Run the server:

     npm run server:prod
     Copy

   • PM2 users can daemonize the process:

     pm2 start ecosystem.config.js
     Copy

2. On the client:
   • Build the client:

     npm run build
     Copy

   • Run the client:

     npm run client:prod -- -h yourdomain.com -p [SERVER_PORT_FROM_ENV] -q [LOCAL_APP_PORT] -r [LOCAL_APP_HOST]
     Copy

   • After connecting, the client logs the public address:

     Your public address is http://[UNIQUE_SUBDOMAIN].yourdomain.com:[INCOMING_PORT_FROM_ENV]
     Copy

   • Access your public application using the generated public address.

Environment Variables

Set these variables in your .env.development or .env.production file:

NODE_ENV=production
CLIENT_SERVER_PORT=4000
INCOMING_SERVER_PORT=4001
SERVER_CLIENT_HOST=0.0.0.0
SERVER_INCOMING_HOST=0.0.0.0
RECONNECT_INTERVAL=1000
PROXY_SERVER_MAIN_HOST=globalmedbooking.com

CLIENT_PARAM_SERVER_HOST=127.0.0.1
CLIENT_PARAM_SERVER_PORT=4000
CLIENT_PARAM_LOCAL_APP_HOST=127.0.0.1
CLIENT_PARAM_LOCAL_APP_PORT=3010
Copy

Dockerizing TunnelForge

You can easily run both the TunnelForge server and client using Docker. This approach simplifies deployment, ensuring a consistent environment for running the application

Steps to Dockerize TunnelForge

1. Prepare the .env File

   Create an .env file in the root directory with the following contents, adjusting the values to match your desired configuration:

   NODE_ENV=production
   CLIENT_SERVER_PORT=4000
   INCOMING_SERVER_PORT=4001
   SERVER_CLIENT_HOST=0.0.0.0
   SERVER_INCOMING_HOST=0.0.0.0
   RECONNECT_INTERVAL=1000
   PROXY_SERVER_MAIN_HOST=yourcustomdomain.com
   
   CLIENT_PARAM_SERVER_HOST=127.0.0.1
   CLIENT_PARAM_SERVER_PORT=4000
   CLIENT_PARAM_LOCAL_APP_HOST=127.0.0.1
   CLIENT_PARAM_LOCAL_APP_PORT=3010
   Copy

   • Server Environment Variables:
     • CLIENT_SERVER_PORT and INCOMING_SERVER_PORT: Ports exposed by the TunnelForge server.
     • PROXY_SERVER_MAIN_HOST: Your main domain to handle subdomains.
   • Client Parameters:
     • CLIENT_PARAM_SERVER_HOST and CLIENT_PARAM_SERVER_PORT: Host and port of the TunnelForge server.
     • CLIENT_PARAM_LOCAL_APP_HOST and CLIENT_PARAM_LOCAL_APP_PORT: Host and port of the local application to expose.

2. Build and Run with Docker Compose

   The provided docker-compose.yml file is configured to build and run both the server and client. To start everything, simply run:

   docker compose up -d
   Copy

3. Server and Client Communication

   • The server will listen on the ports specified in CLIENT_SERVER_PORT and INCOMING_SERVER_PORT.
   • The client will forward requests to your local application and make it publicly accessible via the PROXY_SERVER_MAIN_HOST and generated subdomain.

4. Accessing Your Public URL

   After starting the services, the client will log the public URL for accessing your local application. This will be in the format:

   http://[generated-subdomain].yourcustomdomain.com:[INCOMING_SERVER_PORT]
   Copy

5. Explore the Docker Images

   You can find the Docker images for TunnelForge on Docker Hub:

   • TunnelForge Server
   • TunnelForge Client

Contributing

We welcome contributions! See our Contributing Guidelines for details.

License

TunnelForge is licensed under the MIT License.

Official Website

Visit the official website of TunnelForge for more details: tunnelforge.org.

Documentation

The full API and usage documentation is hosted on GitHub Pages.

If you'd like to view it locally or use it in a different hosting platform, the documentation is generated using TypeDoc and is located in the /docs folder.

Happy tunneling with TunnelForge!