Documentation

Hosting on DigitalOcean Spaces

DigitalOcean Spaces is an S3-compatible object storage service. It works well with Surreal CMS because publishing a static website is just writing files, like index.html, about.html, images, and stylesheets. This page walks you through creating a bucket in the DigitalOcean control panel, connecting it to Surreal CMS, and putting your own domain in front of it.

Spaces stores files, it doesn't host websites

A Spaces bucket will happily serve https://www.example.com/index.html, but on a custom domain it won't serve index.html when someone visits https://www.example.com/. Something has to sit in front of the bucket to do that. This guide uses a small Cloudflare Worker, which is one of the two options DigitalOcean's documentation lists for using Cloudflare with Spaces.


Before you start

All of the following need to be true before you begin:

  • You have a DigitalOcean account. Your first bucket starts a Spaces subscription, which is $5 per month.
  • Your website's domain is an Active zone on a Cloudflare account. The free plan is fine. If you'd rather not use Cloudflare, see Alternative: A Spaces CDN subdomain below, but read about its limitations first.
  • You're using one bucket per website. Every file Surreal CMS publishes is public, so don't store drafts, backups, or anything private in it.

How the pieces fit together

Spaces bucket Stores the files Surreal CMS publishes and serves them at its origin endpoint, e.g. https://my-website.nyc3.digitaloceanspaces.com/index.html
Access key Lets Surreal CMS read and write files in that one bucket
Cloudflare Worker Answers requests for your domain by fetching files from the bucket. It makes / load index.html and shows your 404.html when a file is missing.
Worker custom domain Connects the Worker to www.example.com. Cloudflare creates the DNS record and the SSL certificate for you.

1. Create the bucket

Log in at cloud.digitalocean.com.

  1. In the left menu, select Spaces Object Storage, then select Create Bucket in the top right.
  2. Under Choose a datacenter region, pick the region closest to most of your visitors.
  3. Under Choose a Storage type, select Standard Storage.
  4. Under Content Delivery Network (CDN), leave the CDN disabled. Cloudflare takes its place in this setup, and DigitalOcean doesn't support using the Spaces CDN and another vendor's CDN on the same bucket.
  5. Choose a unique bucket name. Names are 3–63 characters, begin with a letter or number, and contain only lowercase letters, numbers, and dashes, e.g. my-website. The name has to be unique across all of DigitalOcean, not just your account.
  6. Select a project, review the summary, and select Create a Spaces Bucket.

Region, name, and storage type are permanent

None of these can be changed after the bucket is created, and the name and region both become part of the bucket's address. Don't choose Cold Storage. Cold buckets can only be read with signed requests, so they can't serve a public website.

You'll land on the bucket's Files tab. Note the origin endpoint shown in the top right of the page. It looks like https://my-website.nyc3.digitaloceanspaces.com. The first part is your bucket name and the second part, nyc3 in this example, is your region. You'll need both later.

Next, open the bucket's Settings tab and look at the File Listing section. It should be set to Restrict File Listing, which is the default. This stops anonymous visitors from getting a list of every file in your bucket, and it doesn't affect access to the files themselves.


2. Create an access key

Surreal CMS needs an access key to read and write files in your bucket.

  1. In the left menu, select Spaces Object Storage, open the Access Keys tab, and select Create Access Key.
  2. For the access scope, choose Limited access.
  3. Select the bucket you just created and set its Permissions to Read/Write/Delete.
  4. Give the key a name, e.g. surreal-cms, and select Create Access Key.
  5. Copy the access key and the secret key. The secret is only shown once.

A limited access key can do everything Surreal CMS needs and nothing else. It can't see your other buckets, and it can't change the bucket's settings.


3. Add your files

Upload your website from the bucket's Files tab. Keep the same folder structure your pages expect, with index.html at the top level. If you plan to use a custom 404 page, add 404.html too. This is also a good time to create the folder Surreal CMS will store uploads in. Choose Actions › Create Folder and name it uploads.

The control panel is fine for a small website, but DigitalOcean limits it to batches of fewer than 100 files. For anything larger, use a file transfer app that supports S3-compatible storage, or upload from the command line as shown in Hosting an Agent-Built Website on DigitalOcean Spaces.

Files you upload by hand are private

Files in a Spaces bucket are Private by default, and visitors can't load a private file. When you upload through the DigitalOcean control panel, choose Public in the upload window's file permissions section. To fix files that are already uploaded, select them, choose Actions › Manage Permissions, select Public, and then Update. You don't need to do this for anything Surreal CMS publishes or uploads. It makes those files public automatically.

To confirm everything is readable, open your origin endpoint followed by /index.html in a browser, e.g. https://my-website.nyc3.digitaloceanspaces.com/index.html. You should see your homepage. If you see an error instead, the file is probably still private.


