Store uploaded media and generated previews on S3-compatible storage, FTP\/FTPS,\nor WebDAV. Zotonic keeps a database registry of remote files and serves them\nthrough a shared local cache when they are no longer on the site's disk.<\/p>\n
mod_filestore<\/code> for the site.<\/li>- Open System → Cloud File Store<\/strong> in the admin. Changing settings and starting\nbulk moves require the
use mod_admin_config<\/code> permission.<\/li>- Enter the base URL and credentials for your storage service using the table below.\nFor S3, enter the provider's region to enable Signature V4, or leave it empty\nto use legacy Signature V2.<\/li>
- Select Upload new media files to the cloud file store<\/strong>. Decide whether to\nKeep local files after upload<\/strong> and choose the remote deletion delay.<\/li>
- Save the settings. Zotonic writes, reads back, and deletes a temporary\n
-zotonic-filestore-test-file-<\/code> beneath the base URL. Settings are saved only\nwhen this test succeeds.<\/li>- Upload a test image, allow the upload queue to run, and check both the original\nand a resized preview. Use the bulk action to upload existing media when ready.<\/li><\/ol>\n
A successful credential test checks these operations at the configured location;\ncheck normal media delivery as well. The test needs delete permission even when\nremote deletion is set to Never<\/strong>.<\/p>\nSupported services and URLs<\/h3>\n
Service<\/th> Base URL example<\/th> Credentials<\/th> service<\/code> value<\/th><\/tr><\/thead>S3-compatible<\/td> https:\/\/mybucket.s3.amazonaws.com\/mysite<\/code><\/td>Access key and secret key<\/td> s3<\/code><\/td><\/tr>FTP over TLS<\/td> ftps:\/\/files.example.com\/mysite<\/code><\/td>Username and password<\/td> ftp<\/code><\/td><\/tr>WebDAV over HTTPS<\/td> webdavs:\/\/files.example.com\/remote.php\/dav\/files\/alice\/mysite<\/code><\/td>Username and password<\/td> webdav<\/code><\/td><\/tr><\/tbody><\/table>\nThe admin derives the service from the URL scheme. http:<\/code> and https:<\/code> select\nS3, not WebDAV. For WebDAV use webdav:<\/code> or webdavs:<\/code>; dav:<\/code> and davs:<\/code> are\naliases. Use webdavs:<\/code> or davs:<\/code> to protect the WebDAV credentials with HTTPS.<\/p>\nBoth ftp:<\/code> and ftps:<\/code> select the FTP backend. The server must support TLS:\nthe client uses passive FTP with explicit TLS by default, or implicit TLS when\nport 990 is specified, for example ftps:\/\/files.example.com:990\/mysite<\/code>.\nAllow the server's passive data connections through the firewall. SFTP (SSH file\ntransfer) is not supported by this backend.<\/p>\nFTP and WebDAV create missing directories during upload. Their accounts need\npermission to create directories and write, read, and delete files in the chosen\nlocation. For S3, the admin can try to create a private bucket if it is missing;\nthis requires permission to create a bucket. The checkbox is a setup action, not\na saved configuration option.<\/p>\n
S3 signature version and region<\/h3>\n
The S3 region<\/strong> field (s3region<\/code>) selects the signature version automatically:<\/p>\nEffective region<\/th> Signature version<\/th><\/tr><\/thead> Empty, including whitespace-only values<\/td> Signature V2 (legacy)<\/td><\/tr> Nonempty, for example eu-west-1<\/code><\/td>Signature V4, signed for that region<\/td><\/tr><\/tbody><\/table>\nLeading and trailing whitespace is removed. Use the region supplied by your\nstorage provider; Zotonic does not infer it from the endpoint URL. There is no\nseparate signature-version setting and no automatic fallback to V2 if a V4\nrequest fails. Providers requiring V4 need a nonempty, correct region.<\/p>\n
This selection applies to settings tests and all S3 file operations, including\nuploads, downloads, streaming, deletion, and bucket-creation requests. FTP and\nWebDAV ignore the region.<\/p>\n
An unset site region inherits the system-wide s3region<\/code> default. An explicitly\nempty site region overrides that default and selects V2. When configuration is\nlocked, the system-wide region determines the signature version. Existing\ninstallations without a region continue to use V2.<\/p>\nS3 permissions<\/h3>\n
Use a bucket or prefix dedicated to the site. Grant bucket listing where required\nby the provider and grant the following object permissions beneath the base URL:<\/p>\n
Path<\/th> Permissions<\/th><\/tr><\/thead> -zotonic-filestore-test-file-<\/code><\/td>s3:GetObject<\/code>, s3:PutObject<\/code>, s3:DeleteObject<\/code><\/td><\/tr>archive\/*<\/code><\/td>s3:GetObject<\/code>, s3:PutObject<\/code>; s3:DeleteObject<\/code> when remote deletion is enabled<\/td><\/tr>preview\/*<\/code><\/td>s3:GetObject<\/code>, s3:PutObject<\/code>; s3:DeleteObject<\/code> when remote deletion is enabled<\/td><\/tr><\/tbody><\/table>\nOther applications using the filestore may write additional paths. Give those\npaths the corresponding permissions. Files do not need public-read access:\nZotonic retrieves them using the configured credentials.<\/p>\n
Configuration reference<\/h2>\n
Site settings are stored under mod_filestore<\/code> in m_config<\/code>. The historical\ns3<\/code> prefixes also apply to FTP and WebDAV, except s3region<\/code>, which only applies to S3.\nAn explicitly empty site region selects V2 instead of inheriting a global region.\nAn unset site region inherits the global setting; locked configuration always uses the global setting.<\/p>\nKey<\/th> Meaning<\/th><\/tr><\/thead> service<\/code><\/td>Backend identifier: s3<\/code>, ftp<\/code>, or webdav<\/code>. Set it explicitly outside the admin; an empty value falls back to s3<\/code>. TLS variants are URL schemes, not backend identifiers.<\/td><\/tr>s3url<\/code><\/td>Base URL, including the bucket or directory and optional site prefix.<\/td><\/tr> s3region<\/code><\/td>S3 signing region, for example eu-west-1<\/code>. A nonempty region enables Signature V4; empty uses legacy Signature V2.<\/td><\/tr>s3key<\/code><\/td>S3 access key, or FTP\/WebDAV username.<\/td><\/tr> s3secret<\/code><\/td>S3 secret key, or FTP\/WebDAV password.<\/td><\/tr> is_read_only<\/code><\/td>Download-only mode. Blocks uploads, remote deletion and write-based credential tests for every backend. Default false<\/code>. A global or site-file true<\/code> cannot be overridden by other settings.<\/td><\/tr>is_upload_enabled<\/code><\/td>Allow background uploads. Set explicitly when configuring storage outside the admin. Disabling this does not disable reads, queued downloads, or remote deletion.<\/td><\/tr> is_local_keep<\/code><\/td>Keep local files after successful upload. When false, uploaded files move into the evictable cache.<\/td><\/tr> delete_interval<\/code><\/td>Extra delay before deleting files marked for remote deletion: 0<\/code> (the default, no extra delay), false<\/code> (never), seconds, or a value such as 1 week<\/code>, 2 days<\/code>, or 3 months<\/code>.<\/td><\/tr>tls_options<\/code><\/td>Erlang list of TLS options passed to the selected storage client. Not an admin form field; an empty list uses the client's defaults.<\/td><\/tr><\/tbody><\/table>\nSystem-wide defaults and locked settings<\/h3>\n
The same keys can be set in the zotonic_mod_filestore<\/code> application environment in\nthe system configuration. Nonempty site settings override these defaults unless\nis_config_locked<\/code> is true. For s3region<\/code>, an explicitly empty site setting also\noverrides the default, selecting Signature V2. This lock is a system-wide<\/strong> option: it makes sites\nuse the application settings and prevents editing them through the filestore form.<\/p>\nis_read_only<\/code> is an exception to this override rule: setting it to true<\/code> in the\nglobal zotonic_mod_filestore<\/code> configuration makes storage read-only for every\nsite<\/strong>, including sites with their own endpoints or credentials. A site cannot\nturn it off with false<\/code>. This restriction works independently of\nis_config_locked<\/code>; locking configuration is not required to enforce read-only\nstorage. A site can also enable read-only mode when the global value is false.<\/p>\nFor example, merge this application entry into the system's Erlang configuration\nlist, using your own endpoint and credentials:<\/p>\n
{zotonic_mod_filestore, [\n {service, <<"webdav">>},\n {s3url, <<"webdavs:\/\/files.example.com\/zotonic\/{{site}}">>},\n {s3key, <<"storage-user">>},\n {s3secret, <<"replace-with-password">>},\n {is_read_only, false},\n {is_upload_enabled, true},\n {is_local_keep, true},\n {delete_interval, <<"false">>},\n {is_config_locked, true}\n]}\n<\/code><\/pre>\nThe example permits uploads. Set {is_read_only, true}<\/code> in the same application\nentry to make all sites download-only. It takes precedence over\n{is_upload_enabled, true}<\/code> and any delete_interval<\/code>: uploads and remote deletes\nare blocked without changing those saved settings. This is useful when a staging\nor recovery installation needs to read existing storage without modifying it.<\/p>\nIn a system-configured<\/strong> base URL, {{site}}<\/code> is replaced with the site name.\nIf the placeholder is absent, Zotonic appends the site name as a directory.\nA base URL saved in the site's admin is used as entered, without this expansion.\nConfigure service<\/code> alongside the URL: URL-based service detection happens when\nsaving the admin form, not when reading application configuration.<\/p>\nRead-only storage<\/h3>\n
To allow downloads while preventing remote writes for all sites<\/strong>, merge this\nentry into the Zotonic global Erlang configuration list (or add the key to its\nexisting zotonic_mod_filestore<\/code> entry):<\/p>\n{zotonic_mod_filestore, [\n {is_read_only, true}\n]}\n<\/code><\/pre>\nFor one site, add this to its site configuration:<\/p>\n
{mod_filestore, [\n {is_read_only, true}\n]}\n<\/code><\/pre>\nThese examples show the entry to merge into the existing configuration list.\nThe setting can also be stored as mod_filestore.is_read_only<\/code> in m_config<\/code>.\nRestrictions are additive: a global or site-file true<\/code> remains effective even\nif another source says false<\/code>, or the service configuration is locked. The\ndefault is false<\/code>. To restore writes, remove or disable every active read-only\nrestriction; changing only a site setting cannot lift a global restriction.<\/p>\nRead-only mode blocks background uploads, remote deletion, direct filestore\nupload\/delete requests and the admin's write-based credential test. Direct writes\nreturn {error, read_only}<\/code>. Existing upload and deletion queues are retained and\ncan resume when read-only mode is disabled. Local registry deletion marks can still\nbe recorded. Already dispatched remote operations cannot be revoked by changing\nconfiguration; enable read-only mode before starting the site when that matters.<\/p>\nNormal downloads, cached reads and copying remote files to local disk remain\navailable. The admin shows the effective mode and disables upload\/test buttons.\nSettings can be saved without a write test; verify credentials by downloading an\nexisting file. Read-only accounts need only the provider's read permissions for\nthose objects. No test object or bucket is created in this mode.<\/p>\n
Uploads, local copies, and the cache<\/h2>\n
New media files and previews are queued for asynchronous upload. Queue entries\nbecome eligible after one minute. Processing runs on a minute tick, with bounded\nbatches, database-load checks, and backoff, so completion can take longer.<\/p>\n
With is_local_keep<\/code> enabled, remote storage holds an additional copy of local\nmedia. Otherwise, successfully uploaded files move from the site's files directory\ninto filezcache<\/code>, where they can be evicted. When a remote-only file is requested,\nZotonic downloads it into the cache and can serve it while the download proceeds.<\/p>\nThe filezcache<\/code> application is shared by all sites. Its max_bytes<\/code> application\nsetting controls cache capacity (default 10 GiB). Cache files are disposable;\nretain the remote files and database registry. Keeping remote media copies does\nnot replace a backup of the site's database, configuration, and application code.<\/p>\nRead failures and retries<\/h2>\n
A failed remote cache read remains in the file registry and is retried when the\nfile is requested again. This includes forbidden<\/code> and enoent<\/code>: a permission or\naccount problem can be temporary, and S3 can return forbidden<\/code> for missing files.<\/p>\nEach file has its own exponential retry delay: nominally 5, 10, 20, 40 seconds,\nand so on, capped at ten minutes. Jitter varies each delay between 80% and 100%\nof that value. During the cooldown, requests do not start another remote read;\nan existing local or cached copy remains usable. A successful remote read clears\nthe error and resets the delay. There is no automatic permanent cutoff, and files\nthat are not requested generate no read retries.<\/p>\n
Retry eligibility is not a scheduled download time. Zotonic's file-serving\nnegative cache can add up to 60 seconds before another lookup occurs. Retry state\nsurvives restarts. An expiring database claim limits concurrent attempts across\nnodes; abandoned claims expire after ten minutes.<\/p>\n
This policy applies to remote reads into filezcache<\/code>. Background queue processing\nhas separate batch-size backoff. Direct #filestore_request{}<\/code> calls do not use\nthis persistent read-retry policy.<\/p>\nDeletion and moving existing files<\/h2>\n
Zotonic normally retains deleted media for five weeks to allow recovery. The\nfilestore's delete_interval<\/code> adds a delay after a file is marked for remote\ndeletion. 0<\/code> means no extra<\/strong> delay, not deletion at the instant a page is\nremoved. false<\/code> keeps remote files indefinitely; it does not make the remote\nservice itself immutable.<\/p>\nUse the admin's bulk actions to queue existing local media for upload or to move\nremote files back to the server's disk. These operations run in the background;\nwatch the queues and logs. Moving files to disk requires enough disk space and\nworking credentials for their existing locations. Disable uploads when bringing\nfiles back for a storage migration.<\/p>\n
Before switching to a different service or account, bring the files back locally\nand verify that the download queue has completed. Then configure and test the new\nlocation and queue uploads. Changing the base URL alone does not copy existing\nremote objects: the registry retains their original service and location. The\ndefault reverse lookup uses credentials for the currently configured service.\nRemote deletion also checks that an object's URL matches the configured base URL.<\/p>\n
Statistics and troubleshooting<\/h2>\n
The admin shows registered media, estimated local file counts and sizes, remote\nfile counts and sizes, and upload, download, and delete queue counts. These figures\ncome from the site's database; they are not a scan or integrity check of remote\nstorage. Local totals are estimates, not a scan of the files directory.<\/p>\n
If uploads do not progress, check that uploads are enabled, the module is active,\nand the URL and credentials pass the settings test. Inspect logs for connection,\npermission, TLS, or storage errors. For FTP, check passive data connections; for\nWebDAV, check the full collection path and the webdavs:<\/code> scheme. Allow for the\nqueue delay and backoff before assuming a newly queued file is stuck.<\/p>\nHealth warnings and error details<\/h3>\n
The admin dashboard and filestore configuration page warn administrators when:<\/p>\n
- At least five remote cache reads failed and failures account for at least 20%\nof completed reads in the current and preceding fourteen minute buckets.<\/li>
- At least one active, unresolved read error is older than 24 hours.<\/li><\/ul>\n
The read-error rate is shared across nodes. It counts completed remote attempts,\nnot cache hits or requests suppressed by the cooldown. The 24-hour age runs from\nthe first failure in the current unresolved sequence; repeated failures do not\nrestart that clock.<\/p>\n
Follow View errors<\/strong> to the filestore page for details. The list shows 50 files\nper page<\/strong>, oldest first, with Previous\/Next navigation. Each row shows the relative\nfile path, storage service, latest recorded error, consecutive failure count,\nfailing-since time, and retry eligibility. Only errors older than 24 hours are\nlisted, including entries explicitly marked unrecoverable. Remote URLs and\ncredentials are not included in the list.<\/p>\nMarking a file unrecoverable<\/h3>\n
Only the administrator account, user 1<\/strong>, sees the Mark unrecoverable<\/strong> action.\nAfter confirmation, the server rechecks both the user ID and that the entry still\nhas an unresolved error older than 24 hours. Other administrators cannot perform\nthis action, and a recovered or recently failed entry is not eligible.<\/p>\nMarking an entry unrecoverable stops automatic remote cache-read retries and\nremoves it from active unresolved-error counts. Its row remains in the error list\nwith an Unrecoverable<\/strong> label. The file registry record and error details are\nretained; no local or remote files are deleted. Historical read-rate statistics\nare unchanged, so a high-error-rate warning can remain until those attempts leave\nthe reporting window. Late callbacks from an attempt already in flight cannot\nclear the unrecoverable state. A new successful upload of the path resets it.<\/p>\nIntegration points<\/h2>\n
mod_filestore<\/code> handles these notifications:<\/p>\n#media_update_done{}<\/code> queues inserted or updated media files.<\/li>#filestore{}<\/code> handles file lookup, upload, and deletion through the file registry and cache.<\/li>#filestore_request{}<\/code> handles direct storage upload, download, and deletion requests.<\/li>#filestore_credentials_lookup{}<\/code> maps a local path and optional resource ID to remote credentials and location.<\/li>#filestore_credentials_revlookup{}<\/code> resolves credentials for an existing remote service and location.<\/li>#admin_menu{}<\/code> adds the admin menu entry.<\/li><\/ul>\n