KNELProductionContainers/CloudronPackages/Rathole/Rathole-BuildNotes.md

Rathole Cloudron Package - Build Notes

Overview

Rathole is a secure, stable, and high-performance reverse proxy for NAT traversal, written in Rust. This package provides a Cloudron-ready deployment of the Rathole server component.

Package Details

• Version: 0.5.0
• Architecture: x86_64-unknown-linux-gnu
• Base Image: cloudron/base:4.2.0
• Ports: TCP 2333 (Rathole server), HTTP 8080 (health check)

Build Process

Prerequisites

• Docker
• Cloudron CLI (npm install -g cloudron)
• Access to upstream Rathole releases

Build Steps

# Navigate to package directory
cd CloudronPackages/Rathole

# Build the Docker image
docker build -t rathole:latest .

# Test locally (optional)
docker run -d --name rathole-test \
  -p 2333:2333 \
  -p 8080:8080 \
  -e RATHOLE_SERVER_TOKEN=test-token \
  rathole:latest

# Check logs
docker logs rathole-test

# Clean up test container
docker stop rathole-test && docker rm rathole-test

Configuration

Environment Variables

• RATHOLE_SERVER_TOKEN: Mandatory service token for authentication (default: "changeme")
• RATHOLE_SERVER_PORT: Server listening port (default: "2333")

Generated Configuration

The package automatically generates /app/data/rathole.toml with the following structure:

[server]
bind_addr = "0.0.0.0:2333"
token = "your-token-here"

Cloudron Integration

Addons

• localstorage: For persistent configuration storage

Health Checks

• HTTP health check endpoint at http://localhost:8080/health
• Returns "OK" when the service is running

Networking

• TCP port 2333: Rathole server port (exposed to external clients)
• HTTP port 8080: Internal health check port

Deployment

Install Command

cloudron install --image rathole:latest

Post-Installation

1. Configure the server token in the Cloudron environment variables
2. Update the port if needed (default: 2333)
3. Configure client connections to point to the Cloudron instance

Client Configuration Example

For Rathole clients to connect to this server:

[client]
remote_addr = "your-cloudron-domain.com:2333"
token = "your-server-token"

[client.services.your-service]
local_addr = "127.0.0.1:8080"
remote_addr = "0.0.0.0:8080"

Troubleshooting

Common Issues

1. Connection Refused on Port 2333

   • Check if the container is running: docker ps
   • Verify the server token matches between client and server
   • Check Cloudron firewall settings

2. Health Check Failing

   • Verify the health check server is running on port 8080
   • Check container logs: docker logs <container-id>

3. Configuration Not Persisting

   • Ensure /app/data is properly mounted
   • Check file permissions (should be owned by cloudron user)

Debug Commands

# Check container status
docker ps | grep rathole

# View logs
docker logs <container-id>

# Enter container for debugging
docker exec -it <container-id> /bin/bash

# Test connectivity
telnet your-cloudron-domain.com 2333

Security Considerations

1. Token Security: Use a strong, unique token for production
2. Network Access: Only expose port 2333 to trusted clients
3. Firewall Rules: Configure Cloudron firewall to restrict access to authorized IPs

Performance Tuning

• Default configuration should work for most use cases
• For high-throughput scenarios, consider adjusting system limits
• Monitor resource usage through Cloudron dashboard

Version Updates

To update to a newer version of Rathole:

1. Update the RATHOLE_VERSION ARG in the Dockerfile
2. Rebuild the Docker image
3. Test thoroughly before deploying to production
4. Update this documentation with any new configuration options

Support

• Rathole Documentation: https://github.com/rathole-org/rathole
• Cloudron Documentation: https://docs.cloudron.io
• Package Issues: Report via KNEL's issue tracking system

---

Build Date: 2025-01-04 Builder: KNEL/TSYS Development Team Tested On: Cloudron 7.0.0+