docs: recreate README.md in conservative style without emoticons
- Remove all emoticons and casual language - Focus on information and technical content - Maintain comprehensive documentation - Preserve all installation and configuration details
This commit is contained in:
367
README.md
367
README.md
@@ -11,34 +11,34 @@ A high-performance, secure file server implementing XEP-0363 (HTTP File Upload)
|
||||
|
||||
## What's New in 3.3.0 "Nexus Infinitum"
|
||||
|
||||
### 🔧 XMPP Client Compatibility
|
||||
- **✅ Gajim "Bad Gateway" Fix**: Full CORS support resolves intermittent upload errors
|
||||
- **✅ Universal XMPP Support**: Tested with Dino, Gajim, Conversations, Monal
|
||||
- **✅ Web Client Ready**: CORS headers for Converse.js and browser-based clients
|
||||
- **✅ Standards Compliant**: W3C CORS + XEP-0363 HTTP File Upload
|
||||
### XMPP Client Compatibility
|
||||
- Full CORS support resolves intermittent upload errors
|
||||
- Tested with Dino, Gajim, Conversations, Monal
|
||||
- CORS headers for Converse.js and browser-based clients
|
||||
- W3C CORS + XEP-0363 HTTP File Upload standards compliant
|
||||
|
||||
### Configuration Revolution
|
||||
- **93% Config Reduction**: From 112-line complex configs to 8-line minimal configs
|
||||
- **Smart Defaults**: Production-ready settings built into the application
|
||||
- **Auto-Generation**: `--genconfig` creates minimal configs instantly
|
||||
- **Zero Breaking Changes**: Existing configs continue working
|
||||
- 93% reduction in required configuration (from 112-line to 8-line configs)
|
||||
- Production-ready settings built into the application
|
||||
- Automatic generation of minimal configs with `--genconfig`
|
||||
- Backward compatibility with existing configurations
|
||||
|
||||
### Enhanced Performance
|
||||
- **Fixed Deduplication**: Existing files return success instead of "file not found"
|
||||
- **Queue Optimization**: Doubled capacity (50 to 100), faster scaling (80% to 40% threshold)
|
||||
- **Extended Timeouts**: 4800s defaults for large file reliability
|
||||
- **Session Persistence**: 60-minute timeouts for enterprise transfers
|
||||
- Fixed deduplication returning success instead of "file not found" for existing files
|
||||
- Doubled queue capacity (50 to 100) with faster scaling (80% to 40% threshold)
|
||||
- Extended timeouts of 4800s for large file reliability
|
||||
- 60-minute session persistence for enterprise transfers
|
||||
|
||||
### Multi-Architecture Support
|
||||
- **Cross-Platform**: AMD64, ARM64, ARM32v7 with native performance
|
||||
- **Interactive Builder**: Easy architecture targeting with menu system
|
||||
- **Production Ready**: All platforms enterprise-grade
|
||||
- Native performance across AMD64, ARM64, ARM32v7 platforms
|
||||
- Interactive build script with architecture selection menu
|
||||
- Enterprise-grade support for all platforms
|
||||
|
||||
### Container Support
|
||||
- **Docker & Podman**: Full support for both container engines
|
||||
- **Enterprise Ready**: Podman deployment tested and verified ✅
|
||||
- **Security Hardened**: Rootless, daemonless operation with SELinux integration
|
||||
- **XMPP Optimized**: Pod networking for multi-service deployments
|
||||
- Full support for both Docker and Podman container engines
|
||||
- Podman deployment tested and verified
|
||||
- Security hardened with rootless operation and SELinux integration
|
||||
- Optimized pod networking for multi-service XMPP deployments
|
||||
|
||||
---
|
||||
|
||||
@@ -107,7 +107,7 @@ go build -o hmac-file-server ./cmd/server/
|
||||
|
||||
HMAC File Server 3.3.0 includes a comprehensive installation framework that supports all deployment methods:
|
||||
|
||||
### 🚀 **Automated Installation (All Methods)**
|
||||
### Automated Installation (All Methods)
|
||||
```bash
|
||||
# Interactive menu - choose your deployment method
|
||||
./install-manager.sh
|
||||
@@ -122,14 +122,14 @@ HMAC File Server 3.3.0 includes a comprehensive installation framework that supp
|
||||
./install-manager.sh --test
|
||||
```
|
||||
|
||||
### ✅ **Supported Deployment Methods**
|
||||
- **✅ SystemD**: Native installation with service integration
|
||||
- **✅ Docker**: Full containerized deployment with compose files
|
||||
- **✅ Podman**: Rootless container deployment (tested & verified)
|
||||
- **✅ Debian**: Package-based installation with dependency management
|
||||
- **✅ Multi-Architecture**: AMD64, ARM64, ARM32v7 support for all methods
|
||||
### Supported Deployment Methods
|
||||
- SystemD: Native installation with service integration
|
||||
- Docker: Full containerized deployment with compose files
|
||||
- Podman: Rootless container deployment (tested and verified)
|
||||
- Debian: Package-based installation with dependency management
|
||||
- Multi-Architecture: AMD64, ARM64, ARM32v7 support for all methods
|
||||
|
||||
### 🧪 **Comprehensive Testing Suite**
|
||||
### Comprehensive Testing Suite
|
||||
```bash
|
||||
# Run all functionality tests
|
||||
./test
|
||||
@@ -142,9 +142,9 @@ HMAC File Server 3.3.0 includes a comprehensive installation framework that supp
|
||||
./test clean # Clean up test files
|
||||
```
|
||||
|
||||
### 🐳 **Enhanced Container Build Script**
|
||||
### Enhanced Container Build Script
|
||||
```bash
|
||||
# Universal container builder - auto-detects Docker & Podman
|
||||
# Universal container builder - auto-detects Docker and Podman
|
||||
./builddocker.sh
|
||||
|
||||
# Use specific container engine
|
||||
@@ -159,19 +159,19 @@ HMAC File Server 3.3.0 includes a comprehensive installation framework that supp
|
||||
./builddocker.sh --help
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- ✅ **Auto-Detection**: Automatically finds available container engines (Docker/Podman)
|
||||
- ✅ **Engine Selection**: Interactive menu for multiple engines or force specific engine
|
||||
- ✅ **Compose Support**: Uses appropriate compose files (docker-compose.yml / podman-compose.yml)
|
||||
- ✅ **Podman Optimized**: SELinux labels, rootless support, security optimizations
|
||||
- ✅ **Build & Deploy**: Combined build and optional service startup in one command
|
||||
Features:
|
||||
- Auto-Detection: Automatically finds available container engines (Docker/Podman)
|
||||
- Engine Selection: Interactive menu for multiple engines or force specific engine
|
||||
- Compose Support: Uses appropriate compose files (docker-compose.yml / podman-compose.yml)
|
||||
- Podman Optimized: SELinux labels, rootless support, security optimizations
|
||||
- Build and Deploy: Combined build and optional service startup in one command
|
||||
|
||||
**Test Coverage:**
|
||||
- ✅ HMAC Authentication & File Upload Validation
|
||||
- ✅ XMPP Integration (MP4 uploads for Conversations/Gajim)
|
||||
- ✅ Network Resilience & Mobile Switching Features
|
||||
- ✅ Large File Support & Extension Validation
|
||||
- ✅ Security Testing (Invalid HMAC rejection)
|
||||
Test Coverage:
|
||||
- HMAC Authentication and File Upload Validation
|
||||
- XMPP Integration (MP4 uploads for Conversations/Gajim)
|
||||
- Network Resilience and Mobile Switching Features
|
||||
- Large File Support and Extension Validation
|
||||
- Security Testing (Invalid HMAC rejection)
|
||||
|
||||
---
|
||||
|
||||
@@ -182,7 +182,7 @@ HMAC File Server 3.3.0 includes a comprehensive installation framework that supp
|
||||
- [Configuration Documentation](#configuration-documentation)
|
||||
- [Build Options](#build-options)
|
||||
- [Docker Compose Examples](#docker-compose-examples)
|
||||
- [Podman Deployment](#podman-deployment) ⭐ **NEW: Tested & Verified**
|
||||
- [Podman Deployment](#podman-deployment)
|
||||
- [Nginx Reverse Proxy](#nginx-reverse-proxy)
|
||||
- [Apache2 Reverse Proxy](#apache2-reverse-proxy)
|
||||
- [Prosody XMPP Integration](#prosody-xmpp-integration)
|
||||
@@ -196,39 +196,39 @@ HMAC File Server 3.3.0 includes a comprehensive installation framework that supp
|
||||
|
||||
### HMAC File Server 3.3.0 - Nexus Infinitum
|
||||
|
||||
**Release Date**: August 26, 2025
|
||||
**Codename**: Nexus Infinitum (infinite connectivity and boundless network reach)
|
||||
Release Date: August 26, 2025
|
||||
Codename: Nexus Infinitum (infinite connectivity and boundless network reach)
|
||||
|
||||
#### Latest Updates (3.3.0)
|
||||
- **🚀 Enhanced MIME Types**: Added 80+ additional file format support
|
||||
- **🔧 XMPP Client Ecosystem**: Comprehensive compatibility analysis
|
||||
- **🌐 Network Resilience**: Advanced mobile switching optimizations
|
||||
- **📊 Documentation**: Complete client compatibility matrix
|
||||
- **🔒 Security**: HMAC core functions remain untouched and secure
|
||||
- Enhanced MIME Types: Added 80+ additional file format support
|
||||
- XMPP Client Ecosystem: Comprehensive compatibility analysis
|
||||
- Network Resilience: Advanced mobile switching optimizations
|
||||
- Documentation: Complete client compatibility matrix
|
||||
- Security: HMAC core functions remain untouched and secure
|
||||
|
||||
#### Key Improvements
|
||||
- **Configuration Simplification**: 93% reduction in required configuration
|
||||
- **Enhanced Deduplication**: Fixed "file not found" errors for existing files
|
||||
- **Performance Optimization**: Doubled queue capacity, optimized worker scaling
|
||||
- **Multi-Architecture Support**: Native builds for AMD64, ARM64, ARM32v7
|
||||
- **Developer Experience**: Minimal config-first approach with comprehensive defaults
|
||||
- Configuration Simplification: 93% reduction in required configuration
|
||||
- Enhanced Deduplication: Fixed "file not found" errors for existing files
|
||||
- Performance Optimization: Doubled queue capacity, optimized worker scaling
|
||||
- Multi-Architecture Support: Native builds for AMD64, ARM64, ARM32v7
|
||||
- Developer Experience: Minimal config-first approach with comprehensive defaults
|
||||
|
||||
#### Network Switching Enhancements (3.3.0)
|
||||
- **🔧 Session Persistence**: Advanced session-based authentication for 5G/WiFi switching
|
||||
- **🔧 XEP-0363 Enhancement**: Bearer token refresh mechanism with up to 10 refreshes
|
||||
- **🔧 Network Change Detection**: Real-time network transition logging and handling
|
||||
- **🔧 Upload Resumption**: Interrupted transfer recovery across network changes
|
||||
- Session Persistence: Advanced session-based authentication for 5G/WiFi switching
|
||||
- XEP-0363 Enhancement: Bearer token refresh mechanism with up to 10 refreshes
|
||||
- Network Change Detection: Real-time network transition logging and handling
|
||||
- Upload Resumption: Interrupted transfer recovery across network changes
|
||||
|
||||
#### Migration Notes
|
||||
- **Backward Compatible**: All existing 3.2.x configs work unchanged
|
||||
- **Performance Boost**: Automatic optimizations with existing configurations
|
||||
- **Optional Migration**: Users can optionally migrate to simplified 8-line configs
|
||||
- Backward Compatible: All existing 3.2.x configs work unchanged
|
||||
- Performance Boost: Automatic optimizations with existing configurations
|
||||
- Optional Migration: Users can optionally migrate to simplified 8-line configs
|
||||
|
||||
#### System Requirements
|
||||
- **Memory**: 512MB minimum, 2GB+ recommended for large files
|
||||
- **Storage**: 100MB application + user data storage
|
||||
- **Network**: Standard TCP/IP connectivity
|
||||
- **OS**: Linux (primary), Windows/macOS (experimental)
|
||||
- Memory: 512MB minimum, 2GB+ recommended for large files
|
||||
- Storage: 100MB application + user data storage
|
||||
- Network: Standard TCP/IP connectivity
|
||||
- OS: Linux (primary), Windows/macOS (experimental)
|
||||
|
||||
---
|
||||
|
||||
@@ -236,12 +236,11 @@ HMAC File Server 3.3.0 includes a comprehensive installation framework that supp
|
||||
|
||||
HMAC File Server 3.3.0 introduces enhanced network resilience specifically designed for mobile devices and network switching scenarios.
|
||||
|
||||
### 📱 **Mobile Network Switching Support**
|
||||
### Mobile Network Switching Support
|
||||
|
||||
#### **Scenario 1: WLAN ↔ IPv6 5G Switching**
|
||||
#### Scenario 1: WLAN to IPv6 5G Switching
|
||||
Perfect for mobile devices that switch between WiFi and cellular networks:
|
||||
|
||||
```toml
|
||||
```toml
|
||||
[uploads]
|
||||
networkevents = true # REQUIRED: Enable network monitoring
|
||||
@@ -267,7 +266,7 @@ writetimeout = "600s" # Handle cellular upload delays
|
||||
idletimeout = "1200s" # 20-minute tolerance
|
||||
```
|
||||
|
||||
#### **Scenario 2: Multi-Interface Devices (Ethernet + WiFi + LTE)**
|
||||
#### Scenario 2: Multi-Interface Devices (Ethernet + WiFi + LTE)
|
||||
For devices with multiple network interfaces:
|
||||
|
||||
```toml
|
||||
@@ -292,20 +291,20 @@ allow_ip_changes = true # Allow IP changes during uploads
|
||||
adapt_to_client_network = true # Optimize for client connection type
|
||||
```
|
||||
|
||||
### **Benefits for Mobile Scenarios**
|
||||
### Benefits for Mobile Scenarios
|
||||
|
||||
| Feature | Standard Detection | Enhanced Mobile Detection |
|
||||
|---------|-------------------|---------------------------|
|
||||
| **Detection Speed** | 5 seconds | **1 second** |
|
||||
| **Network Quality** | Interface status only | **RTT + packet loss monitoring** |
|
||||
| **Switching Logic** | Reactive (after failure) | **Proactive (before failure)** |
|
||||
| **Mobile Tolerance** | Fixed thresholds | **Cellular-optimized thresholds** |
|
||||
| **Session Recovery** | 2-minute window | **10-minute window** |
|
||||
| **Upload Resumption** | Basic retry | **Smart retry with backoff** |
|
||||
| Detection Speed | 5 seconds | 1 second |
|
||||
| Network Quality | Interface status only | RTT + packet loss monitoring |
|
||||
| Switching Logic | Reactive (after failure) | Proactive (before failure) |
|
||||
| Mobile Tolerance | Fixed thresholds | Cellular-optimized thresholds |
|
||||
| Session Recovery | 2-minute window | 10-minute window |
|
||||
| Upload Resumption | Basic retry | Smart retry with backoff |
|
||||
|
||||
### **Configuration Examples**
|
||||
### Configuration Examples
|
||||
|
||||
**Ultra-Fast Mobile Detection**:
|
||||
Ultra-Fast Mobile Detection:
|
||||
```toml
|
||||
[network_resilience]
|
||||
enabled = true
|
||||
@@ -315,7 +314,7 @@ mobile_optimizations = true # Lenient cellular thresholds
|
||||
upload_resilience = true # Resume uploads on network changes
|
||||
```
|
||||
|
||||
**Conservative Stable Network**:
|
||||
Conservative Stable Network:
|
||||
```toml
|
||||
[network_resilience]
|
||||
enabled = true
|
||||
@@ -325,7 +324,7 @@ predictive_switching = false # React only to hard failures
|
||||
mobile_optimizations = false # Use strict thresholds
|
||||
```
|
||||
|
||||
**Multi-Interface Optimized**:
|
||||
Multi-Interface Optimized:
|
||||
```toml
|
||||
[network_resilience]
|
||||
enabled = true
|
||||
@@ -346,7 +345,7 @@ switch_threshold_packet_loss = 3.0 # 3% packet loss trigger
|
||||
./hmac-file-server -genconfig > config.toml
|
||||
```
|
||||
|
||||
**Output Example:**
|
||||
Output Example:
|
||||
```toml
|
||||
# HMAC File Server - Minimal Configuration
|
||||
[server]
|
||||
@@ -394,34 +393,34 @@ file = "/var/log/hmac-file-server.log"
|
||||
./hmac-file-server -check-performance -config config.toml
|
||||
```
|
||||
|
||||
### ⚠️ Configuration Troubleshooting
|
||||
### Configuration Troubleshooting
|
||||
|
||||
**Common Issue**: Service fails with `storage path is required` or `permission denied`
|
||||
Common Issue: Service fails with `storage path is required` or `permission denied`
|
||||
|
||||
```bash
|
||||
# ❌ WRONG - Field names without underscores
|
||||
# WRONG - Field names without underscores
|
||||
[server]
|
||||
storagepath = "/opt/hmac-file-server/data/uploads"
|
||||
listenport = "8080"
|
||||
|
||||
# ✅ CORRECT - Use underscores in TOML field names
|
||||
# CORRECT - Use underscores in TOML field names
|
||||
[server]
|
||||
storage_path = "/opt/hmac-file-server/data/uploads"
|
||||
listen_address = "8080"
|
||||
```
|
||||
|
||||
### 🔧 XMPP Client Issues
|
||||
### XMPP Client Issues
|
||||
|
||||
**Gajim "Bad Gateway" Error**: Fixed in 3.3.0 with full CORS support
|
||||
Gajim "Bad Gateway" Error: Fixed in 3.3.0 with full CORS support
|
||||
```bash
|
||||
# Verify CORS functionality
|
||||
curl -X OPTIONS http://your-server:8080/ -v
|
||||
# Should return HTTP 200 with Access-Control headers
|
||||
```
|
||||
|
||||
📖 **See**: [GAJIM_BAD_GATEWAY_FIX.md](GAJIM_BAD_GATEWAY_FIX.md) for complete details
|
||||
See [GAJIM_BAD_GATEWAY_FIX.md](GAJIM_BAD_GATEWAY_FIX.md) for complete details
|
||||
|
||||
**Quick Fix Commands:**
|
||||
Quick Fix Commands:
|
||||
```bash
|
||||
# Test configuration
|
||||
./hmac-file-server --validate-config
|
||||
@@ -642,7 +641,7 @@ version = "3.3.0" # Application version
|
||||
./build-multi-arch.sh
|
||||
```
|
||||
|
||||
**Menu Options:**
|
||||
Menu Options:
|
||||
```
|
||||
HMAC File Server Multi-Architecture Builder
|
||||
==========================================
|
||||
@@ -1025,7 +1024,7 @@ writetimeout = "3600s"
|
||||
idletimeout = "3600s"
|
||||
EOF
|
||||
|
||||
echo "⚠️ IMPORTANT: Edit ${app_data}/config/config.toml and change the secrets!"
|
||||
echo "IMPORTANT: Edit ${app_data}/config/config.toml and change the secrets!"
|
||||
fi
|
||||
|
||||
# Build image if it doesn't exist
|
||||
@@ -1060,12 +1059,12 @@ podman run -d \
|
||||
--health-start-period=40s \
|
||||
"${ctr_image}" -config /app/config.toml
|
||||
|
||||
echo "✅ HMAC File Server deployed successfully!"
|
||||
echo "🌐 Server available at: http://localhost:${listen_port}"
|
||||
echo "📊 Metrics available at: http://localhost:${metrics_port}/metrics"
|
||||
echo "📋 Container status: podman ps"
|
||||
echo "📝 View logs: podman logs ${ctr_name}"
|
||||
echo "🔍 Health check: curl -f http://localhost:${listen_port}/health"
|
||||
echo "HMAC File Server deployed successfully!"
|
||||
echo "Server available at: http://localhost:${listen_port}"
|
||||
echo "Metrics available at: http://localhost:${metrics_port}/metrics"
|
||||
echo "Container status: podman ps"
|
||||
echo "View logs: podman logs ${ctr_name}"
|
||||
echo "Health check: curl -f http://localhost:${listen_port}/health"
|
||||
```
|
||||
|
||||
#### Podman Systemd Service (Rootless)
|
||||
@@ -1178,62 +1177,62 @@ podman ps --pod
|
||||
|
||||
| Feature | Docker | Podman |
|
||||
|---------|--------|--------|
|
||||
| **Daemon** | Requires Docker daemon | Daemonless architecture |
|
||||
| **Root Access** | Requires root for Docker daemon | Can run completely rootless |
|
||||
| **Security** | Good, but daemon runs as root | Enhanced security, no privileged daemon |
|
||||
| **Systemd Integration** | Via Docker service | Native systemd integration |
|
||||
| **Pod Support** | Requires docker-compose or swarm | Native Kubernetes-style pods |
|
||||
| **Image Compatibility** | Docker images | Compatible with Docker images |
|
||||
| **Enterprise Use** | Popular in startups/mid-size | Preferred in enterprise environments |
|
||||
| **SELinux** | Basic support | Excellent SELinux integration |
|
||||
| Daemon | Requires Docker daemon | Daemonless architecture |
|
||||
| Root Access | Requires root for Docker daemon | Can run completely rootless |
|
||||
| Security | Good, but daemon runs as root | Enhanced security, no privileged daemon |
|
||||
| Systemd Integration | Via Docker service | Native systemd integration |
|
||||
| Pod Support | Requires docker-compose or swarm | Native Kubernetes-style pods |
|
||||
| Image Compatibility | Docker images | Compatible with Docker images |
|
||||
| Enterprise Use | Popular in startups/mid-size | Preferred in enterprise environments |
|
||||
| SELinux | Basic support | Excellent SELinux integration |
|
||||
|
||||
### Podman Benefits for HMAC File Server
|
||||
|
||||
1. **Enhanced Security**: No privileged daemon, better isolation
|
||||
2. **Rootless Operation**: Can run without root privileges
|
||||
3. **SELinux Integration**: Better compliance in enterprise environments
|
||||
4. **Systemd Native**: Better integration with system services
|
||||
5. **Pod Support**: Natural clustering with XMPP servers
|
||||
6. **Resource Efficiency**: Lower overhead without daemon
|
||||
1. Enhanced Security: No privileged daemon, better isolation
|
||||
2. Rootless Operation: Can run without root privileges
|
||||
3. SELinux Integration: Better compliance in enterprise environments
|
||||
4. Systemd Native: Better integration with system services
|
||||
5. Pod Support: Natural clustering with XMPP servers
|
||||
6. Resource Efficiency: Lower overhead without daemon
|
||||
|
||||
### Testing Results & Verification
|
||||
### Testing Results and Verification
|
||||
|
||||
The Podman deployment has been fully tested and verified:
|
||||
|
||||
#### ✅ **Installation Success**
|
||||
- **Docker Removal**: Complete removal of Docker packages and dependencies
|
||||
- **Podman Installation**: Podman 4.3.1 installed with all dependencies (`fuse-overlayfs`, `slirp4netns`, `uidmap`)
|
||||
- **Image Build**: Successfully built `localhost/hmac-file-server:latest` with security optimizations
|
||||
#### Installation Success
|
||||
- Docker Removal: Complete removal of Docker packages and dependencies
|
||||
- Podman Installation: Podman 4.3.1 installed with all dependencies (fuse-overlayfs, slirp4netns, uidmap)
|
||||
- Image Build: Successfully built localhost/hmac-file-server:latest with security optimizations
|
||||
|
||||
#### ✅ **Container Deployment Success**
|
||||
- **Security Hardened**: Running as non-root user (UID 1011) with `--cap-drop=ALL`, `--read-only`, `--no-new-privileges`
|
||||
- **Health Checks**: Built-in health monitoring and status reporting
|
||||
- **Volume Mounting**: Proper SELinux labeling with `:Z` flags
|
||||
#### Container Deployment Success
|
||||
- Security Hardened: Running as non-root user (UID 1011) with --cap-drop=ALL, --read-only, --no-new-privileges
|
||||
- Health Checks: Built-in health monitoring and status reporting
|
||||
- Volume Mounting: Proper SELinux labeling with :Z flags
|
||||
|
||||
#### ✅ **Functional Verification**
|
||||
#### Functional Verification
|
||||
```bash
|
||||
# Health endpoint test
|
||||
curl -f http://localhost:8888/health
|
||||
# Response: OK ✅
|
||||
# Response: OK
|
||||
|
||||
# Metrics endpoint test
|
||||
curl -s http://localhost:9090/metrics | head -5
|
||||
# Response: Prometheus metrics ✅
|
||||
# Response: Prometheus metrics
|
||||
|
||||
# Container status
|
||||
podman ps
|
||||
# Status: Up and running ✅
|
||||
# Status: Up and running
|
||||
|
||||
# Configuration validation
|
||||
podman logs hmac-file-server
|
||||
# Result: All settings validated ✅
|
||||
# Result: All settings validated
|
||||
```
|
||||
|
||||
#### ✅ **Production Ready Features**
|
||||
- **XMPP Integration**: Pod networking for multi-service XMPP deployments
|
||||
- **Configuration Management**: Auto-generated secure configs with random secrets
|
||||
- **Service Management**: Native systemd integration for both rootless and system-wide deployment
|
||||
- **Enterprise Security**: Enhanced security features preferred in enterprise environments
|
||||
#### Production Ready Features
|
||||
- XMPP Integration: Pod networking for multi-service XMPP deployments
|
||||
- Configuration Management: Auto-generated secure configs with random secrets
|
||||
- Service Management: Native systemd integration for both rootless and system-wide deployment
|
||||
- Enterprise Security: Enhanced security features preferred in enterprise environments
|
||||
|
||||
### Quick Start Commands
|
||||
|
||||
@@ -1250,19 +1249,19 @@ podman run -d --name hmac-file-server \
|
||||
localhost/hmac-file-server:latest -config /app/config.toml
|
||||
|
||||
# Health verification
|
||||
curl -f http://localhost:8888/health && echo " - Server is healthy! ✅"
|
||||
curl -f http://localhost:8888/health && echo " - Server is healthy!"
|
||||
```
|
||||
|
||||
### Manual Setup: Paths, Ownership & Permissions
|
||||
### Manual Setup: Paths, Ownership and Permissions
|
||||
|
||||
When setting up Podman or Docker manually, proper path ownership is crucial:
|
||||
|
||||
#### **Container User Configuration**
|
||||
- **Container User**: `appuser` (UID: 1011, GID: 1011)
|
||||
- **Security**: Non-root user for enhanced security
|
||||
- **Compatibility**: Works with both rootless and rootful containers
|
||||
#### Container User Configuration
|
||||
- Container User: appuser (UID: 1011, GID: 1011)
|
||||
- Security: Non-root user for enhanced security
|
||||
- Compatibility: Works with both rootless and rootful containers
|
||||
|
||||
#### **Required Directory Structure**
|
||||
#### Required Directory Structure
|
||||
```bash
|
||||
# Create base directory structure
|
||||
mkdir -p /opt/podman/hmac-file-server/{config,data,deduplication,logs}
|
||||
@@ -1279,16 +1278,16 @@ chmod 755 /opt/podman/hmac-file-server/{config,data,deduplication,logs}
|
||||
chmod 644 /opt/podman/hmac-file-server/config/config.toml # Read-only config
|
||||
```
|
||||
|
||||
#### **Path Mapping Reference**
|
||||
#### Path Mapping Reference
|
||||
|
||||
| Host Path | Container Path | Purpose | Required Permissions |
|
||||
|-----------|----------------|---------|---------------------|
|
||||
| `/opt/podman/hmac-file-server/config/config.toml` | `/app/config.toml` | Configuration file | `644` (read-only) |
|
||||
| `/opt/podman/hmac-file-server/data/` | `/data/` | File uploads/storage | `755` (read-write) |
|
||||
| `/opt/podman/hmac-file-server/deduplication/` | `/deduplication/` | Deduplication cache | `755` (read-write) |
|
||||
| `/opt/podman/hmac-file-server/logs/` | `/logs/` | Application logs | `755` (read-write) |
|
||||
| /opt/podman/hmac-file-server/config/config.toml | /app/config.toml | Configuration file | 644 (read-only) |
|
||||
| /opt/podman/hmac-file-server/data/ | /data/ | File uploads/storage | 755 (read-write) |
|
||||
| /opt/podman/hmac-file-server/deduplication/ | /deduplication/ | Deduplication cache | 755 (read-write) |
|
||||
| /opt/podman/hmac-file-server/logs/ | /logs/ | Application logs | 755 (read-write) |
|
||||
|
||||
#### **SELinux Labels (Important for RHEL/CentOS/Fedora)**
|
||||
#### SELinux Labels (Important for RHEL/CentOS/Fedora)
|
||||
```bash
|
||||
# Add SELinux labels for Podman volume mounts
|
||||
podman run -d --name hmac-file-server \
|
||||
@@ -1298,18 +1297,18 @@ podman run -d --name hmac-file-server \
|
||||
-v /opt/podman/hmac-file-server/logs:/logs:rw,Z \
|
||||
localhost/hmac-file-server:latest
|
||||
|
||||
# Note: The `:Z` flag relabels content and should be used for private volumes
|
||||
# Use `:z` for shared volumes between multiple containers
|
||||
# Note: The :Z flag relabels content and should be used for private volumes
|
||||
# Use :z for shared volumes between multiple containers
|
||||
```
|
||||
|
||||
#### **Common Ownership Issues & Solutions**
|
||||
#### Common Ownership Issues and Solutions
|
||||
|
||||
**❌ Problem**: Container fails with permission errors
|
||||
Problem: Container fails with permission errors
|
||||
```bash
|
||||
# Logs show: "permission denied: open /data/.write_test"
|
||||
```
|
||||
|
||||
**✅ Solution**: Fix ownership and verify
|
||||
Solution: Fix ownership and verify
|
||||
```bash
|
||||
# Fix ownership
|
||||
chown -R 1011:1011 /opt/podman/hmac-file-server
|
||||
@@ -1323,12 +1322,12 @@ sudo -u "#1011" touch /opt/podman/hmac-file-server/data/test.txt
|
||||
# Should succeed without errors
|
||||
```
|
||||
|
||||
**❌ Problem**: SELinux blocking container access
|
||||
Problem: SELinux blocking container access
|
||||
```bash
|
||||
# Logs show: "SELinux is preventing access"
|
||||
```
|
||||
|
||||
**✅ Solution**: Correct SELinux labeling
|
||||
Solution: Correct SELinux labeling
|
||||
```bash
|
||||
# Option 1: Use :Z labels in volume mounts (recommended)
|
||||
-v /path/to/data:/data:rw,Z
|
||||
@@ -1338,16 +1337,16 @@ sudo setsebool -P container_manage_cgroup on
|
||||
sudo restorecon -R /opt/podman/hmac-file-server
|
||||
```
|
||||
|
||||
#### **Docker vs Podman Ownership Differences**
|
||||
#### Docker vs Podman Ownership Differences
|
||||
|
||||
| Scenario | Docker | Podman Rootless | Podman Rootful |
|
||||
|----------|--------|-----------------|----------------|
|
||||
| **Host UID** | 1011:1011 | 1011:1011 | 1011:1011 |
|
||||
| **Container UID** | 1011:1011 | 1011:1011 | 1011:1011 |
|
||||
| **Volume Ownership** | `chown 1011:1011` | `podman unshare chown 1011:1011` | `chown 1011:1011` |
|
||||
| **SELinux Labels** | `:Z` or `:z` | `:Z` or `:z` | `:Z` or `:z` |
|
||||
| Host UID | 1011:1011 | 1011:1011 | 1011:1011 |
|
||||
| Container UID | 1011:1011 | 1011:1011 | 1011:1011 |
|
||||
| Volume Ownership | chown 1011:1011 | podman unshare chown 1011:1011 | chown 1011:1011 |
|
||||
| SELinux Labels | :Z or :z | :Z or :z | :Z or :z |
|
||||
|
||||
#### **Verification Commands**
|
||||
#### Verification Commands
|
||||
```bash
|
||||
# Check container user
|
||||
podman exec hmac-file-server id
|
||||
@@ -1938,11 +1937,11 @@ HMAC File Server implements [XEP-0363: HTTP File Upload](https://xmpp.org/extens
|
||||
|
||||
#### Protocol Flow
|
||||
|
||||
1. **Discovery**: Client discovers upload service
|
||||
2. **Request Slot**: Client requests upload/download URLs
|
||||
3. **Upload**: Client uploads file to provided PUT URL
|
||||
4. **Share**: Client shares GET URL with contacts
|
||||
5. **Download**: Recipients download using GET URL
|
||||
1. Discovery: Client discovers upload service
|
||||
2. Request Slot: Client requests upload/download URLs
|
||||
3. Upload: Client uploads file to provided PUT URL
|
||||
4. Share: Client shares GET URL with contacts
|
||||
5. Download: Recipients download using GET URL
|
||||
|
||||
#### Implementation Details
|
||||
|
||||
@@ -2035,9 +2034,9 @@ HMAC File Server supports multiple API versions to ensure compatibility with dif
|
||||
|
||||
### V1 API (Legacy Support)
|
||||
|
||||
**Endpoint**: `/api/v1/upload`
|
||||
**Authentication**: Basic HMAC
|
||||
**Usage**: Legacy XMPP clients, basic integrations
|
||||
Endpoint: `/api/v1/upload`
|
||||
Authentication: Basic HMAC
|
||||
Usage: Legacy XMPP clients, basic integrations
|
||||
|
||||
```bash
|
||||
# V1 Upload
|
||||
@@ -2057,9 +2056,9 @@ curl -X POST "https://files.example.com/api/v1/upload" \
|
||||
|
||||
### V2 API (Enhanced)
|
||||
|
||||
**Endpoint**: `/api/v2/upload`
|
||||
**Authentication**: Enhanced HMAC with timestamps
|
||||
**Usage**: Modern XMPP clients, advanced features
|
||||
Endpoint: `/api/v2/upload`
|
||||
Authentication: Enhanced HMAC with timestamps
|
||||
Usage: Modern XMPP clients, advanced features
|
||||
|
||||
```bash
|
||||
# V2 Upload with metadata
|
||||
@@ -2092,10 +2091,10 @@ curl -X POST "https://files.example.com/api/v2/upload" \
|
||||
|
||||
### V3 API (Custom/Experimental)
|
||||
|
||||
**Endpoint**: `/api/v3/upload`
|
||||
**Authentication**: JWT or Enhanced HMAC
|
||||
**Usage**: Custom clients, experimental features
|
||||
**Note**: V3 is not a defined standard - custom implementation
|
||||
Endpoint: `/api/v3/upload`
|
||||
Authentication: JWT or Enhanced HMAC
|
||||
Usage: Custom clients, experimental features
|
||||
Note: V3 is not a defined standard - custom implementation
|
||||
|
||||
```bash
|
||||
# V3 Upload with JWT
|
||||
@@ -2301,7 +2300,7 @@ class HMACFileClientV3:
|
||||
# Build for multiple architectures
|
||||
./build-multi-arch.sh
|
||||
|
||||
# Podman deployment (tested and verified ✅)
|
||||
# Podman deployment (tested and verified)
|
||||
cd dockerenv/podman && ./deploy-podman.sh
|
||||
```
|
||||
|
||||
@@ -2349,8 +2348,8 @@ This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENS
|
||||
|
||||
## Repository
|
||||
|
||||
**Primary Repository (Gitea):** [git.uuxo.net/UUXO/hmac-file-server](https://git.uuxo.net/UUXO/hmac-file-server)
|
||||
**GitHub Mirror:** [github.com/PlusOne/hmac-file-server](https://github.com/PlusOne/hmac-file-server)
|
||||
Primary Repository (Gitea): [git.uuxo.net/UUXO/hmac-file-server](https://git.uuxo.net/UUXO/hmac-file-server)
|
||||
GitHub Mirror: [github.com/PlusOne/hmac-file-server](https://github.com/PlusOne/hmac-file-server)
|
||||
|
||||
Issues and contributions welcome on both platforms.
|
||||
|
||||
@@ -2358,15 +2357,15 @@ Issues and contributions welcome on both platforms.
|
||||
|
||||
## Links
|
||||
|
||||
- **Primary Repository (Gitea):** https://git.uuxo.net/UUXO/hmac-file-server
|
||||
- **GitHub Mirror:** https://github.com/PlusOne/hmac-file-server
|
||||
- **Documentation:** https://git.uuxo.net/UUXO/hmac-file-server/wiki
|
||||
- **Issues (Gitea):** https://git.uuxo.net/UUXO/hmac-file-server/issues
|
||||
- **Issues (GitHub):** https://github.com/PlusOne/hmac-file-server/issues
|
||||
- **Releases (Gitea):** https://git.uuxo.net/UUXO/hmac-file-server/releases
|
||||
- **Releases (GitHub):** https://github.com/PlusOne/hmac-file-server/releases
|
||||
- **Website:** https://uuxo.net
|
||||
- Primary Repository (Gitea): https://git.uuxo.net/UUXO/hmac-file-server
|
||||
- GitHub Mirror: https://github.com/PlusOne/hmac-file-server
|
||||
- Documentation: https://git.uuxo.net/UUXO/hmac-file-server/wiki
|
||||
- Issues (Gitea): https://git.uuxo.net/UUXO/hmac-file-server/issues
|
||||
- Issues (GitHub): https://github.com/PlusOne/hmac-file-server/issues
|
||||
- Releases (Gitea): https://git.uuxo.net/UUXO/hmac-file-server/releases
|
||||
- Releases (GitHub): https://github.com/PlusOne/hmac-file-server/releases
|
||||
- Website: https://uuxo.net
|
||||
|
||||
*HMAC File Server 3.3 "Nexus Infinitum" - Where enterprise power meets user simplicity*
|
||||
HMAC File Server 3.3 "Nexus Infinitum" - Where enterprise power meets user simplicity
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user