Tunnel Server Development Setup

The tunnel server is built using Go and handles SSH remote port forwarding to tunnel HTTP/TCP connections.

Requirements

• Go (1.25+)
• PostgreSQL (16+) or SQLite (3.0+)

Setup Process

Configure environment variables

Create a new .env file using the .env.template file as a reference.

Start the server

go run ./cmd/portrd start tunnel

You should see output similar to:

time=2024-03-29T19:16:35.023+05:30 level=INFO msg="starting SSH server" port=:2222
time=2024-03-29T19:16:35.023+05:30 level=INFO msg="starting proxy server" port=:8001
time=2024-03-29T19:16:35.023+05:30 level=INFO msg="Starting 1 cron jobs"

This starts:

• SSH server on port :2222 for tunnel connections
• Proxy server on port :8001 for routing traffic

Server Architecture

The tunnel server consists of several components:

SSH Server

• Handles incoming tunnel connections from clients
• Manages SSH remote port forwarding
• Authenticates clients using tokens

Proxy Server

• Routes incoming HTTP requests to the appropriate tunnels
• Handles subdomain routing
• Manages SSL termination in production

Cron Jobs

• Cleans up expired tunnel connections
• Performs maintenance tasks

Development Workflow

Available Commands

# Start the server
go run ./cmd/portrd start tunnel

# Build the server
go build ./...

# Run tests
go test ./...

# Format code
go fmt ./...

# Run linting
go vet ./...

Configuration

For all configuration variables, check out the tunnel server config file.

Key configuration options include:

• Database connection: PostgreSQL connection string
• SSH server settings: Port, host keys, and authentication
• Proxy settings: HTTP server configuration
• Security settings: Token validation and access control

Testing Tunnel Connections

Local Testing

1. Start the admin server
2. Start the tunnel server
3. Build and run the client to create a test tunnel

Connection Flow

1. Client connects to SSH server on port 2222
2. SSH server validates the client token with the admin server
3. Remote port forwarding is established
4. Proxy server routes incoming requests to the client

Troubleshooting

Common Issues

Port conflicts: Ensure ports 2222 and 8001 are available.

Database connection errors: Verify your PostgreSQL instance is running and accessible.

SSH connection failures: Check that the SSH server is properly configured and the client has valid credentials.

Debugging

Enable tunnel debug logging with:

PORTR_TUNNEL_DEBUG=true

View detailed logs to troubleshoot connection issues:

# Follow server logs
go run ./cmd/portrd start tunnel