Skip to content

MetaVox Installation Guide

This guide covers installing and configuring MetaVox for your Nextcloud instance.

Requirements

Required

Dependency Why
Nextcloud 31+ (tested up to 33) Platform
Group Folders app MetaVox adds metadata to Team Folders — without Group Folders there are no Team Folders
Administrator access Field definitions and app settings require admin rights
Dependency Why Without it
Redis MetaVox uses Redis for metadata caching (30s TTL), field definition caching (600s TTL), presence tracking, and cell locking MetaVox still works but falls back to APCu (local cache, not shared across PHP workers). Cell locking and presence tracking are disabled. Performance with multiple concurrent users is reduced

Optional

Dependency Why Without it
notify_push app Enables real-time metadata sync between users. When one user edits metadata, all other users see the change instantly via WebSocket Users must manually refresh to see other users' changes. Cell locking indicators are not shown. Last-write-wins applies for concurrent edits
Nextcloud AI provider (e.g. LLM2) Powers the AI Autofill feature that suggests metadata values based on file content AI Autofill button does not appear. All other features work normally

Feature Availability

Feature Base install + Redis + Redis + notify_push
Metadata fields & editing Yes Yes Yes
Inline grid editing Yes Yes Yes
Bulk editing & CSV export Yes Yes Yes
Filter & sort Yes Yes Yes
Flow integration Yes Yes Yes
Backup & restore Yes Yes Yes
Metadata caching (performance) APCu only Distributed Distributed
Cell locking (prevent conflicts) No No Yes
Presence tracking No No Yes
Real-time sync (live updates) No No Yes

Installation

  1. Log in as administrator
  2. Go to Apps (click your profile icon > Apps)
  3. Search for "MetaVox" in the search bar
  4. Click Download and enable

Manual Installation

  1. Download the latest release from GitHub
  2. Extract to nextcloud/apps/metavox
  3. Go to Apps and enable MetaVox

Initial Configuration

After installation:

  1. Go to Settings > MetaVox
  2. You'll see two tabs:
  3. Team folder Metadata - Define fields for Team folders
  4. Document Metadata - Define fields for individual documents

Setting Up Team Folder Metadata

  1. Select a Team folder from the dropdown
  2. Click Add Field to create a new metadata field
  3. Configure the field:
  4. Field Name: Internal identifier (lowercase, no spaces)
  5. Field Label: Display name shown to users
  6. Field Type: Text, select, date, etc.
  7. Description: Help text for users
  8. Required: Whether the field must be filled in
  9. Options: For dropdown fields, comma-separated values

Team folder metadata setup

Once configured, the team folder metadata fields appear directly in the Nextcloud sidebar when someone selects the team folder — admins see an editable panel, end users see a read-only view (depending on configuration).

Team folder metadata in the Nextcloud sidebar

Setting Up Document Metadata

Document metadata fields are configured similarly but apply to individual files rather than the whole folder.

Import/Export

Importing Field Definitions

  1. Go to Settings > MetaVox > Team folder Metadata
  2. Click Select JSON File under "Import & Export"
  3. Select your JSON file
  4. Review the preview and confirm

Exporting Field Definitions

  1. Configure your fields as desired
  2. Click Export to download the JSON file
  3. Use this file to replicate settings on other instances

Using Compliance Templates

MetaVox includes ready-to-use templates for Dutch government compliance:

Template Purpose
avg-compliance.json GDPR personal data classification
woo-compliance.json Open Government Act (WOO) publication status
archiefwet-compliance.json Archives Act retention periods
overheid-compleet.json Combined compliance fields

Templates are located in /templates/compliance/. See Compliance Templates for details.

Updating MetaVox

  1. Go to Apps
  2. Find MetaVox in your installed apps
  3. Click Update if available

Or update manually by replacing the app folder with the new version.

Troubleshooting

MetaVox section not showing

  • Ensure you're viewing a file in a Team folder (not a personal folder)
  • Check that the Team folder has metadata fields configured
  • Verify the user has at least read access to the folder

Cannot edit metadata

  • User needs edit permissions on the document
  • Check user permissions — view, edit, and manage-fields are separate permission levels
  • Check if fields are defined for this Team folder

Import fails

  • Verify JSON format is correct
  • Check for duplicate field names
  • Ensure field types are valid

MetaVox settings not visible

  • Verify MetaVox is enabled in Apps
  • Clear browser cache and reload the page
  • Check Nextcloud logs for errors related to MetaVox

Next Steps