# 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
```bash
# 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:
```toml
[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
```bash
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:

```toml
[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
```bash
# 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+