docs: ✨ update docs

Author: Koro33

Cargo.toml

@@ -17,7 +17,7 @@ clap = { version = "4.5.1", features = ["derive"] }
 humansize = { version = "2.1.3", features = ["impl_style"] }
 opendal = { version = "0.45.0", features = ["layers-tracing"] }
 serde = { version = "1.0.197", features = ["derive"] }
-tempfile = "3.10.0"
+tempfile = "3.10.1"
 tokio = { version = "1.36.0", features = [
     "macros",
     "process",

README.md

@@ -1 +1,48 @@
-# SelfhostBackup
+# SelfhostBackup
+
+![GitHub Release](https://img.shields.io/github/v/release/Koro33/s-backup) ![GitHub License](https://img.shields.io/github/license/Koro33/s-backup) ![GitHub Repo stars](https://img.shields.io/github/stars/Koro33/s-backup)
+
+Use S3 (or compatible) storage service to backup your selfhosted service configurations.
+
+## Motivation
+
+Some of the cloud storage services(e.g. Backblaze, Cloudflare R2) provided free tier. Our individual users can use it free of charge, to backup small amount of data, e.g. selfhosted service configurations or data. This project aims to make it happen(and easy).
+
+## Usage
+
+### docker (recommend)
+
+```sh
+docker run -d \
+  -v /path/to/config.toml:/app/config.toml \
+  -v /path/to/backup:/backup_path_in_config:ro \
+  ghcr.io/koro33/s-backup:latest \
+  run
+```
+
+or docker compose, see [docker-compose.yml](./docker-compose.yml)
+
+**A config file should be provided**. see [config.example.toml](./config.example.toml)
+
+to test the config
+
+```sh
+docker run \
+  -v /path/to/config.toml:/app/config.toml \
+  ghcr.io/koro33/s-backup:latest \
+  test
+```
+
+### Cli
+
+```sh
+# run according to config
+s-backup run --config /path/to/config.toml
+
+# test config
+s-backup test --config /path/to/config.toml
+```
+
+## warning
+
+- **For backblaze(b2) user** since versioning is enabled, the delete opration will not really delete the files. it will create a new file with the same fileanme and set it to hidden. If you really want to delete the old backup(to avoid beyond free tier storage capacity), go backet `Lifecycle Settings`, and set it to `Keep only the last version`. As the docs say, "This rule keeps only the most current version of a file. The previous version of the file is “hidden” for **one day** and then deleted"

config.example.toml

@@ -1,19 +1,24 @@
+# provide s3 configuration
 [s3]
 access_key_id = "0000000000000000000000000"
 bucket = "bucket_name"
 endpoint = "endpoint_name"
 region = "region_name"
 secret_access_key = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
 
+# backup task configuration
 [[backup]]
-exclude = ["exclude", "data"]
-name = "test"
-path = "../test-rust"
-interval = 86400
-keep = 5
+exclude = ["./some_path", "./another/path"]   # exclude path (relative path to the `path` in this section)
+interval = 86400                              # run backup every n seconds
+keep = 5                                      # keep n backups (default: 5)
+name = "backup_task_1"                        # backup name (should be unique between tasks)
+path = "/backup/path"                         # location (see volume in docker-compose.yml)
 
+# another task
 [[backup]]
-exclude = ["exclude", "data"]
-name = "test2"
-path = "../test-rust"
+exclude = ["path", "to", "exclude"]
 interval = 43200
+name = "backup_task_2"
+path = "/backup/path"
+
+# ...

docker-compose.yml

@@ -2,11 +2,11 @@ version: '3'
 
 services:
   s-backup:
-    image: s-backup:latest
+    image: ghcr.io/koro33/s-backup:latest
     restart: unless-stopped
     environment:
       - TZ=Etc/UTC
     volumes:
-      - ./config.toml:/app/config.toml
+      - /path/to/config.toml:/app/config.toml  # config.toml
       - /path/to/backup:/backup_path_in_config:ro
     command: [run, --config, ./config.toml]

src/main.rs

@@ -93,6 +93,8 @@ async fn period_backup(b: &Backup, s3_oprator: &Operator) -> Result<()> {
 }
 
 async fn backup(b: &Backup, s3_oprator: &Operator) -> Result<()> {
+    tracing::info!("[{}] Start backup", b.name);
+
     let entries = s3_oprator.list("/").await.map_err(|e| {
         tracing::error!("connect to s3 failed: {}", e);
         e