Add support for mounting rclone.conf as alternative to base64 config

Author: whispin

Dockerfile

@@ -92,6 +92,9 @@ ENV RECOVERY_TARGET_XID=""
 ENV RECOVERY_TARGET_LSN=""
 ENV RECOVERY_TARGET_INCLUSIVE="true"
 ENV RECOVERY_TARGET_ACTION="promote"
+# rclone配置方式（二选一）：
+# 1. RCLONE_CONF_BASE64 - Base64编码的rclone配置
+# 2. 挂载rclone.conf文件到 /root/.config/rclone/rclone.conf
 
 # 暴露PostgreSQL端口
 EXPOSE 5432

QUICK_START_EN.md

@@ -8,9 +8,9 @@
 - PostgreSQL database to backup
 - rclone configuration for remote storage (optional)
 
-### Step 1: Prepare rclone Configuration
+### Step 1: Prepare rclone Configuration (Choose One Method)
 
-Create a base64 encoded rclone configuration:
+#### Method 1: Environment Variable (Recommended for Production)
 
 ```bash
 # Create rclone config file
@@ -28,8 +28,23 @@ RCLONE_CONF_BASE64=$(cat rclone.conf | base64 -w 0)
 echo $RCLONE_CONF_BASE64
 ```
 
+#### Method 2: File Mount (Recommended for Development)
+
+```bash
+# Create rclone config file
+cat > /path/to/rclone.conf << EOF
+[s3-remote]
+type = s3
+provider = AWS
+access_key_id = your_access_key
+secret_access_key = your_secret_key
+region = us-east-1
+EOF
+```
+
 ### Step 2: Run Backup Container
 
+#### Using Method 1 (Environment Variable):
 ```bash
 docker run -d \
   --name postgres-backup \
@@ -44,6 +59,21 @@ docker run -d \
   ghcr.io/whispin/postgres_nrt_backup:latest
 ```
 
+#### Using Method 2 (File Mount):
+```bash
+docker run -d \
+  --name postgres-backup \
+  -e POSTGRES_USER=myuser \
+  -e POSTGRES_PASSWORD=mypassword \
+  -e POSTGRES_DB=mydatabase \
+  -e PGBACKREST_STANZA=main \
+  -e WAL_GROWTH_THRESHOLD="100MB" \
+  -v /var/lib/postgresql/data:/var/lib/postgresql/data:ro \
+  -v ./backup-logs:/backup/logs \
+  -v /path/to/rclone.conf:/root/.config/rclone/rclone.conf:ro \
+  ghcr.io/whispin/postgres_nrt_backup:latest
+```
+
 ### Step 3: Verify Backup System
 
 ```bash

README.md

@@ -24,7 +24,7 @@ A comprehensive PostgreSQL near real-time backup and recovery solution based on
 # Pull the latest image
 docker pull ghcr.io/whispin/postgres_nrt_backup:latest
 
-# Run backup container
+# Method 1: Using RCLONE_CONF_BASE64 environment variable
 docker run -d \
   --name postgres-backup \
   -e POSTGRES_USER=myuser \
@@ -36,11 +36,25 @@ docker run -d \
   -v /path/to/postgres/data:/var/lib/postgresql/data:ro \
   -v /path/to/backup:/backup/local \
   ghcr.io/whispin/postgres_nrt_backup:latest
+
+# Method 2: Mounting rclone.conf file
+docker run -d \
+  --name postgres-backup \
+  -e POSTGRES_USER=myuser \
+  -e POSTGRES_PASSWORD=mypass \
+  -e POSTGRES_DB=mydb \
+  -e PGBACKREST_STANZA=main \
+  -e WAL_GROWTH_THRESHOLD="100MB" \
+  -v /path/to/postgres/data:/var/lib/postgresql/data:ro \
+  -v /path/to/backup:/backup/local \
+  -v /path/to/rclone.conf:/root/.config/rclone/rclone.conf:ro \
+  ghcr.io/whispin/postgres_nrt_backup:latest
 ```
 
 ### Recovery Mode
 
 ```bash
+# Method 1: Using RCLONE_CONF_BASE64 environment variable
 # Recover to latest backup
 docker run -d \
   --name postgres-recovery \
@@ -51,12 +65,16 @@ docker run -d \
   -e RECOVERY_MODE="true" \
   ghcr.io/whispin/postgres_nrt_backup:latest
 
+# Method 2: Mounting rclone.conf file
 # Point-in-time recovery
 docker run -d \
   --name postgres-recovery \
+  -e POSTGRES_USER=myuser \
+  -e POSTGRES_PASSWORD=mypass \
+  -e POSTGRES_DB=mydb \
   -e RECOVERY_MODE="true" \
   -e RECOVERY_TARGET_TIME="2025-07-10 14:30:00" \
-  # ... other environment variables
+  -v /path/to/rclone.conf:/root/.config/rclone/rclone.conf:ro \
   ghcr.io/whispin/postgres_nrt_backup:latest
 ```
 
