wip: documentation

.gitignore

@@ -1,3 +1,3 @@
-.seafile_backup.db.json
+.seafile_mirror.db.json
 __pycache__/
 *.log

README.md

@@ -0,0 +1,62 @@
+# Seafile Mirror
+
+A Python tool to handle clean read-only (re-)syncs of
+[Seafile](https://www.seafile.com) libraries with the intention to mirror them.
+
+## Overview
+
+If you have Seafile libraries, you may want to back them up in a safe place
+automatically.
+
+One option is to snapshot/backup the whole server on which the library is
+stored. However, in some situations, this may not be feasible or even not
+possible.
+
+This is why this repository offers a different way: you can define one or
+multiple Seafile libraries that shall be downloaded to a local directory. These
+libraries can belong to the same or a different user, and even on different
+Seafile servers!
+
+## Features
+
+* Download/sync defined libraries in customisable intervals
+* De-sync libaries immediately after they have been downloaded to avoid sync
+  errors
+* Allow to force-re-sync a library even if its re-sync interval hasn't reached
+  yet
+* Extensive informative and error logging
+* Created with automation in mind so you can run it in cronjobs or systemd
+  triggers
+* Deal with the numerous caveats of `seaf-cli` and Seafile in general
+
+
+## Install
+
+The tool depends on the following applications:
+* `Python 3` and its library `yaml`
+* [`seafile-cli`](https://help.seafile.com/syncing_client/linux-cli/), available e.g. in [Debian](https://packages.debian.org/bullseye/seafile-cli)
+
+You can execute the tool with `python3 seafile_mirror.py`. The `--help` flag
+informs you about the required and available commands.
+
+There is also an [Ansible
+role](https://src.mehl.mx/mxmehl/seafile-mirror-ansible) that takes care of
+installing the tool, setting up a systemd service, and running it daily.
+
+To keep the Seafile daemon that is required for `seafile-cli` running in the background, check out this [exemplary systemd service](examples/seaf-daemon.service).
+
+## Configuration
+
+Configuration is done in a YAML file called `seafile_mirror.conf.yaml`. You can find an example [here](examples/seafile_mirror.conf.yaml).
+
+If that configuration file resides in the same location as the `seafile_mirror.py` file you are running, you should provide `--configdir ./`.
+
+## Logging and caching
+
+The tool creates `seafile_mirror.log` in addition to the log to the standard
+output. With `-v` you can print DEBUG messages that will help you in case of
+problems.
+
+It also caches the current status of synced libraries and their latest full
+download in the file `.seafile_mirror.db.json`. Do not delete this file unless
+you don't mind that the tool will re-sync all libraries in the next run.

examples/seaf-daemon.service

@@ -0,0 +1,18 @@
+[Unit]
+Description=Seafile Daemon
+After=network.target
+After=nfs-client.target
+StartLimitIntervalSec=60
+StartLimitBurst=3
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/seaf-daemon -c /home/seafile/.ccnet -d /home/seafile/config/seafile-data -w /home/seafile/config/seafile
+Restart=always
+RestartSec=10
+# Restart every day
+RuntimeMaxSec=1d
+SyslogIdentifier=seaf-daemon
+
+[Install]
+WantedBy=default.target

examples/seafile_mirror.conf.yaml

@@ -0,0 +1,18 @@
+# Example configuration file for seafile-mirror
+- server: https://my-seafile-server.tld
+  user: user@example.com
+  password: mysecretpassword
+  # The default resync interval
+  resync_interval_days: 7
+  # Define the libraries which shall be synced
+  libs:
+  - name: Documents
+    # ID of the Seafile library (can be seen in the web UI)
+    id: 53976f13-9d24-4d4a-967b-efb598d542ea
+    # local directory where the mirror shall be created
+    dir: /backup/Documents
+  - name: Pictures
+    id: 12346f13-9d24-4d4a-1234-efb598d555fa
+    dir: /backup/Pictures
+    # A library-specific resync interval
+    resync_interval_days: 31