We hope you find this tutorial helpful. In addition to guides like this one, we provide simple cloud infrastructure for developers. Learn more →

An Introduction to DigitalOcean Spaces

PostedSeptember 20, 2017 95.3k views DigitalOcean Object Storage Storage

DigitalOcean Spaces are designed to make it easy and cost effective to store and serve massive amounts of data. You can create them in a few seconds and use them immediately with no configuration. Data transfer is automatically secured with HTTPS, and the available storage capacity scales seamlessly.

When Should I Use Spaces?

Spaces are ideal for storing static, unstructured data like audio, video, and images as well as large amounts of text. For structured or dynamic data such as databases or applications written in server-side languages, either local storage or block storage is required. You can visit Object Storage vs. Block Storage Services to learn more about the differences.

DigitalOcean Spaces at a Glance

  • Free trial period: Two months
  • Base price (after trial):
    • Base rate: $5/month
    • Data storage: 250GB
    • Outbound bandwidth from Spaces to the Internet: 1TB
    • No charge for Inbound bandwidth.
  • Overage:
    • Additional storage: $0.02/GB
    • Additional outbound transfer from Spaces to the Internet: $0.01/GB
  • Regional Availability: At launch, Spaces are available in the NYC3 region.
  • Supported Protocols: HTTPS.
  • URL Naming Pattern: spacename.region.digitaloceanspaces.com or region.digitaloceanspaces.com/spacename

Creating and Managing Spaces

There are four main ways to create and manage your Spaces.

  • The DigitalOcean Control Panel: Using the Control Panel allows you to start using Spaces directly in your web browser without any configuration. You may start to reach browser limitations when uploading files larger than 2GB or more than 100 files at a time. To handle these use cases, you may prefer to use a third-party client.

  • Third Party Graphical Tools: Third-party graphical clients allow you to interact with Spaces in similar ways to the Control Panel. They avoid browser limitations but require configuration to connect. These guides show you how to configure and use Transmit 4 (Mac) and Cyberduck 6.2.x (Windows, Mac) with DigitalOcean Spaces.

  • Third Party CLI Tools: Third-party command line tools like s3cmd (Linux, Mac, Bash on Windows) facilitate both personal use and automation. How To Configure s3cmd 2.x To Manage DigitalOcean Spaces will help you get set up while How to Manage DigitalOcean Spaces with s3cmd provides a glossary of commands and examples.

  • The Spaces API: The Spaces API allows you to programmatically create and manage Spaces. It's the recommended way to automate Space usage but requires additional technical skills. See the DigitalOcean Spaces API documentation to get started.

Depending on your needs, you may use one or more of these tools as you work with Spaces. In this guide, we'll provide an overview of the DigitalOcean Control Panel for Spaces.

Managing Spaces in the Control Panel

The Control Panel, as well as many third-party clients, presents files in a Space using the metaphor of folders. This helps people organize and think about their assets.

Object stores, however, are not hierarchical. Instead of using the branching, directory-based structure most users are familiar with, object stores are flat key/value file systems. This gives object stores their characteristic scalability, redundancy, and reliability, but it also means that folders may behave differently when it comes to retrieving information about the system. For example, because folders are implied by the name of the object and don't actually exist, they can't have permissions and can't provide information about what they contain.

Follow the Spaces link in the Control Panel's main navigation to access the overview page which provides an index of an account's Spaces. When there are no Spaces, this page will invite you to create your first Space.

Screenshot of the More menu

You can create a Space at any time from the Create menu by selecting Spaces or, when it is available, by using the Create a space button. Whichever link you use, you'll be taken to the Create a Space page.

Creating New Spaces

Each Space you create within your account has its own URL and can be used as a logical unit for segmenting content. Note, however, that administrative access applies to all Spaces. At this time, per-Space administrative access is not supported.

There are three decisions to make when creating a new Space:

Screenshot of Create a Space screen

  1. Choose a unique name for your Space. The name must be unique among all users in all regions. Names must be lowercase and start with a letter or number. They can be between 3 and 63 characters long and may contain dashes.
  2. Choose a region. Spaces are currently available only in NYC3, so at the moment there's no decision to make. The region options will expand as Spaces become available in more places.
  3. Manage Access. The Space-level access you set here only affects whether the contents of a Space can be listed by anonymous visitors. This is mainly useful for orchestration tools, certain API requests, and applications the use Spaces directly as a backend. It has no effect on the visibility of the files themselves. Once the Space has been created, this choice can be changed on the Settings tab in the Permissions section. See Managing Access to DigitalOcean Spaces for more detail.

