An Introduction to DigitalOcean Spaces
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.
- 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:
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.
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:
- 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.
- 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.
- 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.
The Files Tab
One the Files tab, there are five main things you can do:
- Upload files
- Create new folders
- Manage multiple files in the current folder
- Filter existing files in the current folder
- 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.
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.
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:
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.
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.
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.
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.
5 — Managing Individual Files and Folders
An individual file's More menu to allows you to manage several things.
Manage Permissions lets you toggle between public and private visibility for the file:
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.
Selecting Rename will open the filename in an editable text box.
Selecting Move to Folder will allow you to navigate the Space as well as create new folders.
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.
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
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.
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.
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:
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.
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.
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.
Last updated 19 Sept 2017 at 7:30pm EST
Known issues and bugs you may encounter when using Spaces include:
- Transmit 5 does not work with Spaces. Please use Transmit 4 as a workaround.
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
- Space actions (create/delete) do not include the IP address that conducted the action
- 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)
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.
- More regions
- Set a CNAME directly for a Space
- Static website hosting
- Replication between Spaces regions
- Access logging
- 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: