svcops/migrate repository overview

⁠migrate

migrate is a small Debian-based Docker image for moving files or directory contents between paths or mounted volumes. It is designed for scriptable one-shot migration jobs, with path validation, dry-run support, optional encrypted archive handling, and readable logs.

Image built by this module:

svcops/migrate:latest

⁠What It Does

• Migrates a source file or the contents of a source directory to a target directory.
• Validates source and target paths before copying.
• Creates the target directory when it does not exist.
• Supports dry-run mode for checking the operation before writing data.
• Uses rsync for directory migration, with a cp fallback.
• Supports password-protected 7-Zip archives created by compress.sh.
• Runs both inside Docker and as local shell scripts.

⁠Included Commands

The Docker image copies these commands to /usr/local/bin.

⁠Migration Behavior

When SRC is a directory, migrate.sh copies the contents of SRC into TARGET.

Before copying directory contents, the script cleans TARGET and preserves only TARGET/.gitignore when that file exists. Existing files in TARGET should be treated as replaceable migration output.

When SRC is a file, the script copies that file into TARGET.

⁠Configuration

⁠Docker Usage

Basic directory migration:

docker run --rm \
  -v /host/src:/data/src \
  -v /host/dst:/data/dst \
  -e SRC=/data/src \
  -e TARGET=/data/dst \
  svcops/migrate:latest

Dry run:

docker run --rm \
  -v /host/src:/data/src \
  -v /host/dst:/data/dst \
  -e SRC=/data/src \
  -e TARGET=/data/dst \
  -e DRY_RUN=true \
  svcops/migrate:latest

Use CLI arguments instead of environment variables:

docker run --rm \
  -v /host/src:/data/src \
  -v /host/dst:/data/dst \
  svcops/migrate:latest \
  migrate.sh /data/src /data/dst

Docker Compose example:

services:
  migrate:
    image: svcops/migrate:latest
    volumes:
      - ./src:/data/src
      - ./dst:/data/dst
    environment:
      SRC: /data/src
      TARGET: /data/dst

⁠Local Usage

Run with environment variables:

SRC=/path/to/source TARGET=/path/to/target migrate.sh

Run with CLI arguments:

migrate.sh /path/to/source /path/to/target

Run a dry run:

DRY_RUN=true SRC=/path/to/source TARGET=/path/to/target migrate.sh

Show help:

migrate.sh --help

⁠Encrypted Archive Workflow

compress.sh creates a password-protected 7-Zip archive for SRC, stores a marker file, and then removes the original source contents.

Create an archive with SRC from the environment:

SRC=/opt/src/some_dir compress.sh your-password

Or pass both source and password as arguments:

compress.sh /opt/src/some_dir your-password

Generated files:

To decrypt and migrate, run migrate.sh with the same SRC and ARCHIVE_PASSWORD. If the archive and marker exist, the script extracts the archive back into the recorded parent directory, then performs the normal migration into TARGET.

docker run --rm \
  -v /host/src:/data/src \
  -v /host/dst:/data/dst \
  -e SRC=/data/src \
  -e TARGET=/data/dst \
  -e ARCHIVE_PASSWORD=your-password \
  svcops/migrate:latest

⁠Build

Build the image with the provided script:

./build.sh

The Dockerfile accepts BUILD_ORIGIN. When BUILD_ORIGIN=LOCAL, Debian APT sources are rewritten to Aliyun mirrors during image build.

docker build \
  --build-arg BUILD_ORIGIN=LOCAL \
  -t svcops/migrate:latest \
  .

⁠Safety Notes

• Always use absolute paths for SRC and TARGET.
• TARGET must be a directory path, not a file.
• TARGET cannot be the same path as SRC.
• TARGET cannot be a system directory such as /, /usr, /var, or /etc.
• When SRC is a directory, TARGET cannot be inside SRC.
• In Docker, mount both source and target paths explicitly.
• In Docker, avoid mounting TARGET as a parent of the source file directory; this can hide source data through volume overlay behavior.
• Treat compress.sh as destructive: after a successful archive is created, the source file is deleted or the source directory contents are cleared.

⁠Dependencies

• Base image: debian:bookworm-slim
• Packages: bash, rsync, p7zip-full
• Default command: migrate.sh