api-ref: custom API reference (#4770)
* initialized next.js project * finished markdown sections * added operation schema component * change page metadata * eslint fixes * fixes related to deployment * added response schema * resolve max stack issue * support for different property types * added support for property types * added loading for components * added more loading * type fixes * added oneOf type * removed console * fix replace with push * refactored everything * use static content for description * fixes and improvements * added code examples section * fix path name * optimizations * fixed tag navigation * add support for admin and store references * general enhancements * optimizations and fixes * fixes and enhancements * added search bar * loading enhancements * added loading * added code blocks * added margin top * add empty response text * fixed oneOf parameters * added path and query parameters * general fixes * added base path env variable * small fix for arrays * enhancements * design enhancements * general enhancements * fix isRequired * added enum values * enhancements * general fixes * general fixes * changed oas generation script * additions to the introduction section * added copy button for code + other enhancements * fix response code block * fix metadata * formatted store introduction * move sidebar logic to Tags component * added test env variables * fix code block bug * added loading animation * added expand param + loading * enhance operation loading * made responsive + improvements * added loading provider * fixed loading * adjustments for small devices * added sidebar label for endpoints * added feedback component * fixed analytics * general fixes * listen to scroll for other headings * added sample env file * update api ref files + support new fields * fix for external docs link * added new sections * fix last item in sidebar not showing * move docs content to www/docs * change redirect url * revert change * resolve build errors * configure rewrites * changed to environment variable url * revert changing environment variable name * add environment variable for API path * fix links * fix tailwind settings * remove vercel file * reconfigured api route * move api page under api * fix page metadata * fix external link in navigation bar * update api spec * updated api specs * fixed google lint error * add max-height on request samples * add padding before loading * fix for one of name * fix undefined types * general fixes * remove response schema example * redesigned navigation bar * redesigned sidebar * fixed up paddings * added feedback component + report issue * fixed up typography, padding, and general styling * redesigned code blocks * optimization * added error timeout * fixes * added indexing with algolia + fixes * fix errors with algolia script * redesign operation sections * fix heading scroll * design fixes * fix padding * fix padding + scroll issues * fix scroll issues * improve scroll performance * fixes for safari * optimization and fixes * fixes to docs + details animation * padding fixes for code block * added tab animation * fixed incorrect link * added selection styling * fix lint errors * redesigned details component * added detailed feedback form * api reference fixes * fix tabs * upgrade + fixes * updated documentation links * optimizations to sidebar items * fix spacing in sidebar item * optimizations and fixes * fix endpoint path styling * remove margin * final fixes * change margin on small devices * generated OAS * fixes for mobile * added feedback modal * optimize dark mode button * fixed color mode useeffect * minimize dom size * use new style system * radius and spacing design system * design fixes * fix eslint errors * added meta files * change cron schedule * fix docusaurus configurations * added operating system to feedback data * change content directory name * fixes to contribution guidelines * revert renaming content * added api-reference to documentation workflow * fixes for search * added dark mode + fixes * oas fixes * handle bugs * added code examples for clients * changed tooltip text * change authentication to card * change page title based on selected section * redesigned mobile navbar * fix icon colors * fix key colors * fix medusa-js installation command * change external regex in algolia * change changeset * fix padding on mobile * fix hydration error * update depedencies
This commit is contained in:
Shahed Nasser authored and 
GitHub committed
1 parent
16249ec280
commit
914d773d3a
3270 files changed
+22075
-192064
No files matched your search
@@ -0,0 +1,5 @@
|
||||
import DocCardList from '@theme/DocCardList';
|
||||
|
||||
# File Service Plugins
|
||||
|
||||
<DocCardList />
|
||||
@@ -0,0 +1,105 @@
|
||||
---
|
||||
description: 'Learn how to install the local file service to upload images and assets locally on your Medusa backend.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
# Local File Storage
|
||||
|
||||
This document will guide you through installing the local file storage plugin on your Medusa backend.
|
||||
|
||||
## Overview
|
||||
|
||||
To upload and manage file assets in Medusa, you need a file service plugin responsible for hosting the files. 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. The local file storage plugin makes it easy to upload file assets locally during development.
|
||||
|
||||
:::note
|
||||
|
||||
For production, it's recommended to use a file service plugin that hosts your images on a third-party service. This file service doesn't handle advanced features such as private uploads, which means you can't use it for functionalities like import or export products. Check [the file service plugins](./index.mdx) for available other options to use.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
A Medusa backend is required to be set up before following along with this document. You can follow the [quickstart guide](../../development/backend/install.mdx) to get started in minutes.
|
||||
|
||||
---
|
||||
|
||||
## Plugin Installation
|
||||
|
||||
In the directory of your Medusa backend, run the following command to install the local file service plugin:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/file-local
|
||||
```
|
||||
|
||||
Then, configure your `medusa-config.js` to include the plugin with the required options:
|
||||
|
||||
```js title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
resolve: `@medusajs/file-local`,
|
||||
options: {
|
||||
// optional
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
:::caution
|
||||
|
||||
If you have multiple storage plugins configured, the last plugin declared in the `medusa-config.js` file will be used.
|
||||
|
||||
:::
|
||||
|
||||
### Options
|
||||
|
||||
You can pass the plugin the following options:
|
||||
|
||||
- `upload_dir`: a string indicating the relative path to upload the files to. By default, it's `uploads/images`.
|
||||
- `backend_url`: a string indicating the URL of your backend. This is helpful if you deploy your backend or change the port used. By default, it's `http://localhost:9000`.
|
||||
|
||||
---
|
||||
|
||||
## Test it Out
|
||||
|
||||
Run your Medusa backend alongside the [Medusa Admin](../../admin/quickstart.mdx) to try out your new file service. Upon editing or creating products, you can now upload thumbnails and images, that are stored locally in your backend.
|
||||
|
||||
The files will be stored under the `upload_dir` specified in the plugin options (if no option is specified, they'll be stored in the `uploads/images` directory by default.)
|
||||
|
||||
---
|
||||
|
||||
## Next.js Starter Template Configuration
|
||||
|
||||
If you’re using a [Next.js Starter Template](../../starters/nextjs-medusa-starter.mdx), you need to add an additional configuration that adds the backend's domain name into the configured images domain names. This is because all URLs of product images will be from the Medusa backend.
|
||||
|
||||
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 title=next.config.js
|
||||
const { withStoreConfig } = require("./store-config")
|
||||
|
||||
// ...
|
||||
|
||||
module.exports = withStoreConfig({
|
||||
// ...
|
||||
images: {
|
||||
domains: [
|
||||
// ...
|
||||
"<BACKEND_URL>",
|
||||
],
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
Where `<BACKEND_URL>` is the URL of your backend. If you're running the backend locally, the value would be `localhost`.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- Check out [more plugins](../overview.mdx) you can add to your store.
|
||||
@@ -0,0 +1,226 @@
|
||||
---
|
||||
description: 'Learn how to integrate MinIO with the Medusa backend. Learn how to install the MinIO plugin on the Medusa backend and configure it.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
# MinIO
|
||||
|
||||
This document will guide you through installing the MinIO file service plugin on your Medusa backend.
|
||||
|
||||
## Overview
|
||||
|
||||
To upload and manage file assets in Medusa, you need a file service plugin responsible for hosting the files. 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 will focus on setting up [MinIO](https://min.io) on your local machine and connecting Medusa to it.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
A Medusa backend is required to be set up before following along with this document. You can follow the [quickstart guide](../../development/backend/install.mdx) to get started in minutes.
|
||||
|
||||
---
|
||||
|
||||
## Set up MinIO
|
||||
|
||||
You can follow [MinIO’s guide to install it](https://docs.min.io/minio/baremetal/quickstart/quickstart.html) on your machine based on your operating system.
|
||||
|
||||
After installing it, make sure MinIO is always running when your Medusa backend is running. It’s recommended that you set up an alias to quickly start the MinIO backend as instructed at the end of the installation guides in MinIO.
|
||||
|
||||
### Change MinIO port
|
||||
|
||||
In MinIO’s documentation, port `9000` is used for the address of the MinIO backend. However, this collides with the port for the Medusa backend. You must change the port for MinIO to another one (for example, port `9001`).
|
||||
|
||||
After setting up and installing MinIO on your system/sub-system, you can run the following command to change MinIO port to `9001` (or any other available port) instead of `9000` to avoid the port clash:
|
||||
|
||||
```bash
|
||||
minio server ~/minio --console-address :9090 --address :9001
|
||||
```
|
||||
|
||||
### Create a MinIO bucket
|
||||
|
||||
After installing MinIO and logging into the Console, you can create a bucket that will store the files of your Medusa backend by following these steps:
|
||||
|
||||
1. Go to the Buckets page from the sidebar.
|
||||
2. Click on the “Create Bucket” button.
|
||||
3. For the Bucket Name field, enter a name for the bucket. By MinIO’s requirement, the name can only consist of lower case characters, numbers, dots (`.`), and hyphens (`-`).
|
||||
4. Click on the Create Bucket button.
|
||||
5. On the bucket's page, click on the edit icon next to Access Policy.
|
||||
6. In the pop-up that opens, change the selected value to “public” and click Set.
|
||||
|
||||
:::warning
|
||||
|
||||
Changing the Access Policy to public will allow anyone to access your bucket. Avoid storing sensitive data in the bucket.
|
||||
|
||||
:::
|
||||
|
||||
### Generate Access Keys
|
||||
|
||||
To generate access keys for your plugin:
|
||||
|
||||
1. From the sidebar of your MinIO console, click on Access Keys
|
||||
2. Click on the "Create access key" button
|
||||
3. This will open a new form with randomly-generated keys. Click on the Create button.
|
||||
4. A pop-up will then show the value for your Access Key and Secret Key. Copy them to use in the next section.
|
||||
|
||||
:::caution
|
||||
|
||||
You will not be able to access the Secret Key after closing the pop-up. So, make sure to store it somewhere to use later when configuring the plugin.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Plugin Installation
|
||||
|
||||
In the directory of your Medusa backend, run the following command to install the MinIO plugin:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install medusa-file-minio
|
||||
```
|
||||
|
||||
Then, add the following environment variables in `.env`:
|
||||
|
||||
```bash
|
||||
MINIO_ENDPOINT=<ENDPOINT>
|
||||
MINIO_BUCKET=<BUCKET>
|
||||
MINIO_ACCESS_KEY=<ACCESS_KEY>
|
||||
MINIO_SECRET_KEY=<SECRET_KEY>
|
||||
```
|
||||
|
||||
Where `<ENDPOINT>` is the URL of your MinIO backend, `<BUCKET>` is the name of the bucket you created earlier, and `<ACCESS_KEY>` and `<SECRET_KEY>` are the keys you generated in the previous section.
|
||||
|
||||
Finally, configure your `medusa-config.js` to include the plugin with the required options:
|
||||
|
||||
```js title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
resolve: `medusa-file-minio`,
|
||||
options: {
|
||||
endpoint: process.env.MINIO_ENDPOINT,
|
||||
bucket: process.env.MINIO_BUCKET,
|
||||
access_key_id: process.env.MINIO_ACCESS_KEY,
|
||||
secret_access_key: process.env.MINIO_SECRET_KEY,
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
:::caution
|
||||
|
||||
If you have multiple storage plugins configured, the last plugin declared in the `medusa-config.js` file will be used.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Test it Out
|
||||
|
||||
Run your Medusa backend alongside the [Medusa Admin](../../admin/quickstart.mdx) to try out your new file service. Upon editing or creating products, you can now upload thumbnails and images, that are stored in a MinIO backend.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Private Buckets
|
||||
|
||||
### Handle Exports
|
||||
|
||||
Medusa provides export functionalities including exporting products and orders. For exports to work, you must [set up a private bucket](#create-private-bucket).
|
||||
|
||||
### Handle Imports
|
||||
|
||||
Medusa provides import functionalities including importing products. For imports to work, you must [set the private bucket](#add-private-bucket-environment-variable) to be the same as the public bucket.
|
||||
|
||||
### Create Private Bucket
|
||||
|
||||
To create a private bucket, follow along the [steps mentioned earlier](#create-a-minio-bucket), but keep Access Policy set to private.
|
||||
|
||||
### Add Private Bucket Environment Variable
|
||||
|
||||
Add the following environment variable on your Medusa backend:
|
||||
|
||||
```bash
|
||||
MINIO_PRIVATE_BUCKET=exports
|
||||
```
|
||||
|
||||
Then, add a new option to the plugin’s options in `medusa-config.js`:
|
||||
|
||||
```jsx title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
resolve: `medusa-file-minio`,
|
||||
options: {
|
||||
// ...
|
||||
private_bucket: process.env.MINIO_PRIVATE_BUCKET,
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
### Use Different Secret and Access Keys
|
||||
|
||||
If you only add the `private_bucket` option, the same secret and access keys that you used for the public bucket will be used to access the private bucket.
|
||||
|
||||
If you want to use different keys, set the following environment variables:
|
||||
|
||||
```bash
|
||||
MINIO_PRIVATE_ACCESS_KEY=<YOUR_PRIVATE_ACCESS_KEY>
|
||||
MINIO_PRIVATE_SECRET_KEY=<YOUR_PRIVATE_SECRET_KEY>
|
||||
```
|
||||
|
||||
Where `<YOUR_PRIVATE_ACCESS_KEY>` and `<YOUR_PRIVATE_SECRET_KEY>` are the access key and secret access key that have access to the private MinIO bucket.
|
||||
|
||||
Then, add two new options to the plugin’s options in `medusa-config.js`:
|
||||
|
||||
```jsx title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
resolve: `medusa-file-minio`,
|
||||
options: {
|
||||
// ...
|
||||
private_access_key_id:
|
||||
process.env.MINIO_PRIVATE_ACCESS_KEY,
|
||||
private_secret_access_key:
|
||||
process.env.MINIO_PRIVATE_SECRET_KEY,
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next.js Starter Template Configuration
|
||||
|
||||
If you’re using a [Next.js Starter Template](../../starters/nextjs-medusa-starter.mdx), you need to add an additional configuration that adds the MinIO domain name into the configured images domain names. This is because all URLs of product images will be from the MinIO backend.
|
||||
|
||||
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 title=next.config.js
|
||||
const { withStoreConfig } = require("./store-config")
|
||||
|
||||
// ...
|
||||
|
||||
module.exports = withStoreConfig({
|
||||
// ...
|
||||
images: {
|
||||
domains: [
|
||||
// ...
|
||||
"127.0.0.1",
|
||||
],
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
Where `127.0.0.1` is the domain of your local MinIO backend.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- Check out [more plugins](../overview.mdx) you can add to your store.
|
||||
@@ -0,0 +1,244 @@
|
||||
---
|
||||
description: 'Learn how to integrate the S3 plugin with the Medusa backend. Learn how to configure and use S3 to store images related to the Medusa backend.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
import Troubleshooting from '@site/src/components/Troubleshooting'
|
||||
import AclErrorSection from '../../troubleshooting/s3-acl-error.md'
|
||||
|
||||
# S3
|
||||
|
||||
In this document, you’ll learn how to install the [S3 plugin](https://github.com/medusajs/medusa/tree/master/packages/medusa-file-s3) on your Medusa backend and use it for storage.
|
||||
|
||||
## Overview
|
||||
|
||||
To upload and manage file assets in Medusa, you need a file service plugin responsible for hosting the files. 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 [S3](https://aws.amazon.com/s3/) 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](../../development/backend/install.mdx) to get started in minutes.
|
||||
|
||||
### Required Accounts
|
||||
|
||||
You need to [create an AWS account](https://console.aws.amazon.com/console/home?nc2=h_ct&src=header-signin) to follow along with this documentation.
|
||||
|
||||
---
|
||||
|
||||
## Create S3 Bucket
|
||||
|
||||
On your AWS Console, search for S3 in the search box at the top. Then, choose the first result you see which should be S3 under the Services category.
|
||||
|
||||
|
||||
|
||||
Then, on the new page that opens, click on Create Bucket button at the top right of the Buckets table.
|
||||
|
||||
|
||||
|
||||
The Create Bucket form will open. In the General Configuration section enter a name for the bucket and choose a region for the bucket. Both of the values of these fields are important as you’ll use them throughout the documentation.
|
||||
|
||||
|
||||
|
||||
Next, in the Object Ownership section, choose ACLs enabled. Then, two radio buttons will show below it. Choose Bucket owner preferred.
|
||||
|
||||
|
||||
|
||||
Then, in the “Block Public Access settings for this bucket” section, uncheck the “Block all public access” checkbox. This shows a warning message at the bottom of the section with another checkbox. Check the checkbox to ensure you understand that objects in the bucket are publicly accessible.
|
||||
|
||||
|
||||
|
||||
You can leave the rest of the fields in the form as is and scroll down to the end of the page. Then, click on the Create Bucket button.
|
||||
|
||||
---
|
||||
|
||||
## Manage Bucket Policies
|
||||
|
||||
On the page of the bucket you just created, click on the Permissions tab. Then, scroll down until you find the Bucket policy section. Click on Edit in that section.
|
||||
|
||||
|
||||
|
||||
In the Edit Bucket Policy page, enter the following in the field:
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Id": "Policy1397632521960",
|
||||
"Statement": [
|
||||
{
|
||||
"Sid": "Stmt1397633323327",
|
||||
"Effect": "Allow",
|
||||
"Principal": {
|
||||
"AWS": "*"
|
||||
},
|
||||
"Action": "s3:GetObject",
|
||||
"Resource": "arn:aws:s3:::<YOUR_BUCKET_NAME>/*"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Make sure to replace `<YOUR_BUCKET_NAME>` with the name of the bucket you created.
|
||||
|
||||
Once you’re done, scroll down and click on the Save changes button.
|
||||
|
||||
### User Permissions
|
||||
|
||||
Your user must have the `AmazonS3FullAccess` policy attached to it. You can refer to [this guide](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-create-and-attach-iam-policy.html) to learn how to add a policy if necessary.
|
||||
|
||||
### Obtain Access Keys
|
||||
|
||||
You must obtain access keys for your user as you’ll use them to integrate the S3 plugin in Medusa with your bucket. To obtain the Access Key ID and the Secret Access Key, check out [this guide](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys).
|
||||
|
||||
---
|
||||
|
||||
## Install the S3 Plugin
|
||||
|
||||
In the directory of your Medusa backend, run the following command to install the S3 Plugin:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install medusa-file-s3
|
||||
```
|
||||
|
||||
Then, add the following environment variables:
|
||||
|
||||
```bash
|
||||
S3_URL=<YOUR_BUCKET_URL>
|
||||
S3_BUCKET=<YOUR_BUCKET_NAME>
|
||||
S3_REGION=<YOUR_BUCKET_REGION>
|
||||
S3_ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
|
||||
S3_SECRET_ACCESS_KEY=<YOUR_SECRET_ACCESS_KEY>
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
1. `<YOUR_BUCKET_URL>` is the URL to your bucket. It’s in the form `https://<BUCKET_NAME>.s3.<REGION>.amazonaws.com`, where `<BUCKET_NAME>` is the name of the bucket and the `<REGION>` is the region the bucket is created in. If you’re not sure which region, on your bucket’s page on S3 click on Properties. You can then find the region under AWS Region. Make sure to only copy the code (for example, `us-east-1`).
|
||||
2. `<YOUR_BUCKET_NAME>` is the name of the bucket you created.
|
||||
3. `<YOUR_BUCKET_REGION>` is the region code of your bucket. For example, `us-east-1`.
|
||||
4. `<YOUR_ACCESS_KEY_ID>` is the Access Key ID that you created for your user.
|
||||
5. `<YOUR_SECRET_ACCESS_KEY>` is the Secret Access Key that you created for your user.
|
||||
|
||||
Finally, in `medusa-config.js`, add to the `plugins` array the following new item:
|
||||
|
||||
```jsx title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
resolve: `medusa-file-s3`,
|
||||
options: {
|
||||
s3_url: process.env.S3_URL,
|
||||
bucket: process.env.S3_BUCKET,
|
||||
region: process.env.S3_REGION,
|
||||
access_key_id: process.env.S3_ACCESS_KEY_ID,
|
||||
secret_access_key: process.env.S3_SECRET_ACCESS_KEY,
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
|
||||
:::caution
|
||||
|
||||
If you have multiple storage plugins configured, the last plugin declared in the `medusa-config.js` file will be used.
|
||||
|
||||
:::
|
||||
|
||||
### Add AWS Configurations
|
||||
|
||||
You can pass additional AWS configurations, such as `customUserAgent`, in the plugin's options under the property `aws_config_object`. This property is an object that accepts [AWS Configurations](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html) as its properties.
|
||||
|
||||
For example:
|
||||
|
||||
```jsx title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
resolve: `medusa-file-s3`,
|
||||
options: {
|
||||
s3_url: process.env.S3_URL,
|
||||
bucket: process.env.S3_BUCKET,
|
||||
aws_config_object: {
|
||||
customUserAgent: process.env.S3_CUSTOM_AGENT,
|
||||
},
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
Make sure to define `S3_CUSTOM_AGENT` in your environment variables first.
|
||||
|
||||
---
|
||||
|
||||
## Test the S3 Plugin
|
||||
|
||||
Run your Medusa backend with the following command:
|
||||
|
||||
```bash npm2yarn
|
||||
npx medusa develop
|
||||
```
|
||||
|
||||
Then, you can either test the plugin using the [REST APIs](https://docs.medusajs.com/api/store) or using the [Medusa Admin](../../admin/quickstart.mdx).
|
||||
|
||||
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 S3 bucket’s page.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Next.js Starter Template Configuration
|
||||
|
||||
If you’re using a [Next.js Starter Template](../../starters/nextjs-medusa-starter.mdx), you need to add an additional configuration that adds the S3 bucket domain name into the configured images’ domain names. This is because all URLs of product images will be from the S3 bucket.
|
||||
|
||||
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 title=next.config.js
|
||||
const { withStoreConfig } = require("./store-config")
|
||||
|
||||
// ...
|
||||
|
||||
module.exports = withStoreConfig({
|
||||
// ...
|
||||
images: {
|
||||
domains: [
|
||||
// ...
|
||||
"<BUCKET_NAME>.s3.<REGION>.amazonaws.com",
|
||||
],
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
- `<BUCKET_NAME>` is the name of the S3 bucket you’re using
|
||||
- `<REGION>` is the region of the S3 bucket (for example, `eu-west-1`). If your S3 URL doesn't use region in it, you may omit it to be instead `<BUCKET_NAME>.s3.amazonaws.com`.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<Troubleshooting
|
||||
sections={[
|
||||
{
|
||||
title: 'Error: AccessControlListNotSupported: The bucket does not allow ACLs',
|
||||
content: <AclErrorSection />
|
||||
}
|
||||
]}
|
||||
/>
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- Check out [more plugins](../overview.mdx) you can add to your store
|
||||
- [Deploy the Medusa backend](../../deployments/server/index.mdx)
|
||||
- Install the [Next.js Starter Template](../../starters/nextjs-medusa-starter.mdx)
|
||||
@@ -0,0 +1,187 @@
|
||||
---
|
||||
description: 'Learn how to integrate Spaces with the Medusa backend. Learn how to install and configure the Spaces plugin on the Medusa backend.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
# 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 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.
|
||||
|
||||
Medusa provides three different options to handle your file storage. This document focuses on using [Spaces](https://www.digitalocean.com/products/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](../../development/backend/install.mdx) to get started in minutes.
|
||||
|
||||
### Required Accounts
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## Create DigitalOcean Space
|
||||
|
||||
In your DigitalOcean account, click on the Create button at the top right, then choose Spaces from the dropdown.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
This opens the Application & API page. Scroll down to Spaces Access Keys and click the Generate New Key button.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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 backend, run the following command to install the Spaces plugin:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install medusa-file-spaces
|
||||
```
|
||||
|
||||
Then, add the following environment variables:
|
||||
|
||||
```bash
|
||||
SPACE_URL=<YOUR_SPACE_URL>
|
||||
SPACE_BUCKET=<YOUR_SPACE_NAME>
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
4. `<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:
|
||||
|
||||
```jsx title=medusa-config.js
|
||||
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.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Test the Space Plugin
|
||||
|
||||
Run your Medusa backend with the following command:
|
||||
|
||||
```bash npm2yarn
|
||||
npx medusa develop
|
||||
```
|
||||
|
||||
Then, you can either test the plugin using the [REST APIs](https://docs.medusajs.com/api/store) or using the [Medusa Admin](../../admin/quickstart.mdx).
|
||||
|
||||
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](../../starters/nextjs-medusa-starter.mdx), 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 title=next.config.js
|
||||
const { withStoreConfig } = require("./store-config")
|
||||
|
||||
// ...
|
||||
|
||||
module.exports = withStoreConfig({
|
||||
// ...
|
||||
images: {
|
||||
domains: [
|
||||
// ...
|
||||
"<YOUR_SPACE_DOMAIN>",
|
||||
],
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
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`.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- Check out [more plugins](../overview.mdx) you can add to your store
|
||||
- [Deploy the Medusa backend on DigitalOcean](../../deployments/server/deploying-on-digital-ocean.md)
|
||||
- Install the [Next.js Starter Template](../../starters/nextjs-medusa-starter.mdx)
|
||||
Reference in new issue
Block a user