4. Connect your website to Surreal CMS

Log in to Surreal CMS, then select New Site on the Sites page. Choose DigitalOcean Spaces for the protocol and fill out the form.

Name The name you want to use for your website. (Only used in the CMS.)
URL The domain your visitors will use, e.g. https://www.example.com/

Important! Use your own domain here, not the digitaloceanspaces.com endpoint.
Protocol DigitalOcean Spaces
Region The region from your origin endpoint, e.g. nyc3. Enter just the region, not the whole URL.
Bucket The exact name of the bucket you created.
Access Key The access key you created above.
Secret Access Key The secret key you created above.
Home Folder The folder that contains your homepage. Use the Browse button to navigate to it. For a bucket that holds a single website, this is the root of the bucket, so you can leave it blank.
Upload Folder The folder that uploaded files will be stored in. It has to be inside your home folder. Users can upload, rename, move, and delete anything inside this folder, but nothing outside of it, so don't select one that contains webpages or other important files. Create a folder called uploads for this purpose. See best practices for why.

Select Test Connection to make sure everything works. If all goes well, you'll see Connection successful!

If the connection fails, double check the region and bucket name, and make sure the access key has Read/Write/Delete permission for this bucket.


5. Put your domain in front of the bucket

Unlike everything above, this step happens in Cloudflare. Log in at dash.cloudflare.com and go to Workers & Pages. Create a new Worker from the "Hello World" starter, give it a name such as my-website, and deploy it. Then edit its code, replace everything with the following, and deploy again. Change the first line to your bucket's origin endpoint, with no slash at the end.

const ORIGIN = 'https://my-website.nyc3.digitaloceanspaces.com';
const CLEAN_URLS = false;

export default {
  async fetch(request) {
    if (request.method !== 'GET' && request.method !== 'HEAD') {
      return new Response('Method not allowed', { status: 405, headers: { Allow: 'GET, HEAD' } });
    }

    // "/" becomes "/index.html" and "/blog/" becomes "/blog/index.html"
    let path = new URL(request.url).pathname;
    if (path.endsWith('/')) {
      path += 'index.html';
    } else if (CLEAN_URLS && !path.split('/').pop().includes('.')) {
      path += '.html';
    }

    // Pass along the headers browsers use for caching and media playback
    const headers = new Headers();
    for (const name of ['If-None-Match', 'If-Modified-Since', 'Range']) {
      if (request.headers.has(name)) headers.set(name, request.headers.get(name));
    }

    const response = await fetch(ORIGIN + path, { method: request.method, headers });

    // Show 404.html instead of the bucket's XML error when a file is missing
    if (response.status === 403 || response.status === 404) {
      const notFound = await fetch(ORIGIN + '/404.html');
      return new Response(notFound.ok ? notFound.body : 'Not found', {
        status: 404,
        headers: { 'Content-Type': 'text/html; charset=utf-8' }
      });
    }

    // Let the Surreal CMS editor load fonts and scripts from your domain
    const result = new Response(response.body, response);
    result.headers.set('Access-Control-Allow-Origin', '*');
    return result;
  }
};

Now connect the Worker to your domain:

  1. Open the Worker and go to Settings › Domains & Routes.
  2. Select Add › Custom Domain.
  3. Enter the hostname by itself, e.g. www.example.com, and select Add Custom Domain.

Cloudflare creates the DNS record and issues the certificate for you. If the hostname already has a CNAME record, Cloudflare won't let you add it. Delete the old record from your domain's DNS settings first, then try again.

Once the domain is active, https://www.example.com/ serves index.html, and https://www.example.com/blog/ serves blog/index.html. Folder URLs need the trailing slash, because /blog on its own won't find blog/index.html, so include the slash when you link to a folder.

A Worker can have more than one custom domain. If you want both example.com and www.example.com to work, add each one.


Optional: Clean URLs

If you want https://www.example.com/about to serve about.html, change CLEAN_URLS to true in the Worker and deploy it again. The file in your bucket is still named about.html. The Worker only changes what it looks up, so the address bar stays clean.

This applies to any path whose last segment doesn't contain a dot, such as /about and /blog/hello, and leaves /styles.css and /images/logo.png alone. If a page is saved as about/index.html rather than about.html, use /about/ instead.


Fonts and scripts in the editor

Surreal CMS loads your page from its own origin to edit it, so web fonts and JavaScript modules are cross-origin requests in the editor, and browsers block them unless the response allows it. Without that permission, the editor shows your site in a fallback font and type="module" scripts don't run. Visitors aren't affected.

The Worker above handles this. Its last lines copy the bucket's response and add Access-Control-Allow-Origin: * before returning it. If you deployed an older version of the Worker without them, paste the current code in and deploy it again.


Testing your setup