When you create a Space, you'll be taken directly to its Files tab, where the files and folders in its root will be displayed.

Screenshot of the Spaces index screen

The Files Tab

One the Files tab, there are five main things you can do:

  1. Upload files
  2. Create new folders
  3. Manage multiple files in the current folder
  4. Filter existing files in the current folder
  5. Manage individual files and folders

1. Upload Files

Clicking the Upload Files button opens a dialog that allows you to add files by dragging and dropping them into the window or by using a system dialog to select them from your local file system.

Screenshot of Upload dialog

Drag and drop allows you to upload nested directory structures, while the system dialog only supports selecting one or more files in a single directory at a time.

The Upload Files dialog remains open after you add a file, allowing you to stage multiple files, set their permissions to private or public as a group, and upload them as a batch. Because of browser limitations, file uploads from the Control Panel work best with files smaller than 2GB and batches of less than 100 files.

Screenshot of staged files with permissions set to Public

Once a file has been staged and uploaded, mousing over its filename provides a Copy link to its URL and displays its permissions and Content-Type metadata.

2. Create New Folders

The New Folder button adds a new folder in the directory you're in and opens a text box where you can fill in its name:

Screenshot of new folder

When you've entered the name, click the checkmark to close the editing box.

3. Manage Multiple Files in the Current Folder

In addition to managing individual files and folders, the Actions menu allows you manage items in bulk. It becomes active when you check two or more items, and the options vary depending on what is selected.

When two or more files are selected and no folders are selected, you can manage permissions and metadata, move files to a folder, or delete them.

Screenshot of options with two files selected.

Because folders don't actually exist on the backend, they can't have permissions or metadata. Consequently, when a folder is part of a selection, only two options are present: Move to Folder and Delete. Deleting a folder will recursively delete all the content inside.

Screenshot of options with a folder nd two files selected

Note: While you can set permissions for all the files in a folder, currently you'll need to use a third-party client to set permissions recursively.

4 — Filter Files in the Current Folder

The Start typing to filter... box performs a "Begins with" filter for the files and folders at the current level. It's especially helpful for folders with a large number of files. Rather than looking for a file by paging down and waiting for more files to load, you can start typing the first few characters of the file's name and progressively filter what is displayed.

Screenshot of the tasks

The filter is limited to the file and folder names as they are displayed in the level we're viewing with an important exception. If you filter by a complete file name when at the root of a Space, it will appear in the results, allowing you to avoid clicking through nested folders to manage a specific file.

For example, say we're trying to view https://space-intro.nyc3.digitaloceanspaces.com/images/thumbnails/sammy10x10.png in a web browser and discover that it's not publicly accessible. We can copy everything after the base URL, https://space-intro.nyc3.digitaloceanspaces.com/, to get its full name, images/thumbnails/sammy10x10.png. At the root of the Space, when we paste the full name into the filter, the file will be returned in the results. Then, we can use its More menu to change its permissions.

Screenshot of a full path filter

5 — Managing Individual Files and Folders

An individual file's More menu to allows you to manage several things.

More menu screenshot

Manage Permissions lets you toggle between public and private visibility for the file:

Screenshot of Permissions radio button

Manage Metadata lets you set the following four attributes and add custom key-value pairs:

Content-Type, also known as the MIME type, helps browsers render content properly. Most of the time, this is automatically detected, but it can be overridden if needed. For a detailed discussion, see Content-Type.

Cache-Control determines how long web browsers and Internet caches can store a copy of the object. The cache time values are specified in seconds. For a detailed discussion, see Web Caching Basics: Terminology, HTTP Headers, and Caching Strategies.

Content-Encoding: For a detailed discussion, see Content Encoding.

Content-Disposition indicates if a regular file should be displayed inline in the web browser or downloaded as an attachment. For detailed discussion, see Content-Disposition.

Add Custom Pairing x-amz-meta- For example, if you are using Spaces with certain CDNs or reverse proxies, you might use the x-amz-meta-surrogate-key to assist with selective cache invalidations.

Screenshot of Metadata dialog

Selecting Rename will open the filename in an editable text box.

Screenshot of Rename edit box

Selecting Move to Folder will allow you to navigate the Space as well as create new folders.

Screenshot of Move to Folder dialog

Quick Share allows you to generate a URL for a private file. The sharing duration can last 1 hour, 6 hours, 1 day, 3 days, or 7 days.

Screenshot of Quick Share dialog

