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
Navigate to the tunnel directory
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
- Start the admin server
- Start the tunnel server
- Build and run the client to create a test tunnel
Connection Flow
- Client connects to SSH server on port 2222
- SSH server validates the client token with the admin server
- Remote port forwarding is established
- 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)"