File System Buckets

When you deploy an application on Clever Cloud, like most PaaS, a new virtual machine is created, the previous one is deleted. If your application generates data, for example if you let users upload pictures and you do not store it on external services like S3, you will lose anything stored on the disk.

The Git deployment does not allow you to keep generated data files between deployments. To avoid the loss of your data, you have to mount a persistent filesystem. This is why we created File System Buckets.

You will be able to retrieve generated data between two deployments.

Configuring your application

Buckets are configured using environment variables. Add the following to your application :

CC_FS_BUCKET=/some/empty/folder:bucket-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-fsbucket.services.clever-cloud.com[:async]

Don’t forget to replace the path of the mounted folder and the fs-bucket host with the targeted folder path (make sure the folder does not exists) and your fs-bucket host.

Optionnally, you can add :async to the end of the environment variable. This will make Clever Cloud mount the FS Bucket with the async option. It will make the FS Bucket faster (sometimes up to 3 times faster), but in case of a network issue it may cause file corruption.

You can setup multiple buckets by appending a number at the end of the environment variable’s name.

CC_FS_BUCKET=/some/empty/folder:fs_bucket_host
CC_FS_BUCKET_1=/some/otherempty/folder:fs_bucket_other_host:async

Note that the async parameter can be set per bucket.

Configuring your application with buckets.json (@deprecated)

To configure your application to use buckets, use the clevercloud/buckets.json file.
The clevercloud folder must be located at the root of your application.
The buckets.json file must contain the following structure:

[
  {
    "bucket" : "bucketId",
    "folder" : "/myFolder",
    "apps"   : ["app_id"]

  },
  {
    "bucket_host" : "bucket-01234567-0123-0123-0123-012345678987-fsbucket.services.clever-cloud.com",
    "folder" : "/myotherFolder",
    "apps"   : ["app_id_2"]
  }
]

It’s a json array containing objects with at least two fields:

The folder must not exist in your repository (or it needs to be empty). Otherwise, the mount of your bucket will be ignored. You can mount the same bucket in different folders, but they will share the same content, so it’s not the solution. You should prefer to mount the bucket in only one folder and then manage multiple subfolders in it.

Accessing your data inside the FS Bucket

From your application

Your bucket is mounted at the configured path, starting from your application’s root folder.

If you want to use an absolute path, you can use the APP_HOME environment variable, see special environment variables

From the addon dashboard

The File explorer tab of the addon dashboard gives you access to your files in the FS bucket.

From your favorite FTP client

The Addon information tab of your FS Bucket add-on displays the information you need to connect to your bucket using FTP.