{"id":25209527,"url":"https://github.com/backdrop-contrib/s3fs","last_synced_at":"2025-10-25T07:40:47.175Z","repository":{"id":129829060,"uuid":"436749895","full_name":"backdrop-contrib/s3fs","owner":"backdrop-contrib","description":"Adds Amazon Simple Storage Service as a Default download method option.","archived":false,"fork":false,"pushed_at":"2025-10-24T19:36:46.000Z","size":17768,"stargazers_count":0,"open_issues_count":0,"forks_count":3,"subscribers_count":9,"default_branch":"1.x-3.x","last_synced_at":"2025-10-24T21:21:11.423Z","etag":null,"topics":["aws-s3","backdrop","backdropcms","cms"],"latest_commit_sha":null,"homepage":"https://backdropcms.org/project/s3fs","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/backdrop-contrib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-12-09T20:18:28.000Z","updated_at":"2025-10-24T19:34:36.000Z","dependencies_parsed_at":"2025-10-24T21:11:45.813Z","dependency_job_id":"e2e42535-da7c-4d20-bdce-6defbfb8cf03","html_url":"https://github.com/backdrop-contrib/s3fs","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/backdrop-contrib/s3fs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/backdrop-contrib%2Fs3fs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/backdrop-contrib%2Fs3fs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/backdrop-contrib%2Fs3fs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/backdrop-contrib%2Fs3fs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/backdrop-contrib","download_url":"https://codeload.github.com/backdrop-contrib/s3fs/tar.gz/refs/heads/1.x-3.x","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/backdrop-contrib%2Fs3fs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280923471,"owners_count":26414234,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-25T02:00:06.499Z","response_time":81,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws-s3","backdrop","backdropcms","cms"],"created_at":"2025-02-10T13:17:50.712Z","updated_at":"2025-10-25T07:40:47.153Z","avatar_url":"https://github.com/backdrop-contrib.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# S3 File System\n\n---\n\nS3 File System (s3fs) provides an additional file system to your Backdrop site, alongside the public and private file systems, which stores files in Amazon's Simple Storage Service (S3) (or any S3-compatible storage service). You can set your site to use S3 File System as the default, or use it only for individual fields. This functionality is designed for sites which are load-balanced across multiple servers, as the mechanism used by Backdrop's default file systems is not viable under such a configuration.\n\n## Installation\n\nInstall this module using the official Backdrop CMS instructions\n\nat https://docs.backdropcms.org/documentation/extend-with-modules.\n\nVisit the configuration page under Administration \u003e Configuration \u003e Media \u003e s3fs (admin/config/media/s3fs) and enter the required information.\n\nIN CASE OF TROUBLE DETECTING THE AWS SDK LIBRARY:\n\nEnsure that the awssdk folder itself, and all the files within it, can be read by your webserver. Usually this means that the user \"apache\" (or \"_www\" on OSX) must have read permissions for the files, and read+execute permissions for all the folders in the path leading to the awssdk files.\n\n## Initial Setup\n\n------------\n\nWith the code installation complete, you must now configure s3fs to use your Amazon Web Services credentials.\n\nThe preferred method is to use environment variables or IAM credentials as outlined\n\nhere: https://docs.aws.amazon.com/aws-sdk-php/v3/guide/guide/credentials.html\n\nConfigure your settings for S3 File System (including your S3 bucket name) at admin/config/media/s3fs/settings.  Add the AWS keys either in settings.php or use the Key module.\n\n### Essential Step! Do not skip this!\n\nWith the settings saved, go to /admin/config/media/s3fs/actions to refresh the file metadata cache. This will copy the filenames and attributes for every existing file in your S3 bucket into Drupal's database. This can take a significant amount of time for very large buckets (thousands of files). If this operation times out, you can also perform it using \"bee s3fs-refresh-cache\".\n\nPlease keep in mind that any time the contents of your S3 bucket change without Drupal knowing about it (like if you copy some files into it manually using another tool), you'll need to refresh the metadata cache again. S3FS assumes that its cache is a canonical listing of every file in the bucket. Thus, Drupal will not be able to access any files you copied into your bucket manually until S3FS's cache learns of them. This is true of folders as well; s3fs will not be able to copy files into folders that it doesn't know about.\n\n## How to Configure your site to use s3fs\n------------\nVisit the admin/config/media/file-system page and set the \"Default download method\" to \"Amazon Simple Storage Service\" -and/or- Add a field of type File, Image, etc. and set the \"Upload destination\" to \"Amazon Simple Storage Service\" in the \"Field Settings\" tab.\n\nThis will configure your site to store new uploaded files in S3. Files which your site creates automatically (such as\naggregated CSS) will still be stored in the server's local filesystem, because Drupal is hard-coded to use the public:// filesystem for such files.\n\nHowever, s3fs can be configured to handle these files, as well. On the s3fs configuration page (admin/config/media/s3fs) you can enable the \"Use S3 for public:// files\" and/or \"Use S3 for private:// files\" options to make s3fs take over the job of the public and/or private file systems. This will cause your site to store newly uploaded/generated files from the public/private file system in S3 instead of the local file system. However, it will make any existing files in those file systems become invisible to Drupal. To remedy this, you'll need to copy those files into your S3 bucket.\n\nYou are strongly encouraged to use the bee command \"bee s3fs-copy-local\" to do this, as it will copy all the files into the correct subfolders in your bucket, according to your s3fs configuration, and will write them to the metadata cache. If you don't have bee, you can use the buttons provided on the S3FS Actions page (admin/config/media/s3fs/actions), though the copy operation may fail if you have a lot of files, or very large files. The bee command will cleanly handle any combination of files.\n\nIf you're using nginx rather than Apache, you probably have a config block like this:\n\nlocation ~ (^/sites/.*/files/imagecache/|^/sites/default/themes/.*/includes/fonts/|^/sites/.*/files/styles/) {\n  expires max;\n  try_files $uri @rewrite;\n}\n\nTo make s3fs's custom image derivative mechanism work, you'll need to modify\nthat regex it with an additional path, like so:\n\nlocation ~ (^/s3/files/styles/|^/sites/.*/files/imagecache/|^/sites/default/themes/.*/includes/fonts/|^/sites/.*/files/styles/) {\n  expires max;\n  try_files $uri @rewrite;\n}\n\n## AWS Permissions\n\n------------\nFor s3fs to be able to function, the AWS user identified by the configured\ncredentials should have the following User Policy set:\n\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"s3:ListAllMyBuckets\"\n            ],\n            \"Resource\": \"arn:aws:s3:::*\"\n        },\n        {\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"s3:*\"\n            ],\n            \"Resource\": [\n                \"arn:aws:s3:::\u003cbucket_name\u003e\",\n                \"arn:aws:s3:::\u003cbucket_name\u003e/*\"\n            ]\n        }\n    ]\n}\n\nThis is not the precise list of permissions necessary, but it's broad enough to allow s3fs to function while being\n\nstrict enough to restrict access to other services.\n\n## Aggregated CSS and JS in S3\n\n------------\n\nIf you want your site's aggregated CSS and JS files to be stored on S3, rather than the default of storing them on the webserver's local filesystem, you'll need to do two things:\n\n1) Enable the \"Use S3 for public:// files\" option in the s3fs configuration, because Drupal always* puts aggregated\n\nCSS/JS into the public:// filesystem.\n\n2) Because of the way browsers interpret relative URLs used in CSS files, and how they restrict requests made from external javascript files, you'll need to set up your webserver as a proxy for those files.\n\nWhen you've got a module like \"Advanced CSS/JS Aggregation\" installed, things get hairy. For now, that module is not compatible with s3fs public:// takeover.\n\nS3FS will present all css files in the taken over public:// filesystem with the url prefix /s3fs-css/, and all\n\njavascript files with /s3fs-js/. So you need to set up your webserver to proxy those URLs into your S3 bucket.\n\nFor Apache, add this code to the right location* in your server's config:\n\nProxyRequests Off\nSSLProxyEngine on\n\u003cProxy *\u003e\n    Order deny,allow\n    Allow from all\n\u003c/Proxy\u003e\nProxyPass /s3fs-css/ https://YOUR-BUCKET.s3.amazonaws.com/s3fs-public/\nProxyPassReverse /s3fs-css/ https://YOUR-BUCKET.s3.amazonaws.com/s3fs-public/\nProxyPass /s3fs-js/ https://YOUR-BUCKET.s3.amazonaws.com/s3fs-public/\nProxyPassReverse /s3fs-js/ https://YOUR-BUCKET.s3.amazonaws.com/s3fs-public/\n\nIf you're using the \"S3FS Root Folder\" option, you'll need to insert that\nfolder before the /s3fs-public/ part of the target URLs. Like so:\n\nProxyPass /s3fs-css/ https://YOUR-BUCKET.s3.amazonaws.com/YOUR-ROOT-FOLDER/s3fs-public/\nProxyPassReverse /s3fs-css/ https://YOUR-BUCKET.s3.amazonaws.com/YOUR-ROOT-FOLDER/s3fs-public/\n\nIf you've set up a custom name for the public folder, you'll need to change the\n\n's3fs-public' part of the URLs above to match your custom folder name.\n\n* The \"right location\" is implementation-dependent. Normally, placing these lines at the bottom of your httpd.conf file\n\nshould be sufficient. However, if your site is configured to use SSL, you'll need to put these lines in the\n\nVirtualHost settings for both your normal and SSL sites.\n\nFor nginx, add this to your server config:\n\nlocation ~* ^/(s3fs-css|s3fs-js)/(.*) { set $s3_base_path 'YOUR-BUCKET.s3.amazonaws.com/s3fs-public'; set $file_path $2;\nresolver 8.8.4.4 8.8.8.8 valid=300s; resolver_timeout 10s;\nproxy_pass http://$s3_base_path/$file_path; }\n\nAgain, be sure to take the S3FS Root Folder setting into account, here.\n\nThe /s3fs-public/ subfolder is where s3fs stores the files from the public:// filesystem, to avoid name conflicts with files from the s3:// filesystem.\n\nIf you're using the \"Use a Custom Host\" option to store your files in a non-Amazon file service, you'll need to change the proxy target to the appropriate URL for your service.\n\nUnder some domain name setups, you may be able to avoid the need for proxying by having the same domain name as your site also point to your S3 bucket. If that is the case with your site, enable the \"Don't rewrite CSS/JS file paths\" option to prevent s3fs from prefixing the URLs for CSS/JS files.\n\n## Known Issues\n\n------------\nSome curl libraries, such as the one bundled with MAMP, do not come with authoritative certificate files. See the\n\nfollowing page for details:\n\nhttp://dev.soup.io/post/56438473/If-youre-using-MAMP-and-doing-something\n\nBecause of a bizarre limitation regarding MySQL's maximum index length for InnoDB tables, the maximum uri length that S3FS supports is 250 characters. That includes the full path to the file in your bucket, as the full folder path is part of the uri.\n\neAccelerator, a deprecated opcode cache plugin for PHP, is incompatible with AWS SDK for PHP. eAccelerator will corrupt the configuration settings for the SDK's s3 client object, causing a variety of different exceptions to be thrown. If your server uses eAccelerator, it is highly recommended that you replace it with a different opcode cache plugin, as its development was abandoned several years ago.\n\nFor s3fs 7.x-3.x, the most current supported version of AWS SDK is v3.156.0, which can be downloaded above. This is due to an [open issue](https://www.drupal.org/project/s3fs/issues/3194400).\n\n## Differences from Drupal 7\n\nThe ability to save the AWS keys in UI on the settings page was removed.\n\nThis needs to be done in settings.php or by using the Key module.\n\nAdvanced features have not been fully tested.\n\nThe tests probably do not work.\n\n## Issues\n\n------\n\nBugs and feature requests should be reported in [the Issue Queue](https://github.com/backdrop-contrib/s3fs/issues).\n\n## Current Maintainers\n\n-------------------\n\n- [Justin Keiser](https://github.com/keiserjb).\n\n- Seeking additional maintainers.\n\n- This module is supported by the [Academy of Model Aeronautics](https://www.modelaircraft.org/).\n\n## Credits\n\n-------\n\n- Ported to Backdrop CMS by [Justin Keiser](https://github.com/keiserjb).\n\n- Originally written for Drupal by [Robert Rollins](https://github.com/coredumperror).\n\n## License\n\n-------\n\nThis project is GPL v2 software. See the LICENSE.txt file in this directory for complete text.\n\nThe AWS SDK library for PHP is licensed under an Apache License.\n\n## Acknowledgements\n\nSpecial recognition goes to justafish, author of the AmazonS3 module:\n\nhttp://drupal.org/project/amazons3\n\nS3 File System started as a fork of her great module, but has evolved dramatically since then, becoming a very different\n\nbeast. The main benefit of using S3 File System over AmazonS3 is performance, especially for image- related operations,\n\ndue to the metadata cache that is central to S3 File System's operation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbackdrop-contrib%2Fs3fs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbackdrop-contrib%2Fs3fs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbackdrop-contrib%2Fs3fs/lists"}