ReachableCEO
d74cdc091b
- Update CloudronManifest.json to use modern format with proper ID, health check, and metadata
- Fix Dockerfile to follow Cloudron conventions (/app/code, /app/data structure)
- Correct Rathole configuration format (default_token instead of token, add services section)
- Fix start.sh to use proper --server flag syntax
- Add health check endpoint on port 8080
- Create comprehensive build notes documentation
- Successfully build and test package - both ports 2333 (Rathole) and 8080 (health) working
🤖 Generated with assistance from OpenCode for code optimization and testing
157 lines
4.0 KiB
Markdown
157 lines
4.0 KiB
Markdown
# 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+ |