Once everything's in place, check these URLs. Replace the hostname with your own.

/ Your homepage.
/index.html Also your homepage.
/about.html Your about page.
/about Your about page, but only if you turned on clean URLs.
/styles.css Stylesheets, images, and other static files.
/this-does-not-exist Your 404.html, or a plain "Not found" message if you don't have one.

Finally, edit a page in Surreal CMS, publish it, and reload it on your domain. The change should be there right away.


How publishing stays instant

Surreal CMS sends a Cache-Control: no-cache header with every file it uploads to your bucket. Cloudflare never serves a file with that header from its cache without checking your bucket first. That's why your edits show up as soon as you publish, with nothing to purge.

Files you upload through the DigitalOcean control panel don't get that header. Cloudflare doesn't cache HTML by default, but it does cache common static files such as CSS, JavaScript, and images, for two hours, unless the file says otherwise. If you replace one of those by hand and still see the old version, purge it from Cloudflare's cache. When purging a single file, enter the address the Worker fetched, e.g. https://my-website.nyc3.digitaloceanspaces.com/styles.css, not the address on your own domain. Cloudflare stores the file under the bucket's URL. Or skip all of that and replace the file through Surreal CMS instead.


Alternative: A Spaces CDN subdomain

Spaces has a built-in CDN that can serve your bucket from a subdomain you own, without Cloudflare. It's a good way to serve images and downloads, but it has two limitations that make it a poor fit for a whole website edited with Surreal CMS:

  • No index documents. https://www.example.com/index.html works, but https://www.example.com/ doesn't load your homepage. Spaces does have a separate website endpoint that handles this, but DigitalOcean doesn't support the CDN on it, and custom subdomains are a CDN feature.
  • Edits may not be instant. The CDN keeps copies of your files for the length of its Edge Cache TTL. The shortest setting is 1 minute and the default is 1 hour. DigitalOcean doesn't document whether the CDN honors the no-cache header Surreal CMS sends, so plan on visitors seeing the old version until the copy expires or you purge it by hand from the bucket's Settings tab. Surreal CMS can't purge it for you.

If that works for your project, open the bucket's Settings tab, select Edit in the CDN (Content Delivery Network) section, and select Enable CDN. Set the Edge Cache TTL to its shortest setting, then select Add a New Subdomain. Every subdomain needs an SSL certificate, and there are two ways to get one:

Use Let's Encrypt Free and renewed automatically, but only available when DigitalOcean manages your domain's DNS. DigitalOcean creates the DNS record for you.
Bring your own certificate For domains whose DNS is hosted elsewhere. You paste in a certificate, private key, and certificate chain, and you're responsible for renewing it. Cloudflare Origin CA certificates aren't accepted. At your DNS provider, create a CNAME record that points the subdomain to your bucket's CDN endpoint, e.g. my-website.nyc3.cdn.digitaloceanspaces.com.

Don't combine this with the Cloudflare Worker above. Use one or the other.


Performance and cost

A Spaces subscription is $5 per month and covers all of your buckets. It includes 250 GiB of storage and 1,024 GiB of outbound transfer. Beyond that, storage is $0.02 per GiB and transfer is $0.01 per GiB. Billing starts with your first bucket and stops when you destroy your last one.

On the Cloudflare side, every request to your website runs the Worker, including pages, images, and stylesheets. The Workers Free plan allows 100,000 requests per day, which resets at midnight UTC. If you go over, visitors see a Cloudflare error page until the reset. A typical brochure website stays within the limit, but a busy or image-heavy one needs the Workers Paid plan.

Your bucket lives in one region, so a visitor on the other side of the world waits on that region for every page. New buckets handle up to 800 operations per second, which is far more than a typical website needs.

A few other things worth knowing: your files are also reachable at the bucket's origin endpoint, there's no atomic deploy or preview URL since publishing overwrites files in place, and your domain has to stay on Cloudflare for the Worker to keep running.


Should you use Spaces?

Spaces is a good fit if you're already a DigitalOcean customer and want an S3-style workflow. Connect a bucket, publish files, and serve them on your domain.

If you're starting from scratch, consider Cloudflare R2 instead. This setup already depends on Cloudflare for your domain, and R2 gets you the same result with a couple of rules instead of a Worker.


Checklist

  • One bucket per website, Standard Storage, CDN disabled, with the region chosen deliberately
  • File listing set to Restrict File Listing
  • A limited access key with Read/Write/Delete permission for that bucket only
  • Any files uploaded by hand set to Public, with /index.html loading from the origin endpoint, and an uploads folder
  • A Cloudflare Worker pointing at your origin endpoint, connected to your hostname as a custom domain
  • Optionally, CLEAN_URLS turned on and a 404.html in the bucket
  • No private files in the bucket

If you run into trouble getting connected, feel free to contact us for help!