Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: updated digital ocean spaces guide #5900

Merged
merged 3 commits into from
Dec 15, 2023
Merged

docs: updated digital ocean spaces guide #5900

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8ef6d0b
docs: updated digital ocean spaces guide
shahednasser Dec 15, 2023
f8953a4
fix example
shahednasser Dec 15, 2023
4ea137d
Merge branch 'develop' into docs/do-spaces-fixes
shahednasser Dec 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 31 additions & 48 deletions www/apps/docs/content/plugins/file-service/spaces.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,6 @@ addHowToData: true

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 backend and use it for storage.

<div>
<video width="100%" height="100%" playsinline autoplay muted controls>
<source src="https://user-images.githubusercontent.com/59018053/154808767-7c030254-1879-41fd-a71c-b31c5508d8a4.mp4" type="video/mp4" />
</video>
</div>

## 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.
Expand All @@ -33,43 +27,33 @@ You need to [create a DigitalOcean account](https://cloud.digitalocean.com/regi

---

## 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://res.cloudinary.com/dza7lstvk/image/upload/v1668000907/Medusa%20Docs/Spaces/AQqMRoJ_uhkywh.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://res.cloudinary.com/dza7lstvk/image/upload/v1668000929/Medusa%20Docs/Spaces/ipsIqoA_zeyfkf.png)
## Create DigitalOcean Spaces Bucket

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.
On your DigitalOcean dashboard:

![Enter a name for the Space in the Choose a unique name field](https://res.cloudinary.com/dza7lstvk/image/upload/v1668000949/Medusa%20Docs/Spaces/NhlRX0h_ptdhpk.png)
1. Click on the Create button at the top right.
2. Choose "Spaces Object Storage" from the dropdown.
3. In the Create a Spaces Bucket form:
1. You can choose any of the datacenter regions listed.
2. 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.
3. For the "Select a project" input, select the project you want to add the new Spaces Bucket to.
4. Once you’re done, click on the "Create a Spaces Bucket" button.

Once you’re done, click on the Create a Space button. This creates the Space and redirects you to the Space’s page.
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.

![Choose API from the bottom of the sidebar.](https://res.cloudinary.com/dza7lstvk/image/upload/v1668000964/Medusa%20Docs/Spaces/6zNoDOW_tqbeqv.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://res.cloudinary.com/dza7lstvk/image/upload/v1668000977/Medusa%20Docs/Spaces/NUocdgh_doi0dq.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://res.cloudinary.com/dza7lstvk/image/upload/v1668000987/Medusa%20Docs/Spaces/ihJBx0T_xfe4rh.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.
1. Choose API from the bottom of the sidebar.
2. This opens the Application & API page. Choose the "Spaces Keys" tab.
3. Click on the "Generate New Key" button.
4. In the pop-up, enter a name for the access key and click Create Access Key.
5. Then, in the table, you'll find a new key added where you can copy the secret and access keys.

:::warning

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.
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.

:::

Expand All @@ -88,23 +72,19 @@ Then, add the following environment variables:
```bash
SPACE_URL=<YOUR_SPACE_URL>
SPACE_BUCKET=<YOUR_SPACE_NAME>
SPACE_REGION=<YOUR_SPACE_REGION>
SPACE_ENDPOINT=<YOUR_SPACE_ENDPOINT>
SPACE_ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
SPACE_SECRET_ACCESS_KEY=<YOUR_SECRET_ACCESS_KEY>
```

Where:

1. `<YOUR_SPACE_URL>` is the URL of your Space which you can find on the Space’s page below the Space’s name.

![The URL is available under the Space's name on the Space's page](https://res.cloudinary.com/dza7lstvk/image/upload/v1668001004/Medusa%20Docs/Spaces/cA3vkvh_maixr0.png)

2. `<YOUR_SPACE_NAME>` is the name of your Space.
3. `<YOUR_SPACE_ENDPOINT>` 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://res.cloudinary.com/dza7lstvk/image/upload/v1668001017/Medusa%20Docs/Spaces/CnvLr6R_tudlhu.png)

4. `<YOUR_ACCESS_KEY_ID>` and `<YOUR_SECRET_ACCESS_KEY>` are the keys you created in the previous section.
1. `<YOUR_SPACE_URL>` is either the Origin Endpoint or the CDN endpoint of your Spaces Object Storage bucket.
2. `<YOUR_SPACE_NAME>` is the name of your Spaces Object Storage bucket.
3. `<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 is `https://<bucket-name>.<region>.digitaloceanspaces.com`. For example, `nyc3`.
4. `<YOUR_SPACE_ENDPOINT>` is of the format `https://<region>.digitaloceanspaces.com`. For example, `https://nyc3.digitaloceanspaces.com`.
5. `<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:

Expand All @@ -116,6 +96,7 @@ const plugins = [
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,
Expand All @@ -130,6 +111,12 @@ If you have multiple storage plugins configured, the last plugin declared in the

:::

### 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
Expand All @@ -144,12 +131,8 @@ Then, you can either test the plugin using the [REST APIs](https://docs.medusaj

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://res.cloudinary.com/dza7lstvk/image/upload/v1668001039/Medusa%20Docs/Spaces/oTi4jIw_c6vefa.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://res.cloudinary.com/dza7lstvk/image/upload/v1668001050/Medusa%20Docs/Spaces/BexmRkg_gimk1d.png)

---

## Next.js Starter Template Configuration
Expand All @@ -170,13 +153,13 @@ module.exports = withStoreConfig({
images: {
domains: [
// ...
"<YOUR_SPACE_DOMAIN>",
"<YOUR_SPACE_URL>",
],
},
})
```

Where `<YOUR_SPACE_DOMAIN>` is the domain name for your Space which can be retrieved from the Space URL. For example, `medusa-backend.digitaloceanspaces.com`.
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`

---

Expand Down
Loading