# How to Set Up Nextcloud Upload with Automatic Directory Creation for iCloud Photos

> Easily set up Nextcloud upload for iCloud photos with automatic directory creation. This Docker container mirrors your photo structure by detecting changes and creating remote folders for seamless syncing. Configure with just f...

- Repository: [boredazfcuk/docker-icloudpd](https://github.com/boredazfcuk/docker-icloudpd)
- Tags: how-to-guide
- Published: 2026-02-26

---

**The docker-icloudpd container automatically mirrors your local iCloud photo directory structure to Nextcloud by detecting file changes, creating remote folders via WebDAV MKCOL requests, and uploading content—requiring only five environment variables to enable.**

The boredazfcuk/docker-icloudpd container downloads photos from Apple's iCloud service and can synchronise them to a Nextcloud server while preserving your folder hierarchy. Setting up Nextcloud upload with automatic directory creation involves configuring environment variables that trigger WebDAV-based directory provisioning and file streaming. This guide explains the underlying mechanics based on the actual shell script implementation and provides a complete configuration reference.

## How the Automatic Nextcloud Upload Works

The synchronisation logic resides in [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) and executes a three-stage pipeline whenever the `nextcloud_upload` flag is set to **true**【`sync‑icloud.sh` line 166‑170】.

### Stage 1: Detecting File Changes

The script monitors `/tmp/icloudpd/icloudpd_sync.log` for lines containing *"Downloaded /"* or *"Deleted /"* to identify new or removed assets【`sync‑icloud.sh` line 1271‑1275】. It extracts the relative file paths from these log entries to determine exactly which items need processing.

### Stage 2: Creating Remote Directories

Before uploading files, the **`nextlcoud_create_directories`** function ensures the remote folder hierarchy exists:

- It parses unique sub-paths from the download log to build the required directory tree【`sync‑icloud.sh` line 1235‑1241】.
- Each path is URL-encoded for safe WebDAV transmission【`sync‑icloud.sh` line 1243‑1246】.
- The function probes each remote directory with `curl`; if the HTTP response is not 2xx, it issues a `MKCOL` request to create the missing folder【`sync‑icloud.sh` line 1249‑1264】.

This guarantees that structures like `2022/12/25` are replicated exactly on the Nextcloud server without manual intervention.

### Stage 3: Uploading Files

Once directories exist, the **`nextcloud_upload`** function streams each file (and its associated JPEG version if applicable) to the corresponding WebDAV endpoint using `curl`【`sync‑icloud.sh` line 1296‑1332】. The upload targets the `nextcloud_target_dir` root with the preserved sub-folder hierarchy appended.

## Required Configuration

To activate automatic Nextcloud upload, you must populate specific variables in [`/config/icloudpd.conf`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//config/icloudpd.conf) or inject them as environment variables when creating the container.

### Mandatory Environment Variables

Set the following five variables to enable the integration:

- **`nextcloud_upload`**: Set to `true` to enable the upload workflow【[`CONFIGURATION.md`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/CONFIGURATION.md) line 1225】.
- **`nextcloud_url`**: The base URL of your Nextcloud instance (e.g., `https://cloud.example.com`)【[`CONFIGURATION.md`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/CONFIGURATION.md) line 1223】.
- **`nextcloud_username`**: Your Nextcloud account username【[`CONFIGURATION.md`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/CONFIGURATION.md) line 1229】.
- **`nextcloud_password`**: Your Nextcloud account password or app-specific token【[`CONFIGURATION.md`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/CONFIGURATION.md) line 1230】.
- **`nextcloud_target_dir`**: The root folder inside Nextcloud where photos will reside (e.g., `Photos`). **Note:** You cannot upload to the absolute root of Nextcloud; a sub-folder is mandatory【[`CONFIGURATION.md`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/CONFIGURATION.md) line 1225‑1226】.

### Optional Settings

- **`nextcloud_delete`**: Set to `true` to mirror local deletions to Nextcloud, removing files from the remote server when they are deleted locally【[`CONFIGURATION.md`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/CONFIGURATION.md) line 1221】.
- **`folder_structure`**: Defines the local directory pattern (e.g., `{:%Y/%m/%d}`). The same hierarchy will be reproduced in Nextcloud because the directory-creation step uses the exact relative paths from the log【[`CONFIGURATION.md`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/CONFIGURATION.md) line 36】.

## Step-by-Step Setup Guide

Follow these steps to configure the container for automatic Nextcloud upload with directory creation:

1. **Prepare the host volume.** Create a sentinel file named `.mounted` in your host bind-mount directory (e.g., `/home/joe/iCloud/.mounted`). Without this file, the sync loop exits immediately as a failsafe measure.

2. **Define the target directory.** Decide on a root folder name in Nextcloud (such as `Photos`). Remember that uploads cannot occur at the Nextcloud root level.

3. **Configure variables.** Set `nextcloud_upload=true` and provide `nextcloud_url`, `nextcloud_username`, `nextcloud_password`, and `nextcloud_target_dir` via environment variables or edit [`/config/icloudpd.conf`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//config/icloudpd.conf) after the first run.

4. **Enable deletion sync (optional).** If you want remote files deleted when local copies are removed, set `nextcloud_delete=true`.

5. **Start the container.** On initialization, the script runs `check_nextcloud_connectivity` to verify it can reach the WebDAV endpoint (expecting HTTP 200)【`sync‑icloud.sh` line 1179‑1182】. If successful, subsequent sync cycles will automatically create directories and upload files.

## Docker Compose Example

Use the following [`docker-compose.yml`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/docker-compose.yml) configuration to deploy the container with Nextcloud integration enabled:

```yaml
version: "3.8"
services:
  icloudpd:
    image: boredazfcuk/icloudpd
    container_name: icloudpd
    restart: always
    environment:
      TZ: Europe/London
      apple_id: "my@email.com"
      download_path: "/home/joe/iCloud"
      folder_structure: "{:%Y/%m/%d}"
      # Nextcloud integration

      nextcloud_upload: "true"
      nextcloud_url: "https://cloud.example.com"
      nextcloud_username: "myuser"
      nextcloud_password: "mysecret"
      nextcloud_target_dir: "Photos"
      # Optional deletion sync

      # nextcloud_delete: "true"

    volumes:
      - icloudpd_config:/config
      - /home/joe/iCloud:/home/joe/iCloud
volumes:
  icloudpd_config:

```

Ensure you create the `.mounted` file on the host before starting:

```bash
touch /home/joe/iCloud/.mounted

```

## Configuration File Reference

After the first run, the container generates [`/config/icloudpd.conf`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//config/icloudpd.conf). You can edit this file directly to adjust Nextcloud settings:

```ini
apple_id = my@email.com
download_path = /home/joe/iCloud
folder_structure = {:%Y/%m/%d}

# Nextcloud settings

nextcloud_upload = true
nextcloud_url = https://cloud.example.com
nextcloud_username = myuser
nextcloud_password = mysecret
nextcloud_target_dir = Photos
nextcloud_delete = false

```

## Summary

- The **`nextlcoud_create_directories`** function in [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) automatically provisions the remote folder structure using WebDAV `MKCOL` requests before any files are transferred.
- You must set `nextcloud_upload=true` and provide valid credentials plus a `nextcloud_target_dir` (sub-folder) to enable the integration.
- The script parses `/tmp/icloudpd/icloudpd_sync.log` to detect new files and determine which directories need creation.
- A sentinel file named `.mounted` must exist in the host download directory to allow the sync loop to run.
- Optional deletion syncing via `nextcloud_delete=true` ensures the remote server mirrors local removals.

## Frequently Asked Questions

### Does the script create the directory structure automatically on Nextcloud?

Yes. The **`nextlcoud_create_directories`** function extracts unique sub-paths from the download log and issues WebDAV `MKCOL` requests for any missing directories【`sync‑icloud.sh` line 1249‑1264】. This ensures your local folder hierarchy (e.g., `2024/06/15`) is replicated exactly on the Nextcloud server without manual creation.

### What happens if I don't set nextcloud_target_dir?

The upload will fail. According to the configuration documentation, `nextcloud_target_dir` is mandatory and must specify a sub-folder within Nextcloud (such as `Photos` or `iCloudBackup`). The script cannot upload files to the absolute root of the Nextcloud storage【[`CONFIGURATION.md`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/CONFIGURATION.md) line 1225‑1226】.

### Can I sync deletions from iCloud to Nextcloud?

Yes. Set `nextcloud_delete=true` in your configuration. When enabled, the script parses the sync log for *"Deleted /"* entries and removes the corresponding files from the Nextcloud server via WebDAV DELETE requests, keeping the remote directory in sync with local deletions【[`CONFIGURATION.md`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/CONFIGURATION.md) line 1221】.

### Why is the .mounted file required?

The `.mounted` file acts as a failsafe sentinel. The script checks for the existence of `/home/<user>/iCloud/.mounted` before proceeding with any synchronisation. If this file is absent, the sync loop exits early to prevent data loss or errors when the host volume is not properly mounted. Create this file with `touch` on your host system before starting the container.