Alexander Renz
9751fb9e93
- 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.
264 lines
6.0 KiB
Markdown
264 lines
6.0 KiB
Markdown
# 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)
|