Update README with basic examples.

README.md

@@ -1 +1,101 @@
 # docker-volume-backup-companion
+
+Docker image for performing simple backups of Docker volumes. Main features:
+
+- Mount volumes into the container, and they'll get backed up
+- Use full `cron` expressions for scheduling the backups
+- Backs up to local disk, AWS S3, or both
+- Optionally stops other containers for the duration of the backup, and starts them again afterward, to ensure consistent backups of things like database files, etc
+
+## Examples
+
+### Backing up locally
+
+Say you're running some dashboards with [Grafana](https://grafana.com/) and want to back them up:
+
+```yml
+version: "3"
+
+services:
+  dashboard:
+    image: grafana/grafana:5.3.4
+    volumes:
+      - grafana-data:/var/lib/grafana           # This is where Grafana keeps its data
+
+  backup:
+    image: futurice/docker-volume-backup-companion:TODO
+    environment:
+      BACKUP_SOURCES: /mnt/grafana              # Where to read data from
+      BACKUP_ARCHIVE: /mnt/backups              # Where to write backups to
+    volumes:
+      - grafana-data:/mnt/grafana:ro            # Mount the Grafana data volume (read-only)
+      - ./backups:/mnt/backups                  # Mount a local folder as the backup archive
+
+volumes:
+  grafana-data:
+```
+
+This will back up the Grafana data volume, once per day, and write it to `./backups` with a filename like `backup-2018-11-26.tar.gz`.
+
+### Backing up to S3
+
+Off-site backups are better, though:
+
+```yml
+version: "3"
+
+services:
+  dashboard:
+    image: grafana/grafana:5.3.4
+    volumes:
+      - grafana-data:/var/lib/grafana           # This is where Grafana keeps its data
+
+  backup:
+    image: futurice/docker-volume-backup-companion:TODO
+    environment:
+      BACKUP_SOURCES: /mnt/grafana              # Where to read data from
+      AWS_S3_BUCKET_NAME: my-backup-bucket      # S3 bucket which you own, and already exists
+      AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}   # Read AWS secrets from environment (or a .env file)
+      AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
+    volumes:
+      - grafana-data:/mnt/grafana:ro            # Mount the Grafana data volume (read-only)
+
+volumes:
+  grafana-data:
+```
+
+This configuration will back up to AWS S3 instead.
+
+### Stopping containers while backing up
+
+It's not generally safe to read files to which other processes might be writing. You may end up with corrupted copies. You generally don't want corrupted backups.
+
+You can give the backup container access to the Docker socket, and label any containers that need to be stopped while the backup runs:
+
+```yml
+version: "3"
+
+services:
+  dashboard:
+    image: grafana/grafana:5.3.4
+    volumes:
+      - grafana-data:/var/lib/grafana           # This is where Grafana keeps its data
+    labels:
+      - "docker-volume-backup-companion.stop-during-backup=true"
+
+  backup:
+    image: futurice/docker-volume-backup-companion:TODO
+    environment:
+      BACKUP_SOURCES: /mnt/grafana              # Where to read data from
+      AWS_S3_BUCKET_NAME: my-backup-bucket      # S3 bucket which you own, and already exists
+      AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}   # Read AWS secrets from environment (or a .env file)
+      AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro # Allow use of the "stop-during-backup" label
+      - grafana-data:/mnt/grafana:ro            # Mount the Grafana data volume (read-only)
+
+volumes:
+  grafana-data:
+```
+
+This configuration allows you to safely back up things like databases, if you can tolerate a bit of downtime.