The link includes a Unix timestamp. You can use online tools like EpochConverter to transform the timestamp into a human-readable form. Copy the value after Expires= up to, but not including the ampersand (&) before the word Signature.

welcome.html?AWSAccessKeyId=EXAMPLEGZXANSEEOTKMZ&Expires=1505849630&Signature=ESAMPLE2FKq8CSddX6J%2FR%2BuYfvIYU%3D

Important: This feature is intended to provide time-bound access to a private resource. At this time, the Quick Share link for a public file is the same as the public URL and has no expiration date. If you make the file private, the link would not grant access.

Selecting Download will start a download of the item to your local machine. Depending on your browser's preferences, the download may start automatically or you may be prompted to save the file first.

Screenshot of the downloaded file

Delete removes a file or folder from your Space. Because deletions are permanent, when you select Delete from the More menu, you'll be asked to confirm before the item is actually deleted.

Screenshot of the Delete confirmation

Folders

A folder's More menu provides a subset of the choices described above. You can rename it, move it and all its contents to a new folder, or delete it along with all of its contents:

Screenshot of an example folder displaying the options listed above

The Settings Tab

The settings page displays the Endpoint value for a Space, which is used to configure third-party clients. From here you can also change the permissions for listing files. This doesn't affect the visibility of the files themselves. You can also permanently destroy the Space and all of its contents.

Screenshot of the Settings tab

The Spaces Index Page

When you have created at least one Space, the Spaces link in the main navigation bar of the Spaces page will display all of your Spaces.

From here, you can see the name, size, and creation date of each Space. Clicking the name will take you to a Space's Files tab. Each Space has a More menu. Show files will also lead you to the Space's Files tab, while both Settings and Destroy will take you to the Settings tab.

In addition, a Manage Keys shortcut is available, which leads to the Applications & API page.
Screenshot of the Spaces index when a Space exists showing the Manage Keys button in the upper right

You can also access the Applications & API page at any time by following API link in the main navigation bar.

Access keys are one of two ways that you can share the administration of your Spaces.

Sharing Administrative Access to Spaces

If an owner wants to allow one or more people to co-manage Spaces, there are two distinctly different ways: access keys and DigitalOcean Teams.

Access keys allow people or programs to connect to Spaces with third-party clients and the API. The privileges granted by Spaces access keys do not provide access to the Control Panel and do not extend to other DigitalOcean resources. See Managing Access to DigitalOcean Spaces for detailed directions on how to create and manage access keys.

DigitalOcean Teams, on the other hand, allow owners and members to use the Control Panel to create and manage Spaces, as well as to create Spaces access keys. In addition, team members can administer other DigitalOcean resources like billing information, Droplets, Load Balancers, Cloud Firewalls and more. See How To Use Teams on DigitalOcean for more detail.

Known Issues

Last updated 19 Sept 2017 at 7:30pm EST

Known issues and bugs you may encounter when using Spaces include:

Third-party clients

  • Transmit 5 does not work with Spaces. Please use Transmit 4 as a workaround.

API

  • List-objects-v2 pagination does not work

  • Spaces currently supports v2 of pre-signed URL functionality. Tools and libraries that only support v4 of pre-signed URL functionality will not work.

  • Updates to Space permissions with 3rd party clients are not reflected in the ‘Settings’ tab of a Space

Security history

  • Space actions (create/delete) do not include the IP address that conducted the action

cloud.digitalocean.com

  • Uploading hundreds or thousands of files via cloud.digitalocean.com may not complete reliably. (For this use case, leverage s3cmd or other 3rd party tools mentioned in this tutorial)

Feature Requests

During the Spaces Early Access period, participants identified several features of interest we're considering for future releases. Is there something you'd like to see on this list? Let us know on UserVoice.

General

  • More regions
  • Set a CNAME directly for a Space
  • Static website hosting
  • Replication between Spaces regions
  • Access logging

Cloud UI

  • Manage files recursively (metadata, permissions, etc.)
  • Move files between buckets
  • Set the default permissions for files at the account level; must be set on every upload
  • Enable sorting in File browser

Where to Go From Here

In this article, we've provided a general overview of DigitalOcean Spaces and how to create and manage them from the Control Panel. For more specific information about other ways of working with Spaces, check out the guides below:

Creating your First Space with the Control Panel:

The guide How To Create your First DigitalOcean Space has step-by-step directions on using the Control Panel to create a Space.

Managing Spaces with 3rd party tools:

Managing Spaces with the DigitalOcean API:

29 Comments

Creative Commons License