# Owncloud Backup Homeassistant

[![Latest Release](https://img.shields.io/github/v/release/bahmcloud/owncloud-backup-ha?style=flat-square)](https://github.com/bahmcloud/owncloud-backup-ha/releases)
[![HACS](https://img.shields.io/badge/HACS-Custom-orange.svg?style=flat-square)](https://hacs.xyz/)
[![License](https://img.shields.io/github/license/bahmcloud/owncloud-backup-ha?style=flat-square)](LICENSE)

[![Add to Home Assistant](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=owncloud_backup)

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.2.0`  
> This release focuses on reliability and compatibility across Home Assistant versions.

---

## 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

### Upload reliability (important)
To improve reliability behind reverse proxies and avoid WebDAV timeouts with chunked uploads,
the integration **spools the backup to a temporary file** and then uploads it with a proper
**Content-Length** header.

### Home Assistant compatibility
Home Assistant has evolved its backup metadata schema over time. This integration normalizes
backup metadata keys to remain compatible across multiple Home Assistant versions.

---

## 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

### "Upload failed" / HTTP 504 (Gateway Timeout)
A 504 typically indicates a reverse proxy / gateway timeout (e.g., Nginx/Traefik/Cloudflare).
This integration uploads with Content-Length (non-chunked) for better compatibility.

If you still see 504:
- Increase proxy timeouts (e.g. `proxy_read_timeout`, `proxy_send_timeout` in Nginx)
- Ensure large uploads are allowed (`client_max_body_size` in Nginx)
- Avoid buffering restrictions for WebDAV endpoints

### "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)

---

## 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.