@@ -93,7 +111,7 @@ docker-compose -f docker-compose.ghcr.yml up -d
 | `PGBACKREST_STANZA` | `main` | pgBackRest stanza name |
 | `BACKUP_RETENTION_DAYS` | `3` | Backup retention period in days |
 | `BASE_BACKUP_SCHEDULE` | `"0 3 * * *"` | Full backup schedule (cron format) |
-| `RCLONE_CONF_BASE64` | - | Base64 encoded rclone configuration |
+| `RCLONE_CONF_BASE64` | - | Base64 encoded rclone configuration (optional if file mounted) |
 | `RCLONE_REMOTE_PATH` | `"postgres-backups"` | Remote storage path |
 | `RECOVERY_MODE` | `"false"` | Enable recovery mode |
 | `WAL_GROWTH_THRESHOLD` | `"100MB"` | WAL growth threshold for auto backups |
@@ -111,14 +129,31 @@ docker-compose -f docker-compose.ghcr.yml up -d
 | `RECOVERY_TARGET_INCLUSIVE` | `"true"` | Include recovery target |
 | `RECOVERY_TARGET_ACTION` | `"promote"` | Action after recovery |
 
+### rclone Configuration (Choose One Method)
+
+#### Method 1: Environment Variable
+```bash
+# Encode your rclone.conf to base64
+RCLONE_CONF_BASE64=$(cat rclone.conf | base64 -w 0)
+
+# Use in docker run
+docker run -e RCLONE_CONF_BASE64="$RCLONE_CONF_BASE64" ...
+```
+
+#### Method 2: File Mount
+```bash
+# Mount rclone.conf directly
+docker run -v /path/to/rclone.conf:/root/.config/rclone/rclone.conf:ro ...
+```
+
 ### Volume Mounts
 
 | Path | Description | Permission |
 |------|-------------|------------|
 | `/var/lib/postgresql/data` | PostgreSQL data directory | Read-only |
 | `/backup/local` | Local backup storage | Read-write |
 | `/backup/logs` | Backup logs | Read-write |
-| `/root/.config/rclone/rclone.conf` | rclone configuration file | Read-only |
+| `/root/.config/rclone/rclone.conf` | rclone configuration file (optional) | Read-only |
 
 ## 🔧 Manual Operations
 
@@ -246,6 +281,7 @@ The project uses GitHub Actions for automated building and publishing:
 ## 📚 Documentation
 
 - [Quick Start Guide](QUICK_START_EN.md) - Get started in 5 minutes
+- [rclone Configuration Guide](RCLONE_CONFIGURATION_GUIDE.md) - Two methods to configure rclone
 - [Manual Backup Guide](MANUAL_BACKUP_GUIDE.md)
 - [WAL Monitor Guide](WAL_MONITOR_GUIDE.md)
 - [Recovery Guide](RECOVERY_GUIDE.md)

README_ZH.md

@@ -24,7 +24,7 @@
 # 拉取最新镜像
 docker pull ghcr.io/whispin/postgres_nrt_backup:latest
 
-# 运行备份容器
+# 方式1：使用RCLONE_CONF_BASE64环境变量
 docker run -d \
   --name postgres-backup \
   -e POSTGRES_USER=myuser \
@@ -36,12 +36,25 @@ docker run -d \
   -v /path/to/postgres/data:/var/lib/postgresql/data:ro \
   -v /path/to/backup:/backup/local \
   ghcr.io/whispin/postgres_nrt_backup:latest
