Skip to content

Commit

Permalink
πŸ“ Update README with new features and use cases
Browse files Browse the repository at this point in the history
Revise README to highlight key features and practical applications

Enhancements include:
- Reorganize structure for better readability
- Add 'Key Features' section emphasizing core capabilities
- Include 'Getting Started' with simplified installation instructions
- Expand 'Usage' section with basic command examples
- Add 'Advanced Topics' covering configuration and remote structure
- Introduce 'Use Cases' section with practical backup scenarios
- Update development and contribution guidelines

These changes provide a more comprehensive and user-friendly overview
of AeonSync's capabilities and potential applications.
  • Loading branch information
hyperb1iss committed Sep 15, 2024
1 parent e1fc251 commit 47609ca
Showing 1 changed file with 87 additions and 88 deletions.
175 changes: 87 additions & 88 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,73 +8,49 @@

_A powerful and flexible remote backup tool for developers and system administrators_

[Features](#-features) β€’ [Installation](#-installation) β€’ [Usage](#-usage) β€’ [Configuration](#%EF%B8%8F-configuration) β€’ [Development](#%EF%B8%8F-development) β€’ [Contributing](#-contributing) β€’ [License](#-license)
[Key Features](#-key-features) β€’ [Getting Started](#-getting-started) β€’ [Usage](#-usage) β€’ [Advanced Topics](#-advanced-topics) β€’ [Contributing](#-contributing)

</div>

## ✨ Features
## ✨ Key Features

AeonSync offers a comprehensive set of features for efficient and secure remote backups:
AeonSync redefines remote backups with its powerful feature set:

- πŸ”„ **Incremental Backups**: Utilizes rsync's `--link-dest` for efficient storage management
- πŸ” **Secure Remote Syncing**: Implements SSH for secure data transfer
- ⏱️ **Customizable Retention Policies**: Automatically cleans up old backups based on user-defined policies
- πŸ§ͺ **Dry-run Mode**: Test backups without making changes to ensure configuration accuracy
- πŸ“Š **Detailed Metadata Tracking**: Maintains comprehensive metadata for each backup operation
- πŸ–₯️ **User-friendly CLI**: Powered by Typer for an intuitive command-line interface
- 🎨 **Rich Console Output**: Enhances readability with colorized and formatted output
- πŸ” **Verbose Mode**: Provides detailed transfer logs for in-depth analysis
- πŸ—‚οΈ **Multiple Source Support**: Backup multiple directories in a single operation
- πŸ” **Latest Backup Symlink**: Automatically creates a symlink to the most recent backup
- πŸ•°οΈ **Version Selection**: Choose specific versions of files for restoration
- πŸ‘€ **File Preview**: View file contents before restoration
- πŸ“Š **Diff Display**: Compare different versions of files
- πŸ”„ **Interactive Restore**: User-friendly guided process for file recovery
- πŸ“œ **Comprehensive Backup Listing**: Detailed information about all available backups
- βš™οΈ **Flexible Configuration**: Easily customizable through command-line options or configuration file
- πŸ”„ **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

## πŸ’» Installation
## πŸš€ Getting Started

### Prerequisites
### Requirements

- Python 3.12 or higher
- SSH access to a remote server
- rsync installed on both local and remote systems
- Python 3.12+
- SSH access to remote server/NAS
- rsync on local and remote systems

### Using pip
### Installation

```bash
pip install aeonsync
```

### Using Poetry
## πŸ“˜ Usage

```bash
git clone https://github.com/hyperb1iss/aeonsync.git
cd aeonsync
poetry install
```

After installation, the `aeon` command will be available in your system path.

## πŸš€ Usage

AeonSync provides an intuitive command-line interface for easy interaction with your backup setup.

### Basic Commands
Basic command structure:

```bash
# Perform a backup
# 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 [OPTIONS]

# Show help
aeon --help
aeon list-backups
```

### Sync Command
Expand All @@ -92,10 +68,11 @@ Options:
- `--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 powerful functionality for file recovery:
The restore command provides functionality for file recovery:

```bash
aeon restore [OPTIONS] [FILE] [DATE]
Expand All @@ -118,61 +95,83 @@ aeon list-backups [OPTIONS]

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

### Configuration Command

Manage AeonSync configuration:

```bash
aeon config [OPTIONS]
```

Options:
## πŸ”§ Advanced Topics

- `--hostname TEXT`: Set the hostname
- `--remote-address TEXT`: Set the remote address
- `--remote-path TEXT`: Set the remote path
- `--remote-port INTEGER`: Set the remote port
- `--retention-period INTEGER`: Set the retention period in days
- `--add-source-dir TEXT`: Add a source directory
- `--remove-source-dir TEXT`: Remove a source directory
- `--add-exclusion TEXT`: Add an exclusion pattern
- `--remove-exclusion TEXT`: Remove an exclusion pattern
- `--ssh-key TEXT`: Set the SSH key path
- `--verbose`: Set verbose mode
- `--log-file TEXT`: Set the log file path
- `--show`: Show current configuration

## βš™οΈ Configuration
### βš™οΈ Configuration

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

- `hostname`: Hostname for the backup
- `remote_address`: Remote server address
- `remote_path`: Path on the remote server for backups
- `remote_port`: SSH port for the remote server
- `retention_period`: Number of days to keep backups
- `source_dirs`: List of directories to back up
- `exclusions`: Patterns to exclude from backups
- `ssh_key`: Path to SSH key file
- `verbose`: Enable verbose logging
- `log_file`: Path to log file

Example configuration:

```python
hostname = "myhost"
remote_address = "user@example.com"
remote_path = "/backups"
hostname = "myworkstation"
remote_address = "user@nas.local"
remote_path = "/volume1/backups"
remote_port = 22
retention_period = 30
source_dirs = ["/home/user", "/var/www"]
exclusions = [".cache", "*/node_modules", "*.tmp"]
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:

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

#### Web Server Backup

Safeguard your web applications and databases:

```bash
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:

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

#### Small Business Server

Comprehensive backup solution for critical business data:

```bash
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
### πŸ› οΈ Development

To set up the development environment:

Expand Down

0 comments on commit 47609ca

Please sign in to comment.