{"id":13721048,"url":"https://github.com/kuzzleio/kuzzle-plugin-s3","last_synced_at":"2025-04-29T13:33:42.729Z","repository":{"id":56412903,"uuid":"185434861","full_name":"kuzzleio/kuzzle-plugin-s3","owner":"kuzzleio","description":"Upload and manage files with S3 protocol","archived":false,"fork":false,"pushed_at":"2023-08-28T11:48:17.000Z","size":1307,"stargazers_count":2,"open_issues_count":1,"forks_count":4,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-11-04T00:21:43.499Z","etag":null,"topics":["file-upload","kuzzle","kuzzle-plugin","presignedurl","s3"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kuzzleio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-05-07T15:56:33.000Z","updated_at":"2023-06-27T13:39:56.000Z","dependencies_parsed_at":"2024-01-14T22:03:50.624Z","dependency_job_id":"80230985-1262-4130-bb2c-5aaf004cae93","html_url":"https://github.com/kuzzleio/kuzzle-plugin-s3","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuzzleio%2Fkuzzle-plugin-s3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuzzleio%2Fkuzzle-plugin-s3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuzzleio%2Fkuzzle-plugin-s3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuzzleio%2Fkuzzle-plugin-s3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kuzzleio","download_url":"https://codeload.github.com/kuzzleio/kuzzle-plugin-s3/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224175670,"owners_count":17268390,"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","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":["file-upload","kuzzle","kuzzle-plugin","presignedurl","s3"],"created_at":"2024-08-03T01:01:11.730Z","updated_at":"2025-04-29T13:33:42.699Z","avatar_url":"https://github.com/kuzzleio.png","language":"JavaScript","funding_links":[],"categories":["Plugins"],"sub_categories":["External services plugins"],"readme":"# Kuzzle Plugin S3\n\nS3 has a right system to limit who can upload files to buckets.\n\n[Presigned URLs](https://docs.aws.amazon.com/AmazonS3/latest/dev/PresignedUrlUploadObject.html) are special disposable URLs generated by S3. It is possible to upload a file directly to one of these URLs so that it can be stored into the bucket.\n\nThese URLs must be generated on the server side, this plugin includes among other things the generation of these URLs so that developers can then send their files directly to S3 from a client application.\n\n## Compatibility Matrix\n\n| Kuzzle Version | Plugin Version |\n| -------------- | -------------- |\n| 1.x.x          | 1.x.x          |\n| 2.x.x          | 2.x.x          |\n| 2.x.x          | 3.x.x          |\n\n## Configuration\n\n\\\nYour access key must have the following rights: `GetObject` , `PutObject` and `DeleteObject`.\n\nThen in your `kuzzlerc` file, you can change the following configuration variable:\n\n```js\n{\n  \"plugins\": {\n    \"s3\": {\n      \"endpoints\": {\n        \"eu-west-3\": {\n          \"endpoint\": \"https://s3.eu-west-3.amazonaws.com\",\n          \"forcePathStyle\": false,\n          \"accessKeyIdPath\": \"foo.s3.eu-west-3.accessKeyId\",\n          \"secretAccessKeyPath\": \"foo.s3.eu-west-3.secretAccessKey\",\n          \"isMinio\": false\n        },\n        \"us-east-1\": {\n          \"endpoint\": \"https://s3.us-east-1.amazonaws.com\",\n          \"forcePathStyle\": false,\n          \"accessKeyIdPath\": \"foo.s3.us-east-1.accessKeyId\",\n          \"secretAccessKeyPath\": \"foo.s3.us-east-1.secretAccessKey\",\n          \"isMinio\": false\n        },\n        \"custom-minio\": {\n          \"endpoint\": \"https://minio.example.com\",\n          \"forcePathStyle\": true,\n          \"accessKeyIdPath\": \"foo.s3.minio.accessKeyId\",\n          \"secretAccessKeyPath\": \"foo.s3.minio.secretAccessKey\",\n          \"isMinio\": true\n        }\n      },\n      \"signedUrlTTL\": 1200000\n    }\n  }\n}\n```\n\n### Updated Configuration Format\n\n- **Endpoints**: Defines region-specific configurations, including endpoint URL and access keys.\n- **Signed URL TTL**: Time-to-live for presigned URLs generated by the plugin.\n\nIn addition to Amazon AWS S3, this plugin allows you to use any S3-API compatible service accessible through the [AWS-S3 SDK](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html). Any specific [configuration option](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#constructor-property) can be added to the `s3ClientOptions` configuration attribute. Please note that the parameters are translated directly, so refer to the SDK documentation for available options.\n\n## Usage\n\nGet a Presigned URL:\n\n```javascript\n// Kuzzle request\n{\n  \"controller\": \"s3/upload\",\n  \"action\": \"getUploadUrl\",\n  \"filename\": \"headcrab.png\",\n  \"uploadDir\": \"xen\"\n}\n\n// Kuzzle response\n{\n  \"fileKey\": \"xen/\u003cuuid\u003e-headcrab.png\",\n  \"uploadUrl\": \"https://s3.eu-west-3.amazonaws.com/...\",\n  \"fileUrl\": \"https://s3.eu-west-3.amazonaws.com/...\",\n  \"ttl\": 1200000\n}\n```\n\nThen send a PUT request to the `uploadUrl` URL with the body set to the file's content and a `Content-Type` header corresponding to the file mime type.\n\n### Example using the JavaScript SDK\n\n```js\n  // Get a Presigned URL\n  const file = document.getElementById('uploadInput').files[0];\n  const { result } = await kuzzle.query({\n    controller: 's3/upload',\n    action: 'getUploadUrl',\n    uploadDir: 'xen',\n    filename: file.name\n  });\n\n  // Upload the file directly to S3\n  const axiosOptions = {\n    headers: {\n      'Content-Type': file.type\n    }\n  };\n  await axios.put(result.uploadUrl, file, axiosOptions);\n\n```\n\n\n### API\n\n#### *upload*\\*:getUploadUrl\\*\n\nReturns a Presigned URL to upload directly to S3.\\\nThe URL is only valid for a specified period of time. (Configurable in the [kuzzlerc file](https://docs.kuzzle.io/plugins/2/manual-setup/config/))\n\nFile uploaded to the generated URL must be validated with `upload:validate` otherwise they will be deleted after the same TTL as for the URL expiration.\n\n*Request format:*\n\n```javascript\n{\n  \"controller\": \"s3/upload\",\n  \"action\": \"getUploadUrl\",\n  \"filename\": \"headcrab.png\",\n  \"uploadDir\": \"xen\",\n  \"bucketRegion\": \"foo\",\n  \"bucketName\": \"bar\"\n}\n```\n\n*Response result format:*\n\n```javascript\n{\n  \"fileKey\": \"xen/\u003cuuid\u003e-headcrab.png\",\n  \"uploadUrl\": \"https://s3.eu-west-3.amazonaws.com/...\",\n  \"fileUrl\": \"https://s3.eu-west-3.amazonaws.com/...\",\n  \"ttl\": 1200000\n}\n```\n\n#### *file*\\*:getFileUrl\\*\n\nReturns the public file URL.\n\n*Request format:*\n\n```javascript\n{\n  \"controller\": \"s3/file\",\n  \"action\": \"getFileUrl\",\n  \"fileKey\": \"xen/\u003cuuid\u003e-headcrab.png\",\n  \"bucketRegion\": \"foo\",\n  \"bucketName\": \"bar\"\n}\n```\n\n*Response result format:*\n\n```javascript\n{\n  \"fileUrl\": \"https://s3.eu-west-3.amazonaws.com/...\"\n}\n```\n\n#### *file*\\*:delete\\*\n\nDeletes an uploaded file from S3.\n\n*Request format:*\n\n```javascript\n{\n  \"controller\": \"s3/file\",\n  \"action\": \"fileDelete\",\n  \"fileKey\": \"xen/\u003cuuid\u003e-headcrab.png\",\n  \"bucketRegion\": \"foo\",\n  \"bucketName\": \"bar\"\n}\n```\n\n#### *file*\\*:getFilesKeys\\*\n\nList the files keys uploaded to an S3 Bucket.\n\n*Request format:*\n\n```javascript\n{\n  \"controller\": \"s3/file\",\n  \"action\": \"getFilesKeys\",\n  \"bucketRegion\": \"foo\",\n  \"bucketName\": \"bar\"\n}\n```\n\n## Installation\n\n### Local setup\n\nYou can use the [docker-compose.yml](docker/docker-compose.yml) file provided in this repository to start a Kuzzle stack with this plugin pre-installed.\n\n```bash\ndocker-compose -f docker-compose.yml up\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuzzleio%2Fkuzzle-plugin-s3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkuzzleio%2Fkuzzle-plugin-s3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuzzleio%2Fkuzzle-plugin-s3/lists"}