mildman1848/rclone repository overview

⁠rclone Docker Image

🐳 Docker Hub: mildman1848/rclone⁠

A production-ready Docker image for rclone⁠ based on the LinuxServer.io Alpine baseimage with enhanced security features, automatic secret management, full LinuxServer.io compliance, and CI/CD integration. rclone is a command-line program to manage files on cloud storage.

⁠🚀 Features

• ✅ LinuxServer.io Alpine Baseimage 3.22 - Optimized and secure
• ✅ S6 Overlay v3 - Professional process management
• ✅ Full LinuxServer.io Compliance - FILE__ secrets, Docker Mods, custom scripts
• ✅ Enhanced Security Hardening - Non-root execution, capability dropping, secure permissions
• ✅ OCI Manifest Lists - True multi-architecture support following OCI standard
• ✅ LinuxServer.io Pipeline - Architecture-specific tags + manifest lists
• ✅ Multi-Platform Support - AMD64, ARM64 with native performance
• ✅ Advanced Health Checks - Automatic monitoring with failover
• ✅ Robust Secret Management - 512-bit JWT, 256-bit API keys, secure rotation
• ✅ Automated Build System - Make + GitHub Actions CI/CD with manifest validation
• ✅ Environment Validation - Comprehensive configuration checks
• ✅ Security Scanning - Integrated vulnerability scans with Trivy + CodeQL
• ✅ OCI Compliance - Standard-compliant container labels and manifest structure

⁠🚀 Quick Start

⁠Automated Setup (Recommended)

# Clone repository
git clone https://github.com/mildman1848/rclone.git
cd rclone

# Complete setup (environment + secrets)
make setup

# Start container
docker-compose up -d

⁠With Docker Compose (Manual)

# Clone repository
git clone https://github.com/mildman1848/rclone.git
cd rclone

# Configure environment
cp .env.example .env
# Adjust .env as needed

# Generate secure secrets
make secrets-generate

# Start container (docker-compose.override.yml provides security hardening)
docker-compose up -d

⁠With Docker Run

docker run -d \
  --name rclone \
  -p 5572:5572 \
  -v /path/to/config:/config \
  -v /path/to/data:/data \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Europe/Berlin \
  --restart unless-stopped \
  mildman1848/rclone:latest

⁠🛠️ Build & Development

⁠Makefile Targets

# Show help
make help

# Complete setup
make setup                   # Initial setup (env + secrets)
make env-setup               # Create environment from .env.example
make env-validate            # Validate environment

# Secret Management (Enhanced)
make secrets-generate        # Generate secure secrets (512-bit JWT, 256-bit API)
make secrets-rotate          # Rotate secrets (with backup)
make secrets-clean           # Clean up old secret backups
make secrets-info            # Show secret status

# Build & Test (Enhanced with OCI Manifest Lists)
make build                   # Build image for current platform
make build-multiarch         # Multi-architecture build (legacy)
make build-manifest          # LinuxServer.io style manifest lists (recommended)
make inspect-manifest        # Inspect manifest lists (multi-arch details)
make validate-manifest       # Validate OCI manifest compliance
make test                    # Test container (with health checks)
make security-scan           # Run comprehensive security scan (Trivy + CodeQL)
make trivy-scan              # Run Trivy vulnerability scan only
make codeql-scan             # Run CodeQL static code analysis
make validate                # Validate Dockerfile

# Container Management
make start                   # Start container
make stop                    # Stop container
make restart                 # Restart container
make status                  # Show container status and health
make logs                    # Show container logs
make shell                   # Open shell in container

# Development
make dev                     # Start development container

# Release
make release                 # Complete release workflow
make push                    # Push image to registry

⁠Manual Build

# Build image
docker build -t mildman1848/rclone:latest .

# With specific arguments
docker build \
  --build-arg RCLONE_VERSION=v1.71.0 \
  --build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') \
  -t mildman1848/rclone:latest .

⁠Production Deployment

# Use production configuration with enhanced security
docker-compose -f docker-compose.yml -f docker-compose.production.yml up -d

# Or use the override file for automatic security hardening
docker-compose up -d  # Automatically applies docker-compose.override.yml

⁠⚙️ Configuration

⁠Environment File

Configuration is done via a .env file containing all environment variables:

# Create .env from template
cp .env.example .env

# Adjust values as needed
nano .env

The .env.example contains all available options with documentation and links to the official rclone documentation.

⁠Important Environment Variables

⁠🔐 Enhanced LinuxServer.io Secrets Management

FILE__ Prefix (Recommended): The image supports the LinuxServer.io standard FILE__ prefix for secure secret management:

