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, orreferences. Search accepts filename/path text and an optionaldocumentIdfor imported source references.getaccepts an ID or legacy path, optionally pinned to a Git commit. Pagination usespageandlimit(maximum 50).POST /v1/eve-content/media/upload: original binary body,Content-Type: application/octet-stream, URL-encodedX-Eve-Filename, and a UUIDIdempotency-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 relativedownloadPathto 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:
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:
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.