Using DigitalOcean Spaces in October CMS

Posted in Guide, October CMS on Dec 17, 2020 (updated Dec 17, 2020)

I was tinkering with DigitalOcean's "Spaces", which is an alternative to Amazon's AWS S3 service. The Spaces API is actually compatible with Amazon's AWS S3 API, which makes it super easy to replace S3 with. Since I often use October CMS, I was interested in using DigitalOcean Spaces as a filesystem disk. Since October CMS is built on Laravel, it is quite trivial, with almost no plugins required (with some caveats)!

Want to try out DigitalOcean? Use this referral link to receive $50 in DO credit to use for 30 days. Once you spend $25, I'll get a $25 credit to keep my website online!

2020 Update

I've deprecated my plugin, since October CMS supports this out-of-the-box with their Drivers plugin and some special configuration. You can update your filesystems.php configuration file to look like this:

'disks' => [

    // ...

    'do_spaces' => [
        'driver'     => 's3',
        'endpoint'   => 'https://[your region].digitaloceanpsaces.com'
        'key'        => '[your key]',
        'secret'     => '[your secret key]',
        'region'     => '[your region]',
        'bucket'     => '[your space name]',
        'visibility' => 'public', // Update: this is necessary to make your uploads read-only for anyone
    ],

    // ...

]

It was fun learning how to create plugins for the October CMS ecosystem, and this storage driver plugin was helpful but ultimately unnecessary. However, I've also developed another storage driver plugin for Backblaze's B2 cloud storage.


Quick Start

If you're already familiar with October CMS and how to configure S3 disks, add the endpoint parameter to your filesystem disk, and configure like you would with AWS S3:

'disks' => [

    // ...

    'do_spaces' => [
        'driver'   => 's3',
        'endpoint' => 'https://nyc3.digitaloceanpsaces.com'
        'key'      => 'XXXXXXXXXXXXXXXXXXXX',
        'secret'   => 'xxxXxXX+XxxxxXXxXxxxxxxXxxXXXXXXXxxxX9Xx',
        'region'   => 'nyc3',
        'bucket'   => 'my-bucket'
    ],

    // ...

]

Caveat

Unfortunately, even though uploading files will work, they will be private by default. In order to upload public files using the media manager, you'll need a plugin. I've developed a simple plugin that sets the right access control attribute, making your uploaded files public. Get the DigitalOcean Spaces Storage Driver plugin here. The plugin also makes configuration easier, as you don't have to provide an endpoint parameter.

How To: Use Digital Ocean Spaces with October CMS

If DigitalOcean Spaces and October CMS are new to you, here is a more comprehensive guide.

1. Create a New Space

Login to your DigitalOcean dashboard, and head over to Spaces.

Create a space

Click Create a Space, and fill in the information for your new space. You can also setup a CDN if you use DigitalOcean for DNS.

Creating a new space

2. Generate Access Keys

Now, you'll need an API key to list files, upload, etc. Head over to API to generate a new access key for spaces.

Generate an access key

Click Generate New Key and enter the name for your new key.

Access key

You'll use these keys to connect to the DigitalOcean Spaces API.

3. Configure October CMS

Edit config/filesystems.php and add your Spaces configuration. Make sure your region matches where you created your new space.

'disks' => [

    // ...

    'do_spaces' => [
        'driver'   => 's3',
        'endpoint' => 'https://nyc3.digitaloceanpsaces.com'
        'key'      => 'XXXXXXXXXXXXXXXXXXXX',
        'secret'   => 'xxxXxXX+XxxxxXXxXxxxxxxXxxXXXXXXXxxxX9Xx',
        'region'   => 'nyc3',
        'bucket'   => 'my-bucket'
    ],

    // ...

]

Edit config/cms.php to configure the media manager to use your "do_spaces" disk:

'storage' => [

    // ...

    'media' => [
        'disk'   => 'do_spaces',
        'folder' => '',
        'path'   => 'https://<your space name>.<region>.digitaloceanspaces.com/'
    ],
],

Again, there is the same caveat from the beginning of the post. I've developed a simple plugin that sets the right access control attribute, making your uploaded files public. Get the DigitalOcean Spaces Storage Driver plugin here. The plugin also makes configuration easier, as you don't have to provide an endpoint parameter.

Discussion