# .env file - FILE__ prefix secrets for rclone
FILE__RCLONE_CONFIG_PASS=/run/secrets/rclone_config_pass
FILE__RCLONE_WEB_GUI_PASSWORD=/run/secrets/rclone_web_pass
FILE__RCLONE_PASSWORD=/run/secrets/rclone_password

# Docker Compose example
environment:
  - FILE__RCLONE_CONFIG_PASS=/run/secrets/rclone_config_pass
  - FILE__RCLONE_WEB_GUI_PASSWORD=/run/secrets/rclone_web_pass

Enhanced Secret Generation:

# Secure secret generation (improved algorithms)
make secrets-generate        # 512-bit JWT, 256-bit API keys

# Secret rotation with backup
make secrets-rotate

# Check secret status
make secrets-info

Supported Secrets (rclone-specific):

⁠Volumes

⁠rclone Operation Modes

The container supports two primary operation modes:

⁠1. rcd Mode (Default) - Remote Control Daemon with Web GUI

• Port: 5572 (official rclone Web GUI port)
• Features: Full Web-based management interface
• Access: http://localhost:5572⁠
• Configuration: RCLONE_MODE=rcd

⁠2. serve Mode - File Server

• Port: Configurable (default 5572)
• Features: File serving with optional Web GUI
• Protocols: http, webdav, ftp, sftp
• Configuration: RCLONE_MODE=serve

# rcd mode (Web GUI) - Default
RCLONE_MODE=rcd

# serve mode (File Server)
RCLONE_MODE=serve
RCLONE_SERVE_PROTOCOL=http  # or webdav, ftp, sftp

⁠🔧 Enhanced LinuxServer.io S6 Overlay Services

The image uses S6 Overlay v3 with optimized services following LinuxServer.io standards:

• init-branding - Custom Mildman1848 ASCII art branding
• init-mods-package-install - Docker Mods installation
• init-custom-files - Custom scripts & UMASK setup
• init-secrets - Enhanced FILE__ prefix & legacy secret processing
• init-rclone-config - rclone configuration with validation
• rclone - Main application with correct parameter passing

⁠Service Dependencies (Fixed)

init-branding → init-mods-package-install → init-custom-files → init-secrets → init-rclone-config → rclone

⁠Service Improvements

• ✅ Secure Permissions - Fallback methods for chmod issues
• ✅ Enhanced Validation - JSON config validation
• ✅ Robust Error Handling - Graceful fallbacks on errors
• ✅ Security Hardening - Path validation for FILE__ secrets

⁠LinuxServer.io Features

Docker Mods Support:

# Single mod
DOCKER_MODS=linuxserver/mods:universal-cron

# Multiple mods (separated by |)
DOCKER_MODS=linuxserver/mods:universal-cron|linuxserver/mods:rclone-custom

Custom Scripts:

# Scripts in /custom-cont-init.d are executed before services
docker run -v ./my-scripts:/custom-cont-init.d:ro mildman1848/rclone

UMASK Support:

# Default: 022 (files: 644, directories: 755)
UMASK=022

⁠🔒 Enhanced Security

⁠Advanced Security Hardening

The image implements comprehensive security measures:

• ✅ Non-root Execution - Container runs as user abc (UID 911)
• ✅ Capability Dropping - ALL capabilities dropped, minimal required added
• ✅ no-new-privileges - Prevents privilege escalation
• ✅ Secure File Permissions - 750 for directories, 640 for files
• ✅ Path Validation - FILE__ secret path sanitization
• ✅ Enhanced Error Handling - Secure fallbacks for permission issues
• ✅ tmpfs Mounts - Temporary files in memory
• ✅ Security Opt - Additional kernel security features
• ✅ Robust Secret Handling - 512-bit encryption, secure rotation

⁠Security Scanning & Vulnerability Management

Latest Security Improvements (September 2025):

• ✅ 68% Vulnerability Reduction - From 28 to 9 vulnerabilities through comprehensive npm package updates
• ✅ CodeQL Integration - Static code analysis for JavaScript/TypeScript
• ✅ Enhanced npm Security - Updated 16+ vulnerable packages (axios, express, cookie, etc.)
• ✅ Automated Scanning - GitHub Actions integration for continuous security monitoring

# Comprehensive security scan (Trivy + CodeQL)
make security-scan

# Individual scanning tools
make trivy-scan              # Vulnerability scanning only
make codeql-scan             # Static code analysis only
make security-scan-detailed  # Detailed scan with exports

# Manual scanning
trivy image mildman1848/rclone:latest
trivy fs --format sarif --output trivy-results.sarif .

# Dockerfile validation
make validate

