hmac-file-server/dockerenv/podman

HMAC File Server - Podman Configuration Examples

This directory contains Podman-specific deployment files for HMAC File Server 3.2 "Tremora del Terra".

🚀 Quick Start

# Clone repository
git clone https://github.com/PlusOne/hmac-file-server.git
cd hmac-file-server/dockerenv/podman

# Deploy with single command
./deploy-podman.sh

# Check status
./deploy-podman.sh status

# View logs
./deploy-podman.sh logs

📁 Files Overview

Dockerfile.podman

• Purpose: Optimized Dockerfile for Podman deployment
• Features:
  • Security-hardened Alpine-based image
  • Non-root user (UID 1011)
  • Health checks included
  • Static binary compilation
  • Minimal attack surface

deploy-podman.sh

• Purpose: Complete deployment automation script
• Features:
  • Interactive deployment with colored output
  • Automatic configuration generation with random secrets
  • Security-hardened container settings
  • Pod management for XMPP integration
  • Health monitoring and status reporting

hmac-file-server.service

• Purpose: Systemd service unit for service management
• Usage: Place in ~/.config/systemd/user/ (rootless) or /etc/systemd/system/ (system-wide)

🛠️ Deployment Commands

Basic Deployment

# Full deployment (directories, config, build, start)
./deploy-podman.sh deploy

# Start services only
./deploy-podman.sh start

# Stop all services
./deploy-podman.sh stop

# Restart services
./deploy-podman.sh restart

Management Commands

# Check status and health
./deploy-podman.sh status

# View real-time logs
./deploy-podman.sh logs

# Show current configuration
./deploy-podman.sh config

# Build image only
./deploy-podman.sh build

# Create networking pod only
./deploy-podman.sh pod

# Complete cleanup (keeps data)
./deploy-podman.sh clean

🔧 Configuration

Environment Variables

# Custom data directory
export APP_DATA="/custom/path/hmac-file-server"

# Custom ports
export LISTEN_PORT="9999"
export METRICS_PORT="9998"

# Deploy with custom settings
./deploy-podman.sh

Generated Configuration

The deployment script generates a production-ready configuration with:

• ✅ XMPP-compatible file extensions
• ✅ Random HMAC and JWT secrets
• ✅ Optimized performance settings
• ✅ Security hardening enabled
• ✅ Comprehensive logging

🔒 Security Features

Container Security

• Rootless operation: Runs as non-root user (UID 1011)
• Capability dropping: --cap-drop=ALL
• No new privileges: --security-opt no-new-privileges
• Read-only filesystem: --read-only with tmpfs for /tmp
• SELinux labels: Volume mounts with :Z labels

Network Security

• Pod isolation: Containers run in isolated pods
• Port binding: Only necessary ports exposed
• Health monitoring: Built-in health checks

🔄 Systemd Integration

User Service (Rootless - Recommended)

# Copy service file
cp hmac-file-server.service ~/.config/systemd/user/

# Enable and start
systemctl --user daemon-reload
systemctl --user enable hmac-file-server.service
systemctl --user start hmac-file-server.service

# Check status
systemctl --user status hmac-file-server.service

System Service (Root)

# Copy service file
sudo cp hmac-file-server.service /etc/systemd/system/

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable hmac-file-server.service
sudo systemctl start hmac-file-server.service

# Check status
sudo systemctl status hmac-file-server.service

🎯 XMPP Integration

Pod-based XMPP Deployment

# Create XMPP services pod
podman pod create --name xmpp-services \
  --publish 5222:5222 \
  --publish 5269:5269 \
  --publish 5443:5443 \
  --publish 8888:8888

# Add Prosody XMPP server
podman run -d --pod xmpp-services --name prosody \
  -v ./prosody-config:/etc/prosody:ro \
  -v ./prosody-data:/var/lib/prosody:rw \
  docker.io/prosody/prosody:latest

# Add HMAC File Server
podman run -d --pod xmpp-services --name hmac-file-server \
  -v ./config.toml:/app/config.toml:ro \
  -v ./data:/data:rw \
  localhost/hmac-file-server:latest -config /app/config.toml

📊 Monitoring and Health

Health Checks

# Manual health check
curl -f http://localhost:8888/health

# Container health status
podman healthcheck run hmac-file-server

# Continuous monitoring
watch -n 5 'curl -s http://localhost:8888/health && echo " - $(date)"'

Metrics

# Prometheus metrics
curl http://localhost:9090/metrics

# Pod statistics
podman pod stats xmpp-pod

# Container logs
podman logs -f hmac-file-server

🚨 Troubleshooting

Common Issues

Permission Errors

# Fix SELinux contexts
restorecon -R /opt/podman/hmac-file-server

# Check volume permissions
podman unshare ls -la /opt/podman/hmac-file-server

Container Won't Start

# Check image exists
podman images | grep hmac-file-server

# Validate configuration
./deploy-podman.sh config

# Debug with interactive container
podman run -it --rm localhost/hmac-file-server:latest /bin/sh

Network Issues

# Check pod networking
podman pod ps
podman port hmac-file-server

# Test connectivity
nc -zv localhost 8888

Log Analysis

# Container logs
podman logs hmac-file-server

# Application logs
tail -f /opt/podman/hmac-file-server/logs/hmac-file-server.log

# System journal
journalctl --user -u hmac-file-server.service -f

🎉 Success Verification

After deployment, verify everything works:

1. Health Check: curl -f http://localhost:8888/health
2. Metrics: curl http://localhost:9090/metrics
3. Container Status: podman ps
4. Pod Status: podman pod ps
5. Logs: ./deploy-podman.sh logs

📚 Additional Resources

• Podman Official Documentation
• HMAC File Server GitHub
• XEP-0363 Specification
• Container Security Best Practices