Skip to main content

Installation Guide

Get gTunnel up and running on your system with multiple installation options. Choose the method that works best for your environment.

🚀 Client Installation​

The gTunnel client (gtc) connects your local services to a gTunnel server for public access.

📥 Option 1: Download Binary (Recommended)​

The fastest way to get started - download pre-built binaries for your platform.

# Download and install
curl -L https://github.com/B-AJ-Amar/gTunnel/releases/latest/download/gtunnel-client_linux_amd64.tar.gz | tar -xz
sudo mv gtc /usr/local/bin/

# Verify installation
gtc version

📦 Option 2: Package Managers​

Install using your system's package manager for automatic updates and easy removal.

# Download and install DEB package
wget https://github.com/B-AJ-Amar/gTunnel/releases/latest/download/gtunnel_linux_amd64.deb
sudo dpkg -i gtunnel_linux_amd64.deb

🛠️ Option 3: Installation Script (Flexible)​

Our smart installation script automatically detects your system and installs the right version.

Basic Installation
# Install client only (default)
curl -sSL https://raw.githubusercontent.com/B-AJ-Amar/gTunnel/main/scripts/install.sh | bash
Advanced Installation Options
# Install server only
curl -sSL https://raw.githubusercontent.com/B-AJ-Amar/gTunnel/main/scripts/install.sh | bash -s server

# Install both client and server
curl -sSL https://raw.githubusercontent.com/B-AJ-Amar/gTunnel/main/scripts/install.sh | bash -s both

# Install specific version
curl -sSL https://raw.githubusercontent.com/B-AJ-Amar/gTunnel/main/scripts/install.sh | bash -s -- --version v1.0.0 client

# Custom installation directory
INSTALL_DIR=~/.local/bin bash <(curl -sSL https://raw.githubusercontent.com/B-AJ-Amar/gTunnel/main/scripts/install.sh) both

# Get help and see all options
curl -sSL https://raw.githubusercontent.com/B-AJ-Amar/gTunnel/main/scripts/install.sh | bash -s -- --help

Script Features:

  • ✅ Cross-platform - Works on Linux, macOS, and Windows
  • ✅ Architecture detection - Automatically detects amd64, arm64, 386
  • ✅ Version selection - Install latest or specific version
  • ✅ Component selection - Choose client, server, or both
  • ✅ Custom install directory - Install to any directory
  • ✅ Verification - Automatically verifies installation

🔨 Option 4: Build from Source​

For developers who want the latest features or need to modify the code.

Build from Source
# Prerequisites: Go 1.19+
git clone https://github.com/B-AJ-Amar/gTunnel.git
cd gTunnel

# Build both client and server
make build

# Install to system
sudo make install
Prerequisites

Make sure you have Go 1.19 or later installed on your system. You can download it from golang.org.

🐳 Option 5: Docker​

Perfect for containerized environments and microservices architectures.

Run Client Container
docker run -d --name gtunnel-client \
  -e GTUNNEL_SERVER_URL="https://your-server.com" \
  -e GTUNNEL_ACCESS_TOKEN="your-token" \
  -e GTUNNEL_TARGET_HOST="app" \
  -e GTUNNEL_TARGET_PORT="3000" \
  --network your-network \
  ghcr.io/b-aj-amar/gtunnel-client:latest

Docker Environment Variables:

VariableDescriptionDefaultRequired
GTUNNEL_SERVER_URLgTunnel server URL""✅
GTUNNEL_ACCESS_TOKENAuthentication token""❌
GTUNNEL_TARGET_HOSTTarget host to tunnellocalhost❌
GTUNNEL_TARGET_PORTTarget port to tunnel3000❌
GTUNNEL_BASE_ENDPOINTBase endpoint path""❌
GTUNNEL_DEBUGEnable debug loggingfalse❌

🖥️ Server Installation​

The gTunnel server (gts) receives connections from clients and exposes them to the public internet.

The easiest way to install the server component.

Install Server
# Install server only
curl -sSL https://raw.githubusercontent.com/B-AJ-Amar/gTunnel/main/scripts/install.sh | bash -s server

# Install both client and server
curl -sSL https://raw.githubusercontent.com/B-AJ-Amar/gTunnel/main/scripts/install.sh | bash -s both

# Install specific version
curl -sSL https://raw.githubusercontent.com/B-AJ-Amar/gTunnel/main/scripts/install.sh | bash -s -- --version v1.0.0 server

🐳 Option 2: Docker Deployment​

Ideal for cloud platforms and containerized infrastructure.

Run Server Container
docker run -d --name gtunnel-server \
  -p 7205:7205 \
  -e GTUNNEL_ACCESS_TOKEN="your-secret-token" \
  ghcr.io/b-aj-amar/gtunnel-server:latest
Cloud Deployment

For quick cloud deployment, check out our Deployment Guide which includes one-click deployment options.

✅ Verify Installation​

After installation, verify that gTunnel is working correctly:

# Check client version
gtc version

# Check server version (if installed)
gts version

# Test client configuration
gtc config show

🆘 Troubleshooting​

Common Issues​

Command not found after installation

Solution: Add the installation directory to your PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH=$PATH:/usr/local/bin

# Or for custom installation directory
export PATH=$PATH:~/.local/bin
Permission denied errors

Solution: Ensure you have proper permissions:

# Make binary executable
chmod +x /path/to/gtc

# Or install with proper permissions
sudo mv gtc /usr/local/bin/
sudo chmod +x /usr/local/bin/gtc
Docker container won't start

Solution: Check the logs and environment variables:

# Check container logs
docker logs gtunnel-client

# Verify environment variables
docker inspect gtunnel-client

📚 Next Steps​

Now that you have gTunnel installed:

  1. Quick Start - Get your first tunnel running
  2. Configuration - Set up authentication and preferences
  3. CLI Reference - Learn all available commands
  4. Deployment - Deploy your own server

Need help? Check our FAQ or visit our GitHub Issues for support.