⁠Docker Security Best Practices

Implemented Security Features:

• ✅ docker-compose.override.yml - Automatic security hardening
• ✅ docker-compose.production.yml - Production-ready configuration
• ✅ seccomp-profile.json - Custom syscall filtering
• ✅ Capability dropping - Minimal required privileges
• ✅ Non-root execution - User abc (UID 911)
• ✅ Resource limits - CPU, memory, and PID constraints
• ✅ Network isolation - Custom bridge networks
• ✅ tmpfs mounts - Temporary files in memory
• ✅ Read-only filesystems where applicable

# 1. Use LinuxServer.io FILE__ secrets for rclone
FILE__RCLONE_CONFIG_PASS=/run/secrets/rclone_config_pass
FILE__RCLONE_WEB_GUI_PASSWORD=/run/secrets/rclone_web_pass
FILE__RCLONE_PASSWORD=/run/secrets/rclone_password

# 2. Set host user IDs (LinuxServer.io standard)
export PUID=$(id -u)
export PGID=$(id -g)

# 3. Use restrictive UMASK for production
export UMASK=027  # More secure than default 022

# 4. Secure secret generation
make secrets-generate

# 5. Validate configuration
make env-validate

# 6. Use specific image tags
docker run mildman1848/rclone:v1.71.0  # instead of :latest

# 7. Monitor container health
make status  # Container status and health checks

# 8. Production deployment with maximum security
docker-compose -f docker-compose.yml -f docker-compose.production.yml up -d

# 9. Development with automatic security hardening
docker-compose up -d  # Uses docker-compose.override.yml automatically

# 10. Use custom seccomp profile for syscall filtering
# Automatically applied in docker-compose.production.yml

⁠OCI Manifest Lists & LinuxServer.io Pipeline

OCI-compliant Multi-Architecture Support:

# Automatic platform detection (Docker pulls the right image)
docker pull mildman1848/rclone:latest

# Platform-specific tags (LinuxServer.io style)
docker pull mildman1848/rclone:amd64-latest    # Intel/AMD 64-bit
docker pull mildman1848/rclone:arm64-latest    # ARM 64-bit (Apple M1, Pi 4)

# Inspect manifest lists
make inspect-manifest
docker manifest inspect mildman1848/rclone:latest

Technical Details:

• ✅ OCI Image Manifest Specification v1.1.0 compliant
• ✅ LinuxServer.io Pipeline Standards - Architecture tags + manifest lists
• ✅ Native Performance - No emulation, real platform builds
• ✅ Automatic Platform Selection - Docker chooses optimal image
• ✅ Backward Compatibility - Works with all Docker clients

Manifest Structure:

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
  "manifests": [
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "platform": { "architecture": "amd64", "os": "linux" }
    },
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "platform": { "architecture": "arm64", "os": "linux" }
    }
  ]
}

⁠LinuxServer.io Compatibility

# Fully compatible with LinuxServer.io standards
# ✅ S6 Overlay v3
# ✅ FILE__ Prefix Secrets
# ✅ DOCKER_MODS Support
# ✅ Custom Scripts (/custom-cont-init.d)
# ✅ UMASK Support
# ✅ PUID/PGID Management
# ✅ Custom Branding (LinuxServer.io compliant)
# ✅ OCI Manifest Lists (2024 Pipeline Standard)

⁠🎨 Container Branding

The container shows a custom ASCII-art branding for "Mildman1848" at startup:

███╗   ███╗██╗██╗     ██████╗ ███╗   ███╗ █████╗ ███╗   ██╗ ██╗ █████╗ ██╗  ██╗ █████╗
████╗ ████║██║██║     ██╔══██╗████╗ ████║██╔══██╗████╗  ██║███║██╔══██╗██║  ██║██╔══██╗
██╔████╔██║██║██║     ██║  ██║██╔████╔██║███████║██╔██╗ ██║╚██║╚█████╔╝███████║╚█████╔╝
██║╚██╔╝██║██║██║     ██║  ██║██║╚██╔╝██║██╔══██║██║╚██╗██║ ██║██╔══██╗╚════██║██╔══██╗
██║ ╚═╝ ██║██║███████╗██████╔╝██║ ╚═╝ ██║██║  ██║██║ ╚████║ ██║╚█████╔╝     ██║╚█████╔╝
╚═╝     ╚═╝╚═╝╚══════╝╚═════╝ ╚═╝     ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝ ╚═╝ ╚════╝      ╚═╝ ╚════╝

Branding Features:

