Spaces
In this document, you’ll learn how to install the Spaces plugin on your Medusa backend and use it for storage.
Overview
To manage images in Medusa, you need a file service plugin responsible for hosting the images. Without a file service plugin, you will face issues while working with Medusa, such as when uploading images for products.
Medusa provides three different options to handle your file storage. This document focuses on using Spaces to store images and files uploaded to the Medusa backend.
Prerequisites
Medusa Backend
A Medusa backend is required to be set up before following along with this document. You can follow the quickstart guide to get started in minutes.
Required Accounts
You need to create a DigitalOcean account to follow along with this documentation. A credit card is required during registration.
Create DigitalOcean Spaces Bucket
On your DigitalOcean dashboard:
- Click on the Create button at the top right.
- Choose "Spaces Object Storage" from the dropdown.
- In the Create a Spaces Bucket form:
- You can choose any of the datacenter regions listed.
- In the Finalize and Create section, enter a name for the field “Choose a unique Spaces Bucket name”. You’ll use this name later in the integration with Medusa.
- For the "Select a project" input, select the project you want to add the new Spaces Bucket to.
- Once you’re done, click on the "Create a Spaces Bucket" button.
Your Spaces Bucket is then created and you're redirected to its page.
Create Space Access Keys
- Choose API from the bottom of the sidebar.
- This opens the Application & API page. Choose the "Spaces Keys" tab.
- Click on the "Generate New Key" button.
- In the pop-up, enter a name for the access key and click Create Access Key.
- Then, in the table, you'll find a new key added where you can copy the secret and access keys.
The secret access key won't be shown again after you leave the page. Make sure to copy it when you see it or you’ll need to re-generate a new one.
Install the Spaces Plugin
In the directory of your Medusa backend, run the following command to install the Spaces plugin:
Then, add the following environment variables:
Where:
<YOUR_SPACE_URL>
is either the Origin Endpoint or the CDN endpoint of your Spaces Object Storage bucket.<YOUR_SPACE_NAME>
is the name of your Spaces Object Storage bucket.<YOUR_SPACE_REGION>
is the region your Spaces Object Storage bucket is in. If you're unsure, you can find it in the Origin Endpoint whose format ishttps://<bucket-name>.<region>.digitaloceanspaces.com
. For example,nyc3
.<YOUR_SPACE_ENDPOINT>
is of the formathttps://<region>.digitaloceanspaces.com
. For example,https://nyc3.digitaloceanspaces.com
.<YOUR_ACCESS_KEY_ID>
and<YOUR_SECRET_ACCESS_KEY>
are the keys you created in the previous section.
Finally, in medusa-config.js
add a new item to the plugins
array:
const plugins = [
// ...
{
resolve: `medusa-file-spaces`,
options: {
spaces_url: process.env.SPACE_URL,
bucket: process.env.SPACE_BUCKET,
region: process.env.SPACE_REGION,
endpoint: process.env.SPACE_ENDPOINT,
access_key_id: process.env.SPACE_ACCESS_KEY_ID,
secret_access_key: process.env.SPACE_SECRET_ACCESS_KEY,
},
},
]
If you have multiple storage plugins configured, the last plugin declared in the medusa-config.js
file will be used.
Optional Configuration
The plugin also accepts the following optional configuration:
downloadUrlDuration
: A number indicating the expiry time in seconds of presigned download URLs.
Test the Space Plugin
Run your Medusa backend with the following command:
Then, you can either test the plugin using the REST APIs or using the Medusa Admin.
On the Medusa Admin, create a new product and, in the Images section, upload an image then click Save. If the integration was successful, the product image will be uploaded successfully.
You can also check that the image was uploaded on the Space’s page.
Next.js Starter Template Configuration
If you’re using a Next.js Starter Template, you need to add an additional configuration that adds the Space’s domain name into the configured images’ domain names. This is because all URLs of product images will be from the Space.
If this configuration is not added, you’ll receive the error "next/image Un-configured Host”.
In next.config.js
add the following option in the exported object:
Where <YOUR_SPACE_URL>
is the domain name for your Space Origin Endpoint or CDN endpoint. It's of the format <bucket-name>.<region>.digitaloceanspaces.com
or <bucket-name>.<region>.cdn.digitaloceanspaces.com
See Also
- Check out more plugins you can add to your store
- Deploy the Medusa backend on DigitalOcean
- Install the Next.js Starter Template