From 8fcbd3979cee6c952526e5e8eb0bf80984b0890b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ren=C3=A9=20Bachmann?= <r.bachmann@bahmcloud.de>
Date: Wed, 14 Jan 2026 10:10:09 +0100
Subject: [PATCH] Revise README for ownCloud Backup integration

Expanded README with detailed features, installation instructions, configuration steps, and troubleshooting tips.
---
 README.md | 134 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 132 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 4f7760f..1ab3d93 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,132 @@
-# owncloud-backup-ha
-Home Assistant custom integration that adds ownCloud (Classic/Server) as a Backup Location / Backup Agent using the official WebDAV interface.
+# Owncloud Backup Homeassistant by René Bachmann
+
+Home Assistant custom integration that adds **ownCloud (Classic/Server)** as a **Backup Location / Backup Agent** using the official **WebDAV** interface.
+
+This integration allows you to:
+- store Home Assistant backups in ownCloud via WebDAV
+- list backups stored in ownCloud from within the Home Assistant UI
+- download and **restore** backups via the Home Assistant UI
+- authenticate using **either** an ownCloud **App Password** (recommended for 2FA) **or** the regular account password
+
+> **Status:** `0.1.0-alpha`  
+> This is an early alpha release. Please test on a non-critical system first.
+
+---
+
+## Features
+
+- ✅ Home Assistant **Backup Agent** implementation (Backup Location)
+- ✅ **Upload** backups to ownCloud via WebDAV
+- ✅ **List** backups from ownCloud in HA UI
+- ✅ **Download / Restore** backups via HA UI (streaming download)
+- ✅ **Delete** backups from ownCloud
+- ✅ Automatic DAV endpoint detection for ownCloud Classic:
+  - `/remote.php/dav/files/<user>/`
+  - `/remote.php/webdav/`
+- ✅ Metadata sidecar (`.json`) for reliable listing + fallback when metadata is missing
+- ✅ Supports **App Password** and **standard login**
+- ✅ English UI & documentation
+- ✅ HACS-ready repository structure
+
+---
+
+## Requirements
+
+- Home Assistant version that supports the modern Backup system with backup agents (2025.x+).
+- ownCloud Classic / Server with WebDAV enabled (default in ownCloud).
+
+---
+
+## Installation (HACS)
+
+### Add as a custom repository
+1. In Home Assistant: **HACS → Integrations → ⋮ → Custom repositories**
+2. Add your repository URL
+3. Category: **Integration**
+4. Install **owncloud-backup-ha**
+5. Restart Home Assistant
+
+> This repository includes a `hacs.json` and follows the required `custom_components/` layout.
+
+---
+
+## Installation (Manual)
+
+1. Copy the folder `custom_components/owncloud_backup/` into your Home Assistant config directory:
+   - `<config>/custom_components/owncloud_backup/`
+2. Restart Home Assistant.
+
+---
+
+## Configuration
+
+1. In Home Assistant, go to:
+   - **Settings → Devices & services → Add integration**
+2. Search for:
+   - **ownCloud Backup (WebDAV)**
+3. Enter:
+   - **Base URL** (example: `https://cloud.example.com`)
+   - **Username**
+   - **Password / App Password**
+   - **Backup folder path** (default: `/HomeAssistant/Backups`)
+   - **Verify SSL** (default: enabled)
+
+### Recommended authentication
+- If you use **2FA**, create an **App Password** and use it as the "Password" field.
+- If you do **not** use 2FA, your standard login password should also work.
+
+---
+
+## How backups are stored in ownCloud
+
+The integration uploads:
+- the backup tarball: `ha_backup_<backup_id>.tar`
+- a metadata file: `ha_backup_<backup_id>.json`
+
+The JSON metadata enables reliable listing and display in the HA UI.
+
+If the JSON metadata is missing (e.g., you manually copied a `.tar`), the integration will still try to show the backup using WebDAV file properties (size + last modified time) as a fallback.
+
+---
+
+## Restore workflow (UI)
+
+1. **Settings → System → Backups**
+2. Select a backup from the ownCloud location
+3. Choose **Restore**
+
+Home Assistant will download the `.tar` from ownCloud using the Backup Agent API (streaming).
+
+---
+
+## Troubleshooting
+
+### "Cannot connect"
+- Check your **Base URL**
+- Make sure the ownCloud user can access WebDAV
+- If you use 2FA, try an **App Password**
+- Verify that your reverse proxy does not block `PROPFIND`, `MKCOL`, or `DELETE`
+
+### SSL / certificate issues
+- If you use a self-signed certificate, either:
+  - install the CA properly, or
+  - temporarily disable **Verify SSL** (not recommended for production)
+
+### Missing backups in list
+- Ensure the configured backup folder is correct
+- Check that ownCloud contains either:
+  - `.json` metadata files (preferred), or
+  - `.tar` files (fallback)
+
+---
+
+## Security notes
+
+- Credentials are stored in Home Assistant config entry storage.
+- Prefer **App Passwords** over your main login password, especially with 2FA enabled.
+
+---
+
+## Development notes
+
+This integration intentionally does not depend on external Python packages to keep deployment simple.