Cloud Storage Support

In addition to storing your music on the same server as Koel’s installation via the local storage drivers, Koel Plus offers several different file storage options, including SFTP, Amazon S3, S3-compatible services, Dropbox, and likely more in the future. This page will guide you through the process of setting up these storage options.

Warning

Though possible, changing storage drivers after you've already stored files is not recommended, as it may break links to your existing media.

Service UI may change

The screenshots and instructions on this page may not be 100% up-to-date as 3rd-party services' UI may change. The general idea, however, should remain the same.

SFTP

To use SFTP as your storage driver, you need to have an SFTP server set up and running. Many cloud hosting providers offer SFTP access to their storage services. To enable SFTP storage support in Koel, you need to provide the following configuration in your .env file:

STORAGE_DRIVER=sftp

SFTP_HOST=
SFTP_PORT=

# The absolute path of the directory to store the media files on the SFTP server.
# Make sure the directory exists and is writable by the SFTP user.
SFTP_ROOT=

# You can use either a username/password pair…
SFTP_USERNAME=
SFTP_PASSWORD=

# …or private key authentication:
SFTP_PRIVATE_KEY=
SFTP_PASSPHRASE=

After reloading, Koel will start using SFTP as its storage driver. You can now upload your music files to your SFTP server directly from Koel’s web interface.

Amazon S3 and Compatible Services

Since Amazon S3 and S3-compatible services share the same API, you can use the same configuration (AWS_*) for both. Koel has been tested with Amazon S3, DigitalOcean Spaces, and Cloudflare R2, but it should work with any S3-compatible service given the right configuration.

Amazon S3

Create a new S3 bucket and obtain your access key ID and secret key from the AWS console. Then, populate these values in your .env file:

STORAGE_DRIVER=s3

AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=
AWS_ENDPOINT=
AWS_BUCKET=

After reloading, Koel will start using S3 as its storage. You can now upload your music files to your S3 bucket directly from Koel’s web interface.

In order to use S3 for streaming, you'll also need to set up a cross-origin resource sharing (CORS) configuration for your bucket by going to the Permissions tab. Here's a sample policy that allows streaming from any origin:

[
    {
        "AllowedHeaders": [],
        "AllowedMethods": [
            "GET"
        ],
        "AllowedOrigins": [
            "*"
        ],
        "ExposeHeaders": []
    }
]

DigitalOcean Spaces

To use DigitalOcean Spaces, you can follow the same steps as with Amazon S3. Below are some screenshots to help you get started.

Create a DigitalOcean Spaces bucket

DigitalOcean Spaces bucket settings with CORS Configurations

The access key ID and secret key can be generated and obtained via the API -> Space Keys tab in the DigitalOcean control panel:

A sample .env configuration for DigitalOcean Spaces may look like this:

STORAGE_DRIVER=s3

AWS_ACCESS_KEY_ID=DO000000000000000000
AWS_SECRET_ACCESS_KEY=TheSecretKeyObtainedFromDO
AWS_REGION=fra1
AWS_ENDPOINT=https://fra1.digitaloceanspaces.com
AWS_BUCKET=koel

Cloudflare R2

Cloudflare R2 is yet another excellent choice for an S3-compatible service. The setup is pretty much similar to the above:

Create a Cloudflare R2 bucket

Cloudflare R2 bucket settings with CORS Policy

A sample .env configuration for Cloudflare R2 may look like this:

STORAGE_DRIVER=s3

AWS_ACCESS_KEY_ID=c50000000000000000
AWS_SECRET_ACCESS_KEY=TheSecretKeyObtainedFromR2
AWS_REGION=auto # Cloudflare R2 explicitly uses the `auto` region
AWS_ENDPOINT=https://fa37a667b0038bbb7054133627ce74b4.r2.cloudflarestorage.com
AWS_BUCKET=koel

Dropbox

Koel Plus also supports using Dropbox as a storage driver, although the setup is a bit different.

1. First, create a new Dropbox app with the "App folder" access type and set up sufficient permissions to read and write files.

   

   Create a Dropbox app

   

   Set sufficient app permissions

2. Under your Dropbox app's Settings tab, make a note of the "App key" and "App secret" values. Now, from the root folder of your Koel installation, run the following command:

   php artisan koel:storage:dropbox

   You'll be prompted to enter the "App key" and "App secret" values obtained earlier.
3. Koel will generate a URL for you to visit and authorize the Dropbox app. Afterward, you'll receive an access code.
4. Enter the access code back into the command line's prompt. Koel will then finalize the setup automatically and start using Dropbox as its storage.

Now when you upload music files to Koel, they'll be stored in your Dropbox app's folder.

Two-way sync not supported

Koel does not support two-way sync with Dropbox — at least not yet. This means manual changes made to your Dropbox folder will not be reflected in Koel.