Local Development

Tunnel Server Development Setup

Learn how to setup portr tunnel server for local development

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

Requirements

  • Go (1.23+)
  • PostgreSQL (16+)

Setup Process

cd tunnel

Configure environment variables

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

Start the server

make runserver

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
make runserver

# Build the server
make build

# Run tests
make test

# Format code
make fmt

# Run linting
make lint

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

Make sure the admin server is running before testing tunnel connections, as it handles client authentication.

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 debug logging by setting the appropriate log level in your configuration:

// In your .env or config
LOG_LEVEL=debug

View detailed logs to troubleshoot connection issues:

# Follow server logs
make runserver | grep -E "(ERROR|WARN|DEBUG)"