Eve library

Eve media

Other

Revision 1

On this page

Eve stores media metadata, source aliases and import manifests in the environment's Payload PostgreSQL database. Original bytes live in the private Hetzner bucket app-dev-server, under eve/content/<environment>/media/. Payload, Lexical and the AWS SDK are open source; this path requires no paid CMS module.

Each SHA-256-addressed original has an objects/ copy and a recovery/ copy. Uploads use conditional writes and read back both bodies before committing their metadata. A failed database transaction can leave an immutable orphan; retrying verifies the same objects and safely records the result. These two prefixes are in the same bucket. PostgreSQL history and aliases use the existing pgBackRest backup and continuous WAL archive.

The human workspace has a searchable media library, raster/audio previews, original downloads, and an attachment picker in the rich-text editor. SVG, PDF and other active file formats download as attachments with sandbox/nosniff headers. Editable diagram files retain their original bytes. Mermaid documents also have the existing source editor and strict preview.

Worker API and MCP#

Use the same scoped Eve worker credential as the task/document API. Readers need content:read; uploads additionally need content:write. Send the bearer token in the Authorization header, never in a URL. Human sessions use the equivalent reader/editor roles and same-origin checks.

  • POST /v1/eve-content/media/query: search, get, sources, or references. Search accepts filename/path text and an optional documentId for imported source references. get accepts an ID or legacy path, optionally pinned to a Git commit. Pagination uses page and limit (maximum 50).
  • POST /v1/eve-content/media/upload: original binary body, Content-Type: application/octet-stream, URL-encoded X-Eve-Filename, and a UUID Idempotency-Key. Preserve the key and identical bytes/filename after a lost response. Files must contain 1 byte to 32 MiB.
  • GET /v1/eve-content/media/<id>/file: authenticated original download with single byte-range support. Query responses provide a relative downloadPath to append to the content API prefix.
  • MCP eve_media_query: the same bounded metadata, alias and reference reads. Binary uploads/downloads use the HTTP endpoints.

Document attachment links are preserved inside immutable document revisions. The source-reference query describes imported links; extracting relations from newly authored revisions remains part of the document-relations cutover.

Migration and recovery#

Run operator commands with the repository's pinned Node installation. Storage configuration stays in mode-0600 files outside Git. Configure each environment only after its separate CMS database/operator configuration exists:

sh
python3 infra/hetzner/eve/provision-media-storage.py --environment dev
node tools/eve-content/inventory-media.mjs --root . \
  --documents /private/document-manifest.json --out /private/media-manifest.json
python3 infra/hetzner/eve/import-media.py --source . --environment dev \
  --node /root/.nvm/versions/node/v24.14.1/bin/node \
  --manifest /private/media-manifest.json --report /private/media-import.json

The inventory reads the frozen Git commit, resolves document-owned media, and preserves presentation assets, narration and verification images. Operational application assets and fixtures remain in Git. Referenced LFS objects require the exact checksum-verified original; a pointer is never imported as an image. Unresolved references remain visible in the manifest for reconciliation.

The importer is resumable. Choose a new report path for each attempt. An import is marked verified only after every alias is read back and every unique primary and recovery body matches its checksum. The complete manifest is also stored in PostgreSQL so recovery does not depend on a surviving checkout.

After the import completes, take a PostgreSQL backup, then extend the existing isolated restore drill with:

sh
python3 infra/hetzner/eve/restore-drill.py --require-api --source . \
  --node /root/.nvm/versions/node/v24.14.1/bin/node \
  --content-manifest /private/document-manifest.json \
  --content-report /private/restored-content.json \
  --media-manifest-hash <verified-media-manifest-sha256> \
  --media-report /private/restored-media.json

The drill checks the restored manifest, every alias and document reference, and every recovery object body, without using the primary media objects. It stops and removes only its own temporary PostgreSQL cluster. Media/source retirement remains forbidden until consumer conversion and final reconciliation pass.