diff --git a/docs/content/add-plugins/s3.md b/docs/content/add-plugins/s3.md index 9aa7fd50a0..13277caf64 100644 --- a/docs/content/add-plugins/s3.md +++ b/docs/content/add-plugins/s3.md @@ -124,6 +124,12 @@ const plugins = [ ]; ``` +:::caution + +If you have multiple storage plugins configured, the last plugin declared in the `medusa-config.js` file will be used. + +::: + ## Test the S3 Plugin Run your Medusa server with the following command: diff --git a/docs/content/add-plugins/spaces.md b/docs/content/add-plugins/spaces.md index 38a73588c0..1d3d37916b 100644 --- a/docs/content/add-plugins/spaces.md +++ b/docs/content/add-plugins/spaces.md @@ -1,6 +1,6 @@ # Spaces -In order to work with images in Medusa, you need a file service plugin responsible for hosting. Following this guide will allow you to upload images to DigitalOcean Spaces. +In this document, you’ll learn how to install the [Spaces plugin](https://github.com/medusajs/medusa/tree/master/packages/medusa-file-spaces) on your Medusa server and use it for storage.
-### Before you start +## Overview -At this point, you should have an instance of our store engine running. If not, we have a [full guide](https://docs.medusajs.com/tutorial/set-up-your-development-environment) for setting up your local environment. +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. -### Set up DigitalOcean +Medusa provides three different options to handle your file storage. This document focuses on using [Spaces](https://www.digitalocean.com/products/spaces) to store your Medusa server’s images. -#### Create a Space +## Prerequisites -Create an account on DigitalOcean and navigate to Spaces. Create a new Space with the default settings. +### Medusa Server -#### Generate access keys +A Medusa server is required to be set up before following along with this document. You can follow the [quickstart guide](../quickstart/quick-start.md) to get started in minutes. -Navigate to API in the left sidebar. Generate a new Spaces access key. This should provide you with an access key id and a secret key. Note them both down. +### Required Accounts -### Installation +You need to [create a DigitalOcean account](https://cloud.digitalocean.com/registrations/new) to follow along with this documentation. A credit card is required during registration. -First, install the plugin using your preferred package manager: +## Create DigitalOcean Space + +In your DigitalOcean account, click on the Create button at the top right, then choose Spaces from the dropdown. + +![Click on the green Create button at the top right, then choose Spaces in the dropdown](https://i.imgur.com/AQqMRoJ.png) + +In the Create a Space form, you can choose any of the regions listed. You can alternatively leave all settings as they are and scroll down to the Finalize and Create section. + +![The Space form can be left as is and move towards the Finalize and Create section](https://i.imgur.com/ipsIqoA.png) + +In the Finalize and Create section, enter a name for the field “Choose a unique name”. You’ll use this name later in the integration with Medusa. Also, select the project you want to add the new Space to. + +![Enter a name for the Space in the Choose a unique name field](https://i.imgur.com/NhlRX0h.png) + +Once you’re done, click on the Create a Space button. This creates the Space and redirects you to the Space’s page. + +## Create Space Access Keys + +Choose API from the bottom of the sidebar. + +![Choose API from the bottom of the sidebar.](https://i.imgur.com/6zNoDOW.png) + +This opens the Application & API page. Scroll down to Spaces Access Keys and click the Generate New Key button. + +![In the Spaces access keys section, click the Generate New Key button](https://i.imgur.com/NUocdgh.png) + +This shows a table with the Name field editable. Enter a name for the Access Keys and click on the checkmark button to save and generate the Spaces access keys. + +![Enter a name for the Space access key in the field under the Name column](https://i.imgur.com/ihJBx0T.png) + +Then, two keys will be available under the Key column of the table. The first one is the Access Key ID and the second is the Secret Access Key. Copy both as you’ll use them later. + +:::caution + +The secret access key will not 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 server, run the following command to install the Spaces plugin: ```bash npm2yarn npm install medusa-file-spaces ``` -Then configure your `medusa-config.js` to include the plugin alongside the required options: +Then, add the following environment variables: -```=javascript -{ - resolve: `medusa-file-spaces`, - options: { - spaces_url: "https://test.fra1.digitaloceanspaces.com", - bucket: "test", - endpoint: "fra1.digitaloceanspaces.com", - access_key_id: "YOUR-ACCESS-KEY", - secret_access_key: "YOUR-SECRET-KEY", - }, -}, +```bash +SPACE_URL= +SPACE_BUCKET= +SPACE_ENDPOINT= +SPACE_ACCESS_KEY_ID= +SPACE_SECRET_ACCESS_KEY= ``` -In the above options, a `spaces_url` is included. This can be found in your Space overview. The `bucket` should point to the name you gave your Space. The `endpoint` identifies the region in which you created the Space. And finally the two keys are the ones created in the previous section. +Where: -:::tip +1. `` is the URL of your Space which you can find on the Space’s page below the Space’s name. -Make sure to use an environment variable for the secret key in a live environment. +![The URL is available under the Space's name on the Space's page](https://i.imgur.com/cA3vkvh.png) -::: +2. `` is the name of your Space. +3. `` is your Space’s endpoint which can be found by going to your Space’s page, clicking on the Settings tab, and scrolling to the Endpoint section. + +![Endpoint can be found on the Settings tab in the Space's page](https://i.imgur.com/CnvLr6R.png) + +4. `` and `` are the keys you created in the previous section. + +Finally, in `medusa-config.js` add a new item to the `plugins` array: + +```jsx +const plugins = [ + //... + { + resolve: `medusa-file-spaces`, + options: { + spaces_url: process.env.SPACE_URL, + bucket: process.env.SPACE_BUCKET, + endpoint: process.env.SPACE_ENDPOINT, + access_key_id: process.env.SPACE_ACCESS_KEY_ID, + secret_access_key: process.env.SPACE_SECRET_ACCESS_KEY, + }, + }, +]; +``` :::caution -If you have multiple storage plugins configured, the last plugin declared in the `medusa-config.js` file will be used. +If you have multiple storage plugins configured, the last plugin declared in the `medusa-config.js` file will be used. ::: -### Try it out! +## Test the Space Plugin -Finally, run your Medusa server alongside our admin system to try out your new file service. Upon editing or creating products, you can now upload thumbnails and images, that are stored in DigitalOcean Spaces. +Run your Medusa server with the following command: + +```bash npm2yarn +npm run start +``` + +Then, you can either test the plugin using the [REST APIs](https://docs.medusajs.com/api/store) or using the [Medusa Admin](../admin/quickstart.md). + +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. + +![Image successfully uploaded on Medusa's admin](https://i.imgur.com/oTi4jIw.png) + +You can also check that the image was uploaded on the Space’s page. + +![Image can be seen on the Space's page on DigitalOcean](https://i.imgur.com/BexmRkg.png) + +## Next.js Storefront Configuration + +If you’re using a [Next.js](../starters/nextjs-medusa-starter.md) storefront, 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”](https://nextjs.org/docs/messages/next-image-unconfigured-host). + +In `next.config.js` add the following option in the exported object: + +```jsx +module.exports = withStoreConfig({ + //... + images: { + domains: [ + //... + "" + ], + }, +}) +``` + +Where `` is the domain name for your Space which can be retrieved from the Space URL. For example, `medusa-server.fra1.digitaloceanspaces.com`. + +## What’s Next 🚀 + +- Check out [more plugins](https://github.com/medusajs/medusa/tree/master/packages) you can add to your store. +- Learn how to [deploy the Medusa server on DigitalOcean](../deployments/server/deploying-on-digital-ocean.md). +- Learn about the [Next.js](../starters/nextjs-medusa-starter.md) and [Gatsby](../starters/gatsby-medusa-starter.md) storefronts.