Configure your AWS S3 bucket
This feature is only available on Beefree SDK paid plans.
Custom S3 Bucket is a Beefree application configuration feature that allows you to easily connect your own Amazon Web Services S3 bucket to your Beefree application.
By leveraging this feature, you will be able to store and manage your customers’ assets without having to build a new File System Provider, but rather by providing a compliant folder structure and filling out a simple form.
How are images stored?
Our default file system provider uses two first level folders to manage assets:
Images folder – It defines where the user’s images will be stored.
Thumbnails folder – Is used by our API to store the thumbnails of the uploaded images.
These folders can be root folders or can be part of a more complex directory structure.
A few notes and recommendations:
These folders should not be parents/children between themselves.
Their name is restricted by AWS standard naming restrictions.
For performance reasons, you should use a dedicated bucket and place these folders in the root.
The S3 bucket must be publicly accessible.
The S3 bucket Access Control List (ACL) should ensure “List objects, Write objects, and Write bucket permissions” are disabled for the Everyone user.
Shared Assets
As an additional configuration option, you can provide shared files to your users, something that we do in the free version of the Beefree editor at beefree.io. These images are shown to all your customers as read-only assets.
The most common use case is providing sample images for the user’s first experience with the editor. Other use cases include providing application-specific images or documents that must not be deleted by the user.
To use this option you need to set-up two additional folders:
Shared images folder – This is the folder that your users will browse through the file manager.
Shared thumbnails folder – While the user images thumbnails are created when the images are uploaded, there is no automatic thumbnail creation for shared images. You must provide your own thumbnails using these settings:
200px as max. width/height (this guarantee a correct preview in the file manager)
Name: original_image_name.ext_thumb.png (so the thumbnail for cat.jpg must be cat.jpg_thumb.png)
PNG: use only PNG as image format
S3 configuration
This section discusses how you can configure your own custom S3 bucket within the Developer Console, and also provides an example JSON of the Permission policy.
Configure Access keys in the Developer Console
Prior to configuring your custom S3 bucket, ensure you configure Access keys in the Developer Console.
Take the following steps to configure Access keys in the Developer Console:
Log in to the Developer Console.
Navigate to the application you'd like to configure a custom S3 bucket for.
Click the Details button for that application.
Navigate to Application configuration and click View more.
You will be redirected to Storage options.
Toggle on Configure your own S3 storage system to enable the option.
Complete the required fields.*
Click the Test S3 settings button.
*The following image shows an example of the required fields within the Developer Console for configuring your own S3 bucket:
JSON of the Permissions policy
The following JSON is of the Permissions policy assigned to the AWS user.
Note: Images path and Thumbs path must be valid directories in the bucket.
Enabling the Move File Feature for Your File Manager
You can enable the move icon for files within the File manager. This move icon allows your end users to move their files between folders, locations, and so on within the File manger. They can access the move icon directly on the file within the File manager. The move icon is a folder with an arrow pointing right inside it. End users click this icon to initiate the process of relocating the corresponding file to a new destination.
If you are using a Custom AWS S3 Bucket, take the following steps to enable this feature for your File manager.
Using a Custom AWS S3 Bucket
To implement the new Move File feature in your application, follow these steps to change your file path from the old format to the new format. This change is important because it allows the host application to enable the Move File feature within the File Manager without breaking old URLs. Here's how to make the transition:
Understand the Changes: The file paths will change from
/your-path/UID/user-path/filename.jpg
to/your-path/new-internal-id/random-path/filename.jpg
. This new structure decouples the logical path you see in the File Manager from the physical path in the storage, supporting the "move file" feature. For example, you can move the file in the File Manager, and the URL will remain the same.Activate Move Feature: Once you are onboarded, activate the Move Feature inside your SDK Console to utilize the new file paths. Follow the steps outlined in the previous section to complete this process.
Why This Change is Important
Decoupling Logical and Physical Paths: The new path structure separates the logical path (what you see in the File Manager) from the physical path (where the file is stored). This allows for more flexibility and new opportunities for future features.
Enable the Move File Feature: By adopting the new path structure, you can use the Move File feature in the File Manager, which allows you to move files without changing their URLs.
Impact on Existing Data
Existing Paths: Existing paths are not affected. The task done was to collect paths in the new database and keep files where they are.
Newly Uploaded Files: New uploaded files will be stored using the new path structure.
About the New Path
Logical and Physical Path Separation: The new path structure decouples the logical path you see in the File Manager from the physical path in the storage. This supports the "move file" feature, allowing you to move files in the File Manager without changing their URLs.
Changes: The key difference between the two paths is that the new path uses a random part to enhance security and reduce predictability, making it harder for unauthorized users to guess the URLs of stored files.
By following these steps, you can ensure a smooth transition to the new file paths and take full advantage of the Move File feature in your application.
Filling out the form to connect your AWS S3 bucket
Once you have set up a compliant folder structure, you can use the form in the Beefree SDK Console to connect your application. It’s one of the available server-side configurations for your Beefree application (Application details > Open configuration > Storage options).
This is a description of the form fields and what information you will need to provide in each of them:
Parameter | Description | Required |
---|---|---|
Custom url | The hostname – typically a CDN – that will be prefixed to resources URLs referenced in the JSONs created with BEE. | No |
Bucket name | The name you assigned to the bucket when you created it. | Yes |
Access key & Access secret key | You can provide AWS Root Account Credentials or IAM User Credentials (we recommend the second option for security reasons). The provided account must have read and write access to the given bucket. More about AWS credentials. | Yes |
Select Region | AWS region where you created the bucket. Uses EU as the default setting. | Yes |
Images Path | The relative path (from the bucket root) to the images folder described above (use “/” symbol as path delimiter). | Yes |
Thumbnails Path | The relative path (from the bucket root) to the thumbnails folder described above (use “/” symbol as path delimiter). | Yes |
Shared images path | The relative path (from the bucket root) to the shared images folder described above. Cannot be the bucket root (use “/” symbol as path delimiter). | No |
Shared thumbnails Path | The relative path (from the bucket root) to the shared thumbnails folder described above. Cannot be the bucket root (use “/” symbol as path delimiter). | No |
Please note that the Custom url configuration is not retroactive, so messages and pages saved before this configuration is added will keep the assets under the old URLs.
Example using single folders in the bucket root:
Example using single nested folders:
Testing your settings
The button will become active once all required fields have been correctly filled out. It allows you to test your settings before saving the updated configuration. We recommend that you do so before saving any changes.
Remember to save your changes with the SAVE button at the top.
Preparing thumbnails
If you’ve just linked your custom bucket, you may find that you need to create your own thumbnails. Thankfully, this is an easy process.
For starters, the thumbnails in the File Manager are PNG files that are resized to 200×200 px.
Here is an example of thumbnail generation with image magick:
As a quick example, we’ll be using this custom bucket configuration:
bucket_name :
my-custom-bucket
path_images :
/path/to/images/
path_thumbnails :
/path/to/thumbnails/
…And starting the editor with this UID:
uid :
my-uid
When uploading image1.jpg
in root dir, this key will be created in the custom bucket: s3://my-custom-bucket/path/to/images/my-uid/image1.jpg
. Following that, a thumbnail will be generated with name image1.jpg_thumb.png
with key: s3://my-custom-bucket/path/to/thumbnails/my-uid/image1.jpg_thumb.png
.
And one more example:
When uploading image2.jpg
in mydir
inside the root dir, this key is created in the custom bucket: s3://my-custom-bucket/path/to/images/my-uid/mydir/image2.jpg
. Similarly to above, a thumbnail will be generated with name image2.jpg_thumb.png
with key: s3://my-custom-bucket/path/to/thumbnails/my-uid/mydir/image2.jpg_thumb.png
.
Moving from the default S3 bucket
If your Beefree application is currently using the default S3 bucket, you wish to switch to your own bucket, and you have files that you want to transfer between the two, please please log into the Beefree SDK Console and submit a support ticket.
Last updated