Add Podman deployment support for HMAC File Server 3.2
- Introduced Dockerfile.podman for building a Podman-compatible image. - Created deploy-podman.sh script for automated deployment and management. - Added Podman-specific README.md with quick start and configuration details. - Included example configuration file (config.toml.example) for production settings. - Implemented systemd service file for managing the HMAC File Server as a service. - Established health checks and security features in the container setup. - Documented deployment commands and troubleshooting steps in README.md.
This commit is contained in:
263
dockerenv/podman/README.md
Normal file
263
dockerenv/podman/README.md
Normal file
@ -0,0 +1,263 @@
|
||||
# HMAC File Server - Podman Configuration Examples
|
||||
|
||||
This directory contains Podman-specific deployment files for HMAC File Server 3.2 "Tremora del Terra".
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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)
|
||||
```bash
|
||||
# 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)
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Check pod networking
|
||||
podman pod ps
|
||||
podman port hmac-file-server
|
||||
|
||||
# Test connectivity
|
||||
nc -zv localhost 8888
|
||||
```
|
||||
|
||||
### Log Analysis
|
||||
```bash
|
||||
# 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](https://docs.podman.io/)
|
||||
- [HMAC File Server GitHub](https://github.com/PlusOne/hmac-file-server)
|
||||
- [XEP-0363 Specification](https://xmpp.org/extensions/xep-0363.html)
|
||||
- [Container Security Best Practices](https://docs.podman.io/en/latest/markdown/podman-run.1.html#security-options)
|
||||
Reference in New Issue
Block a user