+
+# 方式2：直接挂载rclone.conf文件
+docker run -d \
+  --name postgres-backup \
+  -e POSTGRES_USER=myuser \
+  -e POSTGRES_PASSWORD=mypass \
+  -e POSTGRES_DB=mydb \
+  -e PGBACKREST_STANZA=main \
+  -e WAL_GROWTH_THRESHOLD="100MB" \
+  -v /path/to/postgres/data:/var/lib/postgresql/data:ro \
+  -v /path/to/backup:/backup/local \
+  -v /path/to/rclone.conf:/root/.config/rclone/rclone.conf:ro \
+  ghcr.io/whispin/postgres_nrt_backup:latest
 ```
 
 ### 恢复模式
 
 ```bash
-# 恢复到最新备份
+# 方式1：使用RCLONE_CONF_BASE64环境变量恢复到最新备份
 docker run -d \
   --name postgres-recovery \
   -e POSTGRES_USER=myuser \
@@ -51,12 +64,15 @@ docker run -d \
   -e RECOVERY_MODE="true" \
   ghcr.io/whispin/postgres_nrt_backup:latest
 
-# 恢复到指定时间点
+# 方式2：挂载rclone.conf文件进行时间点恢复
 docker run -d \
   --name postgres-recovery \
+  -e POSTGRES_USER=myuser \
+  -e POSTGRES_PASSWORD=mypass \
+  -e POSTGRES_DB=mydb \
   -e RECOVERY_MODE="true" \
   -e RECOVERY_TARGET_TIME="2025-07-10 14:30:00" \
-  # ... 其他环境变量
+  -v /path/to/rclone.conf:/root/.config/rclone/rclone.conf:ro \
   ghcr.io/whispin/postgres_nrt_backup:latest
 ```
 

scripts/backup-functions.sh

@@ -139,14 +139,38 @@ setup_rclone() {
 
     mkdir -p "$(dirname "$RCLONE_CONFIG_PATH")"
 
-    if ! echo "$RCLONE_CONF_BASE64" | base64 -d | tr -d '\r' > "$RCLONE_CONFIG_PATH"; then
-        log "ERROR" "Failed to decode RCLONE_CONF_BASE64 or write to $RCLONE_CONFIG_PATH."
+    # Check if rclone.conf is already mounted
+    if [ -f "$RCLONE_CONFIG_PATH" ] && [ -s "$RCLONE_CONFIG_PATH" ]; then
+        log "INFO" "Found mounted rclone configuration file at $RCLONE_CONFIG_PATH"
+
+        # Verify the mounted configuration file
+        if ! rclone config show --config "$RCLONE_CONFIG_PATH" >/dev/null 2>&1; then
+            log "ERROR" "Mounted rclone configuration file is invalid"
+            return 1
+        fi
+
+        log "INFO" "Using mounted rclone configuration"
+
+    elif [ -n "$RCLONE_CONF_BASE64" ]; then
+        log "INFO" "Using RCLONE_CONF_BASE64 environment variable"
+
+        # Decode and save rclone configuration
+        if ! echo "$RCLONE_CONF_BASE64" | base64 -d | tr -d '\r' > "$RCLONE_CONFIG_PATH"; then
+            log "ERROR" "Failed to decode RCLONE_CONF_BASE64 or write to $RCLONE_CONFIG_PATH."
+            return 1
+        fi
+
+        chmod 644 "$RCLONE_CONFIG_PATH"
+        log "INFO" "Rclone configuration created from RCLONE_CONF_BASE64 at $RCLONE_CONFIG_PATH."
+
+    else
+        log "ERROR" "Neither rclone.conf file nor RCLONE_CONF_BASE64 environment variable provided"
+        log "INFO" "Please either:"
+        log "INFO" "  1. Mount rclone.conf file to: $RCLONE_CONFIG_PATH"
+        log "INFO" "  2. Set RCLONE_CONF_BASE64 environment variable"
         return 1
     fi
 
-    chmod 644 "$RCLONE_CONFIG_PATH"
-    log "INFO" "Rclone configuration created at $RCLONE_CONFIG_PATH."
-    
     # Use RCLONE_REMOTE_NAME if specified, otherwise extract first remote from config
     if [[ -n "$RCLONE_REMOTE_NAME" ]]; then
         REMOTE_NAME="$RCLONE_REMOTE_NAME"