Skip to content

docs(admin): document the cleanup of old file versions - #1222

Open
pbleser-oc wants to merge 3 commits into
opencloud-eu:mainfrom
pbleser-oc:feat/1419-revisions-cleanup
Open

pbleser-oc wants to merge 3 commits into
opencloud-eu:mainfrom
pbleser-oc:feat/1419-revisions-cleanup

Conversation

@pbleser-oc

@pbleser-oc pbleser-oc commented Oct 21, 2026 •

Copy link
Copy Markdown
Member

Documents the cleanup of old file versions for administrators: opencloud-eu/opencloud#1419, implemented in opencloud-eu/reva#895 and opencloud-eu/opencloud#3778.

Merge after opencloud-eu/opencloud#3778, as it documents its configuration and its command. opencloud-eu/reva#895 is merged.

What's new

  • A new page, "Cleaning Up Old Versions", in Admin → Configuration → Storage (docs/admin/configuration/storage/revisions-cleanup.md):
    • what the cleanup does, and when it runs (uploads, restores, changes on disk with PosixFS);
    • how to turn it on, with OpenCloud Compose (a compose file of one's own added to COMPOSE_FILE, so that the setting survives updates) and with other installations;
    • the strategies, explained one by one with the same example file throughout, so that the effect of each one can be compared: a number of versions, a duration, counting from midnight, auto, and their combinations, with an overview table and suggestions for common needs;
    • what happens after a restore: the version with the replaced content is kept, whatever the strategy, until the file changes again, so that the restore can be undone;
    • how the age of a version is measured: the time it was created, recorded by the server, not the date of its content that the version list shows, with an example of a document that was left alone for two months, and the estimate for versions created by an earlier version of OpenCloud;
    • trying out a strategy with a dry run, the background workers, and the logs.
  • The command to clean up versions on demand, opencloud storage-users revisions cleanup, in Admin → Maintenance → Maintenance Commands: when to use it, a dry run first, selecting the files, choosing the strategy, reading the output, a nightly cron job with a timeout, the exit codes, and how it differs from the older opencloud revisions purge. Also:
    • the shared file metadata cache: the command refuses to delete versions while each process keeps a cache of its own (memory, the default, or ocmem), as lists of versions that are already open would keep showing the deleted ones. The page explains the effect, shows the error, how to share the cache with STORAGE_USERS_FILEMETADATA_CACHE_STORE=nats-js-kv (also in the OpenCloud Compose example of the configuration page), when --allow-local-cache is acceptable, and that a dry run always keeps a cache of its own;
    • the same settings as the server: docker compose exec passes the container's environment, but without containers, Environment= lines of a systemd unit don't reach a command run from a shell or cron. The page recommends an environment file (EnvironmentFile=) and shows how to load it for the command, also in a crontab example.
  • Features and FAQ: the statements that every version can always be restored now say that versions are kept by default, and that administrators can have old ones deleted, with a link to the new page.

The environment variables (OC_REVISIONS_CLEANUP_*) and the storage-users README section reach the Dev section automatically with the next env var update, once opencloud-eu/opencloud#3778 is merged. The new page links to the generated environment variables page.

Checks

pnpm build --locale en passes, without broken links or anchors on these pages. prettier --check and markdownlint-cli2 pass for the changed files.

OpenCloud can now delete old file versions according to a cleanup
strategy (opencloud-eu/opencloud#1419, opencloud-eu/opencloud#3778).

- a new page, Cleaning Up Old Versions, in the storage configuration:
  what the cleanup does and when it runs, how to turn it on with
  OpenCloud Compose and other installations, the strategies explained
  with one example file throughout, how the age of a version is
  measured, how to try a strategy out, the background workers and the
  logs
- the command to clean up versions on demand, in the maintenance
  commands: a dry run first, selecting the files, choosing the
  strategy, the output, a nightly cron job with a timeout, the exit
  codes, and what to know when it runs while OpenCloud is running
  (the user to run it as, versions in an open Versions panel, NATS for
  PosixFS)
- features and FAQ: versions are kept by default, administrators can
  have old ones deleted
…anup command

- After a restore, the version with the replaced content is kept until
  the file changes again, whatever the strategy.
- The cleanup command refuses to delete versions while each process
  keeps its own file metadata cache (the default), and says how to
  share it with STORAGE_USERS_FILEMETADATA_CACHE_STORE=nats-js-kv;
  --allow-local-cache runs it anyway. A dry run uses a cache of its own.
- Without containers, the command needs the same environment as the
  server: load the environment file of a systemd unit for it, also in
  the cron example.

Assisted-by: Claude Code:claude-opus-5-5
@pbleser-oc
pbleser-oc force-pushed the feat/1419-revisions-cleanup branch from da0ef73 to 0077732 Compare November 18, 2026 22:02
The cleanup goes by the time a version was created, recorded by the
server, no longer by the date of its content, which clients choose:

- "How Old Is a Version?" explains the creation time, how it differs
  from the date in the version list, why versions dated in the future
  can't push out the newest ones, and the estimate for versions created
  by an earlier version of OpenCloud.
- "auto" keeps the oldest version of each slot, with the reason why.
- The example file lists when its versions were created, and the
  examples for "30d", "5, 30d" and the restore exception follow suit.
- The verbose output shows the time a version was created.

Assisted-by: Claude Code:claude-opus-5-5
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant