Getting Started

Installation

Compatibility

Parse Server

Node.js

AWS Credentials

Deprecated Configuration

Usage with Parse Server

Parameters

Using a Config File

{  "appId": 'my_app_id',  "masterKey": 'my_master_key',  // other options  "filesAdapter": {    "module": "@parse/s3-files-adapter",    "options": {      "bucket": "my_bucket",      // optional:      "region": 'us-east-1', // default value      "bucketPrefix": '', // default value      "directAccess": false, // default value      "fileAcl": null, // default value      "baseUrl": null, // string, function or async function      "baseUrlDirect": false, // default value      "signatureVersion": 'v4', // default value      "globalCacheControl": null, // default value. Or 'public, max-age=86400' for 24 hrs Cache-Control      "presignedUrl": false, // Optional. If true a presigned URL is returned when requesting the URL of file. The URL is only valid for a specified duration, see parameter `presignedUrlExpires`. Default is false.      "presignedUrlExpires": null, // Optional. Sets the duration in seconds after which the presigned URL of the file expires. Defaults to the AWS S3 SDK default Expires value.      "ServerSideEncryption": 'AES256|aws:kms', //AES256 or aws:kms, or if you do not pass this, encryption won't be done      "validateFilename": null, // Default to parse-server FilesAdapter::validateFilename.      "generateKey": null // Will default to Parse.FilesController.preserveFileName    }  }}

Using Environment Variables

S3_BUCKET=bucketName

S3_SIGNATURE_VERSION=v4

{  "appId": 'my_app_id',  "masterKey": 'my_master_key',  // other options  "filesAdapter": "@parse/s3-files-adapter"}

Passing as an Instance

var S3Adapter = require('@parse/s3-files-adapter');var s3Adapter = new S3Adapter(  'accessKey',  'secretKey',  'bucket',  {    region: 'us-east-1'    bucketPrefix: '',    directAccess: false,    baseUrl: 'http://images.example.com',    signatureVersion: 'v4',    globalCacheControl: 'public, max-age=86400',  // 24 hrs Cache-Control.    presignedUrl: false,    presignedUrlExpires: 900,    validateFilename: (filename) => {      if (filename.length > 1024) {          return 'Filename too long.';        }        return null; // Return null on success    },    generateKey: (filename) => {      return `${Date.now()}_${filename}`; // unique prefix for every filename    }  });var api = new ParseServer({  appId: 'my_app',  masterKey: 'master_key',  filesAdapter: s3adapter})

S3Adapter("bucket")S3Adapter("bucket", options)S3Adapter("key", "secret", "bucket") -- Deprecated, see notice aboveS3Adapter("key", "secret", "bucket", options) -- Deprecated, see notice aboveS3Adapter(options) // where options must contain bucket.S3Adapter(options, s3overrides)

var S3Adapter = require('@parse/s3-files-adapter');var s3Options = {  "bucket": "my_bucket",  // optional:  "region": 'us-east-1', // default value  "bucketPrefix": '', // default value  "directAccess": false, // default value  "baseUrl": null // string, function or async function  "signatureVersion": 'v4', // default value  "globalCacheControl": null, // default value. Or 'public, max-age=86400' for 24 hrs Cache-Control  "presignedUrl": false, // default value  "presignedUrlExpires": 900, // default value (900 seconds)  "validateFilename": () => null, // Anything goes!  "generateKey": (filename) => filename,  // Ensure Parse.FilesController.preserveFileName is true!}var s3Adapter = new S3Adapter(s3Options);var api = new ParseServer({  appId: 'my_app',  masterKey: 'master_key',  filesAdapter: s3Adapter})

Adding Metadata and Tags

const S3Adapter = require('@parse/s3-files-adapter');const s3Options = {}; // Add correct optionsconst s3Adapter = new S3Adapter(s3Options);const filename = 'Fictional_Characters.txt';const data = 'That\'s All Folks!';const contentType = 'text/plain';const tags = {  createdBy: 'Elmer Fudd',  owner: 'Popeye'};const metadata = {  source: 'Mickey Mouse'};const options = { tags, metadata };s3Adapter.createFile(filename, data, contentType, options);

Compatibility with other Storage Providers

Digital Ocean Spaces

varS3Adapter=require("@parse/s3-files-adapter");varAWS=require("aws-sdk");//Configure Digital Ocean Spaces EndPointvars3Options={bucket:process.env.SPACES_BUCKET_NAME,baseUrl:process.env.SPACES_BASE_URL,region:process.env.SPACES_REGION,directAccess:true,globalCacheControl:"public, max-age=31536000",presignedUrl:false,presignedUrlExpires:900,bucketPrefix:process.env.SPACES_BUCKET_PREFIX,s3overrides:{accessKeyId:process.env.SPACES_ACCESS_KEY,secretAccessKey:process.env.SPACES_SECRET_KEY,endpoint:process.env.SPACES_ENDPOINT}};vars3Adapter=newS3Adapter(s3Options);varapi=newParseServer({databaseURI:process.env.DATABASE_URI||"mongodb://localhost:27017/dev",cloud:process.env.CLOUD_CODE_MAIN||__dirname+"/cloud/main.js",appId:process.env.APP_ID||"myAppId",masterKey:process.env.MASTER_KEY||"",serverURL:process.env.SERVER_URL||"http://localhost:1337/parse",logLevel:process.env.LOG_LEVEL||"info",allowClientClassCreation:false,filesAdapter:s3Adapter});

Migration Guide from 3.x to 4.x

AWS IAM Permissions

{"Effect":"Allow","Action": ["s3:ListBucket"  ],"Resource":"arn:aws:s3:::<BUCKET_NAME>"}

Note

The specified resource needs to be the bucket ARN itself, no/* at the end, because it's a bucket-level permission, not object-level.

Passing S3 Credentials

constoptions={bucket:'<AWS_S3_BUCKET>',s3overrides:{accessKeyId:'<AWS_ACCESS_KEY>',secretAccessKey:'<AWS_SECRET_KEY>'}};

constoptions={bucket:'<AWS_S3_BUCKET>',s3overrides:{credentials:{accessKeyId:'<AWS_ACCESS_KEY>',secretAccessKey:'<AWS_SECRET_KEY>'}}};

constoptions={bucket:'<AWS_S3_BUCKET>',credentials:{accessKeyId:'<AWS_ACCESS_KEY>',secretAccessKey:'<AWS_SECRET_KEY>'}};

Note

It is best practice to not store credentials as environment variables, as they can be easily retrieved on a compromised machine. For Parse Server running in an AWS environment, use more secure alternatives like AWS Secrets Manager, or AWS Credential Identity Provider to access shared credentials:

import{fromIni}from'aws-sdk/credential-providers';constoptions={bucket:'<AWS_S3_BUCKET>',s3overrides:{credentials:fromIni({profile:'<AWS_CLIENT_PROFILE>'})}};