UUXO/hmac-file-server
1
1
Fork 0
Code Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: recreate README.md in conservative style without emoticons

Browse Source 
- 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:
Alexander Renz
2025-11-26 18:15:58 +01:00
parent 6f81f83327
commit 30dfa6fec7
1 changed files with 249 additions and 250 deletions
Download Patch File Download Diff File Expand all files Collapse all files

367
README.md
View File

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