• ✅ LinuxServer.io Compliance - Correct branding implementation
• ✅ Custom ASCII Art - Unique Mildman1848 representation
• ✅ Version Information - Build details and rclone version
• ✅ Support Links - Clear references for help and documentation
• ✅ Feature Overview - Overview of implemented LinuxServer.io features

⁠Monitoring & Health Checks

⁠Health Check

The image includes automatic health checks:

# Check status
docker inspect --format='{{.State.Health.Status}}' rclone

# Show logs
docker logs rclone

⁠rclone Monitoring

Built-in Monitoring:

• Health checks via process validation
• Container status monitoring
• Log aggregation

rclone Web GUI (rcd mode):

• Real-time transfer monitoring
• Configuration management
• File browser interface

Prometheus Metrics (Optional): rclone can export Prometheus metrics when configured with --rc-enable-metrics. See rclone documentation⁠ for details.

# Enable Prometheus metrics
RCLONE_RC_ENABLE_METRICS=true
# Access metrics at http://localhost:5572/metrics

⁠📁 Configuration Files

⁠🔧 Troubleshooting

⁠Common Issues

# Adjust PUID/PGID to host user
export PUID=$(id -u)
export PGID=$(id -g)
docker-compose up -d

# Or set in .env
echo "PUID=$(id -u)" >> .env
echo "PGID=$(id -g)" >> .env

# Change port in .env
echo "EXTERNAL_PORT=13379" >> .env

# Or directly in docker-compose.yml
ports:
  - "13379:5572"

# 1. Check logs
make logs

# 2. Health check status
docker inspect --format='{{.State.Health.Status}}' rclone

# 3. Validate environment
make env-validate

# 4. Debug shell
make shell

# Use LinuxServer.io FILE__ secrets
echo "FILE__JWT_SECRET=/run/secrets/jwt_secret" >> .env

# Generate legacy secrets
make secrets-generate

# Check secret status
make secrets-info

# Manual FILE__ secret creation
mkdir -p secrets
openssl rand -base64 64 > secrets/jwt_secret.txt
echo "FILE__JWT_SECRET=$(pwd)/secrets/jwt_secret.txt" >> .env

⁠Debug Mode

# Development container with debug logging
echo "LOG_LEVEL=debug" >> .env
echo "DEBUG_MODE=true" >> .env
echo "VERBOSE_LOGGING=true" >> .env
make dev

# Shell access
make shell

# Container inspection
docker exec -it rclone /bin/bash

⁠🤝 Contributing

⁠Development Workflow

1. Fork & Clone

   git clone https://github.com/yourusername/rclone.git
   cd rclone
   

   Copy

2. Setup Development Environment

   make setup
   make dev
   

   Copy

3. Make Changes & Test

   make validate      # Dockerfile linting
   make build         # Build image
   make test          # Run tests
   make security-scan # Security check
   

   Copy

4. Submit PR

   • Create a feature branch
   • Test all changes
   • Create a pull request

⁠CI/CD Pipeline

The project uses GitHub Actions for:

• ✅ Automated Testing - Dockerfile, container, integration tests
• ✅ Security Scanning - Trivy, Hadolint, SBOM generation
• ✅ OCI Manifest Lists - LinuxServer.io pipeline with architecture-specific tags
• ✅ Multi-Architecture Builds - AMD64, ARM64 with native performance
• ✅ Manifest Validation - OCI compliance and platform verification
• ✅ Automated Releases - Semantic versioning, Docker Hub/GHCR
• ✅ Dependency Updates - Dependabot integration
• ✅ Upstream Monitoring - Automated dependency tracking and update notifications

⁠🔄 Upstream Dependency Monitoring

The project includes automated monitoring of upstream dependencies:

• rclone Application: Monitors rclone/rclone⁠ releases
• LinuxServer.io Base Image: Tracks linuxserver/docker-baseimage-alpine⁠ updates
• Automated Notifications: Creates GitHub issues for new releases
• Security Assessment: Prioritizes security-related updates
• Semi-Automated: rclone updates via PR, base image updates require manual review

Monitoring Schedule: Monday and Thursday at 6 AM UTC

See UPSTREAM_AUTOMATION_EVALUATION.md⁠ for detailed implementation strategy.

⁠🔧 Setup Requirements

For GHCR (GitHub Container Registry) support:

• Create a Personal Access Token with write:packages and read:packages scopes
• Add as repository secret: GHCR_TOKEN
• Path: Repository Settings → Secrets and variables → Actions → New repository secret

All other workflows work without additional setup.

⁠License

This project is licensed under the MIT License. See LICENSE⁠ for details.

⁠Acknowledgments

• rclone⁠ - Original project
• LinuxServer.io⁠ - Baseimage and best practices
• S6 Overlay⁠ - Process management