Nextcloud Time Archive App

Time Archive archives files or complete folders based on age. Archived items are moved through the official Nextcloud Files API into a configurable destination folder. That destination can be a normal folder, a subfolder, or an external storage mount such as an S3 bucket mounted in Nextcloud.

Features

• File Archive mode: Archive individual files using the existing Time Archive behavior.
• Folder Archive mode: Archive complete direct child folders only when every file inside the folder is older than the configured age limit.
• Configurable destination: Store archived items in any folder path visible in Nextcloud Files, including external storage mounts.
• S3-compatible target: Use an S3 external storage mount as the archive destination.
• Dry Run: Log planned moves and skips without changing files or folders.
• Path filters: Limit archiving to configured source folders or exclude paths globally.
• User exclusions: Skip configured user IDs.
• Nextcloud-native moves: All moves use Nextcloud's Files API, preserving storage backend behavior, file cache updates, events, permissions and activities.

Installation

Prerequisites

• Nextcloud 28-34
• PHP 8.2 or higher
• Node.js 24+ and npm 11+ for building frontend assets
• Composer for PHP dependencies

Manual Installation

1. Clone or download the app:

cd /path/to/nextcloud/apps
git clone https://github.com/mdhemmi/time_archive.git

2. Install PHP dependencies:

cd time_archive
composer install --no-dev

3. Install and build frontend assets:

npm ci
npm run build

4. Enable the app:

php occ app:enable time_archive
php occ upgrade

Usage

Go to Settings -> Administration -> Workflow -> Time Archive.

1. Choose File Archive or Folder Archive.
2. Set the Archive destination folder.
3. Configure optional include paths, exclude paths and excluded users.
4. Enable Dry Run for the first run if you want to verify decisions without moving anything.
5. Create an archive rule with the desired age threshold.
6. Use Run archive now or wait for the scheduled background job.

Archive rule configuration is restricted to administrators. Regular users can view archived items through the Archive view or directly through the configured destination folder in Files, if they have access to it.

Archive Destination

The archive destination is a path relative to each user's Nextcloud Files root. Do not use absolute filesystem paths, shell paths, data-directory paths or S3 bucket URLs.

Examples:

.archive
Archive
S3-Archive
External/S3-Archive

The setting is stored as archive_folder_path:

php occ config:app:set time_archive archive_folder_path --value "S3-Archive"

If the destination path does not exist, the app attempts to create it through the Nextcloud Files API. For external storage, create the mount in Nextcloud first and use the mount name that users see in Files.

S3 Destination

To archive into S3, configure S3 as a Nextcloud external storage mount first.

Recommended setup:

1. In Nextcloud, create an external storage mount backed by S3.
2. Give the mount a clear visible name, for example S3-Archive.
3. Grant create, update and delete permissions to every user that Time Archive should process.
4. Configure Time Archive to use that mount:

php occ config:app:set time_archive archive_folder_path --value "S3-Archive"

5. Enable Dry Run and trigger a manual archive run.
6. Check the Nextcloud logs to confirm the planned target paths.
7. Disable Dry Run when the target paths are correct.

The app does not talk to S3 directly. Nextcloud handles the external storage backend.

Archive Modes

File Archive

File Archive is the existing behavior. Files matching the configured age rule are moved individually to the configured archive destination. Existing include and exclude path filters still apply.

Folder Archive

Folder Archive never moves individual files out of a folder.

For each configured source folder, the app checks only direct child folders as archive candidates. A candidate folder is moved only when all files inside it are older than the configured age limit.

Decision rules:

• If every contained file is old enough, the complete folder is moved to <archive destination>/<folder name>.
• If any contained file is too new, the folder is left unchanged.
• As soon as a too-new file is found, checking that folder stops.
• Empty candidate folders are skipped.
• Empty subfolders inside an eligible folder are moved together with the complete folder.
• If the target folder already exists, the candidate is skipped.
• Folder Archive does not merge folders, overwrite folders or create renamed alternatives.

Folder Archive uses file modification times provided by Nextcloud. It does not inspect EXIF data, media metadata, file contents or external metadata.

Tag-based archive rules are skipped while Folder Archive mode is enabled because tags identify individual objects, not source folders.

Source Path Filters

Include and exclude paths are relative to each user's Files root.

If Only archive from these paths is empty, the user's Files root is used as the source.

If include paths are configured, each include path is treated as a source folder. For example:

include path: Photos
candidate:    Photos/Trip 2018
target:       S3-Archive/Trip 2018

Exclude paths prevent traversal and archiving below matching paths.

Dry Run

Dry Run is stored as dry_run:

php occ config:app:set time_archive dry_run --value "1"
php occ config:app:set time_archive dry_run --value "0"

When Dry Run is enabled, Time Archive evaluates all rules and logs what it would move or skip, but it does not create folders or move items.

Other Configuration

Archive mode:

php occ config:app:set time_archive archive_mode --value "file"
php occ config:app:set time_archive archive_mode --value "folder"

If no archive mode is configured, file is used for backward compatibility.

Protected folders:

php occ config:app:set time_archive protected_folders --value "MyCustomFolder,AnotherFolder"

Default protected top-level folders include Camera, Photos, Documents, Screenshots, Videos, Downloads, DCIM, Pictures, Images and SofortUpload.

Viewing Archived Items

Archived items can be opened through:

• The Time Archive app view: https://your-nextcloud.com/index.php/apps/time_archive/
• The Files app by navigating to the configured archive destination, for example /S3-Archive
• The floating Archive button shown in the Files app

Development

composer install
npm ci
npm run dev
npm run build
npm run watch

Building and Releasing

For release instructions, see BUILD_AND_RELEASE.md.

Quick start:

1. Update version in appinfo/info.xml.
2. Build with composer install --no-dev && npm ci && npm run build.
3. Create the archive.
4. Sign the app.
5. Upload it to the Nextcloud App Store.

License

AGPL-3.0-or-later