{"result":{"depiction_url":null,"edges":{"refers":{"objects":[{"created":"2026-11-05T18:43:22Z","object_id":{"id":1902,"is_a":["text","documentation","reference","module"],"name":"doc_module_mod_video","title":"mod_video","uri":"https:\/\/zotonic.com\/id\/1902"},"seq":1000000},{"created":"2026-11-05T18:43:22Z","object_id":{"id":3142,"is_a":["text","documentation","developerguide"],"name":"doc_guide_file_storage","title":"How Zotonic stores and collects media files","uri":"https:\/\/zotonic.com\/id\/3142"},"seq":1000000}],"predicate":{"id":2409,"is_a":["meta","predicate"],"name":"refers","title":{"_type":"trans","tr":{"en":"Refers"}},"uri":"https:\/\/zotonic.com\/id\/refers"}},"subject":{"objects":[{"created":"2026-11-05T18:43:22Z","object_id":{"id":2556,"is_a":["categorization","keyword","keyword_information_type"],"name":"zotonic_topic_explanation","title":"Explanation","uri":"https:\/\/zotonic.com\/id\/2556"},"seq":1},{"created":"2026-11-05T18:43:22Z","object_id":{"id":2564,"is_a":["categorization","keyword","keyword_audience"],"name":"zotonic_topic_backend_developer","title":"Backend developer","uri":"https:\/\/zotonic.com\/id\/2564"},"seq":2},{"created":"2026-11-05T18:43:22Z","object_id":{"id":2566,"is_a":["categorization","keyword","keyword_audience"],"name":"zotonic_topic_operator","title":"Operator","uri":"https:\/\/zotonic.com\/id\/2566"},"seq":3},{"created":"2026-11-05T18:43:22Z","object_id":{"id":2576,"is_a":["categorization","keyword","keyword_domain"],"name":"zotonic_topic_media_management","title":"Media management","uri":"https:\/\/zotonic.com\/id\/2576"},"seq":4},{"created":"2026-11-05T18:43:22Z","object_id":{"id":2581,"is_a":["categorization","keyword","keyword_domain"],"name":"zotonic_topic_file_storage","title":"File storage","uri":"https:\/\/zotonic.com\/id\/2581"},"seq":5},{"created":"2026-11-05T18:43:22Z","object_id":{"id":2599,"is_a":["categorization","keyword","keyword_domain"],"name":"zotonic_topic_api_and_integration","title":"API and integration","uri":"https:\/\/zotonic.com\/id\/2599"},"seq":6}],"predicate":{"id":308,"is_a":["meta","predicate"],"name":"subject","title":{"_type":"trans","tr":{"en":"Keyword"}},"uri":"http:\/\/purl.org\/dc\/elements\/1.1\/subject"}}},"id":3143,"is_a":["text","documentation","developerguide"],"links":[{"rel":"self","target":"https:\/\/zotonic.com\/.zotonic\/websub\/topic\/3143"},{"rel":"hub","target":"https:\/\/zotonic.com\/.zotonic\/websub"}],"medium":null,"medium_url":null,"name":"doc_guide_mediarunner","page_url":{"en":"https:\/\/zotonic.com\/docs\/3143\/running-media-processing-on-a-separate-host","x-default":"https:\/\/zotonic.com\/docs\/3143\/running-media-processing-on-a-separate-host"},"preview_url":null,"resource":{"version":15,"pivot_location_lat":null,"title":"Running media processing on a separate host","is_authoritative":true,"body":"

Running media processing on a separate host<\/h1>\n

Image resizing, PDF previews and video conversion can use considerable CPU, memory\nand temporary disk space. The mediarunner<\/strong> is a dedicated Zotonic site that\nperforms this work for other Zotonic installations. Moving processing to a runner\nlets you size and maintain the processing host separately from the websites.<\/p>\n

The website still owns its media records, access rules and stored files. The\nrunner receives the inputs needed for a job and returns its outputs. Its cache\nhelps avoid repeated transfers and rendering; it is not the website's permanent\nmedia store. See how Zotonic stores files<\/a> for that part.<\/p>\n

The parts of the system<\/h2>\n

\"The<\/p>\n

A runner has a PostgreSQL database for its queue and cache registry, persistent\ndisk for cached inputs and results, and private working directories for commands.\nGeneral jobs and full ffmpeg video conversions have separate worker pools, so a\nlong video conversion need not hold up image previews or video thumbnails.<\/p>\n

On the website, Zotonic's media pipeline chooses the appropriate processing\nprofile automatically. Custom Erlang code uses z_exec:run\/4<\/code> with a profile, a\nsite context, and explicit read<\/code> and write<\/code> paths. Plain z_exec:run\/1,2<\/code> commands\nremain local. See the execution API<\/a> for the profile interface.<\/p>\n

Set up a runner<\/h2>\n
  1. Install the mediarunner site<\/a> under\napps_user\/mediarunner<\/code> in a compatible Zotonic checkout. Use a dedicated host\nor container, with persistent disk and OS or container resource limits.<\/li>
  2. Install the sandbox helper and the required processing tools. Typical installs\nneed ImageMagick, ffmpeg, ffprobe and Ghostscript for PDF processing. Install the\nfonts and ImageMagick policy that your previews require, too.<\/li>
  3. Set the runner hostname, database, TLS and administrator credentials in private\nsite configuration, then enable the site. The supplied site configuration is\ndisabled. Budget disk for both the persistent cache and concurrent job copies.<\/li>
  4. Check z_exec:sandbox_status\/0<\/code> on the runner and the isolation indicator on its\ndashboard. Confirm the actual restrictions on the deployment platform before\naccepting jobs.<\/li>
  5. In the runner dashboard, choose Add website \/ consumer<\/strong>. Store the generated\nOAuth2 bearer key securely; it is shown only once. Use a separate consumer for\neach client installation that should have its own cache access and statistics.<\/li><\/ol>\n

    The runner's deployment documentation<\/a>\nand configuration reference<\/a>\ncover installation commands, capacity limits and container setup.<\/p>\n

    Connect the website<\/h2>\n

    Add these entries to the zotonic<\/code> application section of the client's system\nconfiguration<\/strong>, zotonic.config<\/code>:<\/p>\n

    {media_runner_hostname, <<"media.example.com">>},\n{media_runner_oauth2_key, <<"YOUR-OAUTH2-BEARER-TOKEN">>},\n{media_runner_local_fallback, false}\n<\/code><\/pre>\n
    The hostname can include a port. HTTPS is required, certificates are checked, and\nredirects are refused. Keep the file<\/code> utility installed on the client for local\nMIME detection. Without a configured runner, processing stays local.<\/p>\n
    The runner must also be able to reach the website's canonical HTTPS callback URL.\nBehind a load balancer, route callbacks to the Zotonic node that submitted the\njob<\/strong>: the waiting callback registration belongs to that node. Check the site's\ncanonical hostname and proxy configuration, rather than relying on the hostname\nof an incoming browser request.<\/p>\n
    Allow streaming PUTs and GETs through the runner's reverse proxy. Avoid buffering\nlarge file transfers, and set request-size and timeout limits appropriate for the\nlargest media you accept. The control API and byte transfers use different routes:<\/p>\n
    Traffic<\/th>Route on the runner<\/th><\/tr><\/thead>
    Job submission, status, capabilities and receipt<\/td>\/api\/model\/mediarunner_job\/…<\/code><\/td><\/tr>
    Input uploads<\/td>\/media-runner\/jobs\/files\/:hash<\/code><\/td><\/tr>
    Result downloads<\/td>\/media-runner\/jobs\/results\/:hash<\/code><\/td><\/tr><\/tbody><\/table>\n
    Start with a test image and resized preview, then a small video. Check queue\ncompletion, callback delivery and successful downloads. For several processing\nhosts, use the client runner-pool configuration described in the runner's\npool guide<\/a>.<\/p>\n
    What crosses the network<\/h2>\n
    \"Sequence<\/p>\n
    In the sequence diagram, time flows downward; labelled conditional exchanges occur\nonly when inputs or callbacks are missing. The worker represents the runner’s\nprocessing service, which stages inputs and stores outputs around the sandboxed\ncommand.<\/p>\n
    The job describes the command, profile, input hashes, output files and expiry.\nSmall control messages use JSON. File bytes are streamed separately, rather than\nembedded in JSON. If the runner already has an input for that consumer, the client\ncan reuse it. Concurrent clients reserve a missing hash so only one uploads it.<\/p>\n
    The runner persists accepted jobs before processing. A completed job produces a\nmanifest containing output sizes, SHA-256 hashes and authenticated download URLs.\nThe callback announces that manifest; status polling can recover a lost callback.\nThe client accepts result URLs only from the selected runner endpoint and verifies\nsizes and hashes before publishing the downloaded outputs.<\/p>\n
    Callback delivery and file receipt are different events.<\/strong> The runner retains a\ncompleted manifest and its protected outputs until the client acknowledges receipt\nor result retention expires. The default retention is one day after completion.\nStatus recovery remains available during that window even after execution expiry.\nThe client's receipt acknowledgement is bounded and best effort; losing it leaves\ncleanup to the retention policy.<\/p>\n
    Isolation and trust<\/h2>\n
    On supported systems, commands run with profile-specific filesystem and resource\nrestrictions and without network access. They can use their staged inputs,\noutputs, scratch space and required tool\/runtime files. They cannot access the\nshared cache directly. Inputs are copied into private job directories, so a command\nthat overwrites an input cannot alter another job's cached original.<\/p>\n
    Isolation depends on the host. Unsupported operating systems, including Linux\nwithout the required Landlock support, can continue without sandbox isolation<\/strong>\nand display an alarm. Missing helpers or other sandbox setup failures on supported\nsystems block processing. Check the runner dashboard and z_exec:sandbox_status\/0<\/code>;\na running service alone does not prove that isolation is active.<\/p>\n
    Bearer keys authorize command execution within the selected profiles. Issue them\nonly to trusted clients, use separate consumer accounts, and rotate keys when\naccess changes. Native sandboxing complements host isolation and resource limits;\nlimits on individual processes do not provide a single budget for every delegate\na command might start. See the runner's configuration reference for the exact\nplatform behavior and permissions.<\/p>\n
    Timeouts, retries and maintenance<\/h2>\n
    Three different waits matter:<\/p>\n