🌀 AeonSync

A powerful and flexible remote backup tool for developers and system administrators

Key Features • Getting Started • Usage • Advanced Topics • Contributing

✨ Key Features

AeonSync redefines remote backups with its powerful feature set:

• 🔄 Flexible Backup Modes: Daily snapshots or multiple backups per day
• 🔗 Efficient Incremental Backups: Leverages rsync's --link-dest for optimal storage use
• 🔐 Secure Remote Syncing: Rock-solid SSH encryption for data transfer
• ⏱️ Smart Retention Policies: Automatic management of your backup history
• 🕰️ Version Control: Restore specific file versions with ease
• 🖥️ Intuitive CLI: Seamless command-line experience powered by Typer
• 📊 Rich Metadata: Comprehensive insights into each backup operation

🚀 Getting Started

Requirements

• Python 3.12+
• SSH access to remote server/NAS
• rsync on local and remote systems
• uv (recommended) or pip

Installation

With UV (recommended):

uv pip install aeonsync

With pip:

pip install aeonsync

📘 Usage

Basic command structure:

# Perform a backup (multiple per day by default)
aeon sync --remote user@host:/path/to/backups

# Restore a file
aeon restore [OPTIONS] FILE [DATE]

# List available backups
aeon list-backups

Sync Command

The sync command is used to create backups:

aeon sync [OPTIONS]

Options:

• --remote TEXT: Remote destination in the format [user@]host:path
• --source PATH: Source directories to backup (can be specified multiple times)
• --retention INTEGER: Number of days to retain backups
• --dry-run: Perform a dry run without making changes
• --verbose: Enable verbose output
• --daily: Create only one backup per day (overrides default behavior)

Restore Command

The restore command provides functionality for file recovery:

aeon restore [OPTIONS] [FILE] [DATE]

Options:

• --output PATH: Output directory for restored file or directory
• --interactive: Use fully interactive mode for restore
• --diff: Show diff between local and backup versions
• --preview: Show a preview of the file before restoring

List Backups Command

To view available backups:

aeon list-backups [OPTIONS]

This command displays a detailed list of all backups, including dates, file counts, and total sizes.

🔧 Advanced Topics

⚙️ Configuration

AeonSync can be configured using command-line options or by modifying the configuration file:

hostname = "myworkstation"
remote_address = "[email protected]"
remote_path = "/volume1/backups"
remote_port = 22
retention_period = 30
source_dirs = ["/home/user/projects", "/var/www", "/etc"]
exclusions = [".cache", "*/node_modules", "*.tmp", ".venv"]
ssh_key = "/home/user/.ssh/id_rsa"
verbose = False
log_file = "/home/user/.local/share/aeonsync/aeonsync.log"
default_daily_backup = False  # Set to True to allow only one backup per day

📁 Remote Structure

AeonSync organizes your backups as follows:

/volume1/backups/
└── myworkstation/
    ├── latest -> 2024-03-15
    ├── 2024-03-15/
    ├── 2024-03-14/
    ├── 2024-03-13.1/
    ├── 2024-03-13/
    └── ...

• Each backup is stored in a date-stamped directory
• Multiple backups per day append a sequence number (e.g., 2024-03-13.1)
• The latest symlink always points to the most recent backup

🌟 Use Cases

AeonSync can be used in various scenarios:

Home Office Backup

Protect your projects and documents with daily backups to your Synology NAS:

aeon sync --remote user@synology:/volume1/backups --source /home/user/projects --source /home/user/documents

Web Server Backup

Safeguard your web applications and databases:

aeon sync --remote backupuser@remote-server:/backups --source /var/www --source /var/lib/mysql

Developer Workstation

Keep your code safe with multiple backups per day:

aeon sync --remote user@dev-server:/backups --source /home/dev/workspace

Small Business Server

Comprehensive backup solution for critical business data:

aeon config --hostname business-server --remote-address nas.local --remote-path /volume1/business-backups
aeon sync --source /home/shared --source /var/financial-data --retention 90

🛠️ Development

To set up the development environment:

1. Clone the repository:

   git clone https://github.com/hyperb1iss/aeonsync.git
   cd aeonsync

2. Install UV if you haven't already:

   curl -LsS https://astral.sh/uv/install.sh | bash

3. Create development environment and install dependencies:

   uv venv
   uv sync

4. Activate the virtual environment:

   source .venv/bin/activate  # On Linux/macOS
   .venv\Scripts\activate     # On Windows

To run tests:

uv run pytest

To run linting checks:

uv run ruff check .
uv run mypy .

👥 Contributing

Contributions to AeonSync are welcome! Here's how you can contribute:

1. Fork the repository
2. Create a new branch: git checkout -b feature-branch-name
3. Make your changes and commit them: git commit -m 'Add some feature'
4. Push to the branch: git push origin feature-branch-name
5. Submit a pull request

Please ensure your code adheres to the project's style guide (we use Ruff for formatting) and passes all tests.

📄 License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.

---

📚 Documentation • 🐛 Report Bug • 💡 Request Feature

Created by Stefanie Jane 🌠

If you find this project useful, buy me a Monster Ultra Violet! ⚡️