docs: publish restructure (#3496)
* docs: added features and guides overview page * added image * added version 2 * added version 3 * added version 4 * docs: implemented new color scheme * docs: redesigned sidebar (#3193) * docs: redesigned navbar for restructure (#3199) * docs: redesigned footer (#3209) * docs: redesigned cards (#3230) * docs: redesigned admonitions (#3231) * docs: redesign announcement bar (#3236) * docs: redesigned large cards (#3239) * docs: redesigned code blocks (#3253) * docs: redesigned search modal and page (#3264) * docs: redesigned doc footer (#3268) * docs: added new sidebars + refactored css and assets (#3279) * docs: redesigned api reference sidebar * docs: refactored css * docs: added code tabs transition * docs: added new sidebars * removed unused assets * remove unusued assets * Fix deploy errors * fix incorrect link * docs: fixed code responsivity + missing icons (#3283) * docs: changed icons (#3296) * docs: design fixes to the sidebar (#3297) * redesign fixes * docs: small design fixes * docs: several design fixes after restructure (#3299) * docs: bordered icon fixes * docs: desgin fixes * fixes to code blocks and sidebar scroll * design adjustments * docs: restructured homepage (#3305) * docs: restructured homepage * design fixes * fixed core concepts icon * docs: added core concepts page (#3318) * docs: restructured homepage * design fixes * docs: added core concepts page * changed text of different components * docs: added architecture link * added missing prop for user guide * docs: added regions overview page (#3327) * docs: added regions overview * moved region pages to new structure * docs: fixed description of regions architecture page * small changes * small fix * docs: added customers overview page (#3331) * docs: added regions overview * moved region pages to new structure * docs: fixed description of regions architecture page * small changes * small fix * docs: added customers overview page * fix link * resolve link issues * docs: updated regions architecture image * docs: second-iteration fixes (#3347) * docs: redesigned document * design fixes * docs: added products overview page (#3354) * docs: added carts overview page (#3363) * docs: added orders overview (#3364) * docs: added orders overview * added links in overview * docs: added vercel redirects * docs: added soon badge for cards (#3389) * docs: resolved feedback changes + organized troubleshooting pages (#3409) * docs: resolved feedback changes * added extra line * docs: changed icons for restructure (#3421) * docs: added taxes overview page (#3422) * docs: added taxes overview page * docs: fix sidebar label * added link to taxes overview page * fixed link * docs: fixed sidebar scroll (#3429) * docs: added discounts overview (#3432) * docs: added discounts overview * fixed links * docs: added gift cards overview (#3433) * docs: added price lists overview page (#3440) * docs: added price lists overview page * fixed links * docs: added sales channels overview page (#3441) * docs: added sales overview page * fixed links * docs: added users overview (#3443) * docs: fixed sidebar border height (#3444) * docs: fixed sidebar border height * fixed svg markup * docs: added possible solutions to feedback component (#3449) * docs: added several overview pages + restructured files (#3463) * docs: added several overview pages * fixed links * docs: added feature flags + PAK overview pages (#3464) * docs: added feature flags + PAK overview pages * fixed links * fix link * fix link * fixed links colors * docs: added strategies overview page (#3468) * docs: automated upgrade guide (#3470) * docs: automated upgrade guide * fixed vercel redirect * docs: restructured files in docs codebase (#3475) * docs: restructured files * docs: fixed eslint exception * docs: finished restructure loose-ends (#3493) * fixed uses of backend * docs: finished loose ends * eslint fixes * fixed links * merged master * added update instructions for v1.7.12
This commit is contained in:
391
docs/content/development/backend/configurations.md
Normal file
391
docs/content/development/backend/configurations.md
Normal file
@@ -0,0 +1,391 @@
|
||||
---
|
||||
description: 'Learn about the different configurations available in a Medusa backend. This includes configurations related to the database, CORS, plugins, redis, and more.'
|
||||
---
|
||||
|
||||
# Configure Medusa Backend
|
||||
|
||||
In this document, you’ll learn what configurations you can add to your Medusa backend and how to add them.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
This document assumes you already followed along with the [“Set up your development environment” documentation](./prepare-environment.mdx) and have [installed a Medusa backend](./install.mdx#create-a-medusa-backend).
|
||||
|
||||
---
|
||||
|
||||
## Medusa Configurations File
|
||||
|
||||
The configurations for your Medusa backend are in `medusa-config.js`. This includes database, Redis, and plugin configurations, among other configurations.
|
||||
|
||||
Some of the configurations mentioned in this document are already defined in `medusa-config.js` with default values. It’s important that you know what these configurations are used for and how to set them.
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
In your configurations, you’ll often use environment variables. For example, when using API keys or setting your database URL.
|
||||
|
||||
By default, Medusa loads environment variables from the system’s environment variables. Any different method you prefer to use or other location you’d prefer to load environment variables from you need to manually implement.
|
||||
|
||||
:::info
|
||||
|
||||
This change in how environment variables are loaded was introduced in version 1.3.0. You can learn more in the [upgrade guide for version 1.3.0](../../upgrade-guides/medusa-core/1-3-0.md).
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Database Configuration
|
||||
|
||||
Medusa supports two database types: SQLite and PostgreSQL.
|
||||
|
||||
:::tip
|
||||
|
||||
You can use SQLite for development purposes, however, it’s recommended to use PostgreSQL.
|
||||
|
||||
:::
|
||||
|
||||
### SQLite Configurations
|
||||
|
||||
For SQLite you mainly need two configurations:
|
||||
|
||||
```jsx
|
||||
module.exports = {
|
||||
projectConfig: {
|
||||
// ...other configurations
|
||||
database_type: "sqlite",
|
||||
database_database: "./medusa-db.sql",
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Where `database_type` is `sqlite` and `database_database` is the location you want the SQLite database to be created in.
|
||||
|
||||
### PostgreSQL Configurations
|
||||
|
||||
:::note
|
||||
|
||||
Before getting started with configuring PostgreSQL, you should have created a PostgreSQL database. You can check how to create a database in [PostgreSQL's documentation](https://www.postgresql.org/docs/current/sql-createdatabase.html).
|
||||
|
||||
:::
|
||||
|
||||
For PostgreSQL you mainly need two configurations:
|
||||
|
||||
```jsx
|
||||
module.exports = {
|
||||
projectConfig: {
|
||||
// ...other configurations
|
||||
database_type: "postgres",
|
||||
database_url: DATABASE_URL,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Where `database_type` is `postgres` and `DATABASE_URL` is the URL connection string to your PostgreSQL database. You can check out how to format it in [PostgreSQL’s documentation](https://www.postgresql.org/docs/current/libpq-connect.html).
|
||||
|
||||
It's recommended to set the Database URL as an environment variable:
|
||||
|
||||
```bash
|
||||
DATABASE_URL=<YOUR_DATABASE_URL>
|
||||
```
|
||||
|
||||
Where `<YOUR_DATABASE_URL>` is the URL of your PostgreSQL database.
|
||||
|
||||
### Changing PostgreSQL Schema
|
||||
|
||||
By default, the `public` schema is used in PostgreSQL. You can change it to use a custom schema by passing the `search_path` option in the database URL. For example:
|
||||
|
||||
```bash
|
||||
postgres://localhost/store?options=-c search_path=test
|
||||
```
|
||||
|
||||
Where `test` is the name of the database schema that should be used instead of `public`.
|
||||
|
||||
### Changing Database Type
|
||||
|
||||
Remember to run migrations after you change your database type to `postgres` from another type:
|
||||
|
||||
```bash
|
||||
medusa migrations run
|
||||
```
|
||||
|
||||
### Common Configuration
|
||||
|
||||
As Medusa internally uses [Typeorm](https://typeorm.io/) to connect to the database, the following configurations are also available:
|
||||
|
||||
1. `database_logging`: enable or disable logging.
|
||||
2. `database_extra`: extra options that you can pass to the underlying database driver.
|
||||
|
||||
These configurations are not required and can be omitted.
|
||||
|
||||
```jsx
|
||||
module.exports = {
|
||||
projectConfig: {
|
||||
// ...other configurations
|
||||
database_logging: true,
|
||||
database_extra: {},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Redis
|
||||
|
||||
Medusa uses Redis to handle the event queue, among other usages. You need to set Redis URL in the configurations:
|
||||
|
||||
```jsx
|
||||
module.exports = {
|
||||
projectConfig: {
|
||||
// ...other configurations
|
||||
redis_url: REDIS_URL,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Where `REDIS_URL` is the URL used to connect to Redis. The format of the connection string is `redis[s]://[[username][:password]@][host][:port][/db-number]`.
|
||||
|
||||
If you omit this configuration, events will not be emitted and subscribers will not work.
|
||||
|
||||
:::tip
|
||||
|
||||
By default, the Redis connection string should be `redis://localhost:6379` unless you made any changes to the default configurations during the installation.
|
||||
|
||||
:::
|
||||
|
||||
It is recommended to set the Redis URL as an environment variable:
|
||||
|
||||
```bash
|
||||
REDIS_URL=<YOUR_REDIS_URL>
|
||||
```
|
||||
|
||||
Where `<YOUR_REDIS_URL>` is the URL of your Redis backend.
|
||||
|
||||
:::info
|
||||
|
||||
You can learn more about Subscribers and events in the [Subscriber documentation](../events/create-subscriber.md).
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## JWT Secret
|
||||
|
||||
Medusa uses JSON Web Token (JWT) to handle user authentication. To set the JWT secret:
|
||||
|
||||
```jsx
|
||||
module.exports = {
|
||||
projectConfig: {
|
||||
// ...other configurations
|
||||
jwt_secret: "very secure string",
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Where `jwt_secret` is the secret used to create the tokens. The more secure it is the better.
|
||||
|
||||
It is recommended to set the JWT Secret as an environment variable:
|
||||
|
||||
```bash
|
||||
JWT_SECRET=<YOUR_JWT_SECRET>
|
||||
```
|
||||
|
||||
Where `<YOUR_JWT_SECRET>` is the JWT secret you want to use.
|
||||
|
||||
:::caution
|
||||
|
||||
In a development environment, if this option is not set the default secret is “supersecret”. However, in production, if this option is not set an error will be thrown and your backend will crash.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Cookie Secret
|
||||
|
||||
This configuration is used to sign the session ID cookie. To set the cookie secret:
|
||||
|
||||
```jsx
|
||||
module.exports = {
|
||||
projectConfig: {
|
||||
// ...other configurations
|
||||
cookie_secret: "very secure string",
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Where `cookie_secret` is the secret used to create the tokens. The more secure it is the better.
|
||||
|
||||
It is recommended to set the Cookie secret as an environment variable:
|
||||
|
||||
```bash
|
||||
COOKIE_SECRET=<YOUR_COOKIE_SECRET>
|
||||
```
|
||||
|
||||
Where `<YOUR_COOKIE_SECRET>` is the Cookie secret you want to use.
|
||||
|
||||
:::caution
|
||||
|
||||
In a development environment, if this option is not set the default secret is “supersecret”. However, in production, if this option is not set an error will be thrown and your backend will crash.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## CORS Configurations
|
||||
|
||||
Medusa uses Cross-Origin Resource Sharing (CORS) to only allow specific origins to access the backend.
|
||||
|
||||
The Admin and the Storefront have different CORS configurations that must be configured.
|
||||
|
||||
### Accepted Patterns
|
||||
|
||||
For both of the Admin and the Storefront CORS configurations, the value is expected to be a string. This string can be a comma-separated list of accepted origins. Every origin in that list can be of the following types:
|
||||
|
||||
1. The accepted origin as is. For example, `http://localhost:8000`.
|
||||
2. A regular expression pattern that can match more than one origin. For example, `*.example.com`. The regex pattern that the backend tests for is `^([\/~@;%#'])(.*?)\1([gimsuy]*)$`.
|
||||
|
||||
Here are some examples of common use cases:
|
||||
|
||||
```bash
|
||||
# Allow different ports locally starting with 700
|
||||
ADMIN_CORS=/http:\/\/localhost:700\d+$/
|
||||
|
||||
# Allow any origin ending with vercel.app. For example, storefront.vercel.app
|
||||
STORE_CORS=/vercel\.app$/
|
||||
|
||||
# Allow all HTTP requests
|
||||
ADMIN_CORS=/http:\/\/*/
|
||||
```
|
||||
|
||||
Although this is not recommended, but when setting these values directly in `medusa-config.json`, make sure to add an extra escaping `backslash` for every backslash in the pattern. For example:
|
||||
|
||||
```js
|
||||
const ADMIN_CORS = process.env.ADMIN_CORS ||
|
||||
"/http:\\/\\/localhost:700\\d+$/"
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
The examples above apply to both Admin and Store CORS.
|
||||
|
||||
:::
|
||||
|
||||
### Admin CORS
|
||||
|
||||
To make sure your Admin dashboard can access the Medusa backend’s admin endpoints, set this configuration:
|
||||
|
||||
```jsx
|
||||
module.exports = {
|
||||
projectConfig: {
|
||||
// ...other configurations
|
||||
admin_cors: ADMIN_CORS,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Where `ADMIN_CORS` is the URL of your admin dashboard. By default, it’s `http://localhost:7000,http://localhost:7001`.
|
||||
|
||||
It is recommended to set the Admin CORS as an environment variable:
|
||||
|
||||
```bash
|
||||
ADMIN_CORS=<YOUR_ADMIN_CORS>
|
||||
```
|
||||
|
||||
Where `<YOUR_ADMIN_CORS>` is the URL of your admin dashboard.
|
||||
|
||||
:::tip
|
||||
|
||||
Make sure that the URL is without a backslash at the end. For example, you should use `http://localhost:7000` instead of `http://localhost:7000/`.
|
||||
|
||||
:::
|
||||
|
||||
### Storefront CORS
|
||||
|
||||
To make sure your Storefront dashboard can access the Medusa backend, set this configuration:
|
||||
|
||||
```jsx
|
||||
module.exports = {
|
||||
projectConfig: {
|
||||
// ...other configurations
|
||||
store_cors: STORE_CORS,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Where `STORE_CORS` is the URL of your storefront. By default, it’s `http://localhost:8000`.
|
||||
|
||||
It is recommended to set the Storefront CORS as an environment variable:
|
||||
|
||||
```bash
|
||||
STORE_CORS=<YOUR_STORE_CORS>
|
||||
```
|
||||
|
||||
Where `<YOUR_STORE_CORS>` is the URL of your storefront.
|
||||
|
||||
:::tip
|
||||
|
||||
Make sure that the URL is without a backslash at the end. For example, you should use `http://localhost:8000` instead of `http://localhost:8000/`.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Plugins
|
||||
|
||||
On your Medusa backend, you can use Plugins to add custom features or integrate third-party services. For example, installing a plugin to use Stripe as a payment provider.
|
||||
|
||||
:::info
|
||||
|
||||
You can learn more about plugins in the [Plugins Overview documentation](../plugins/overview.mdx).
|
||||
|
||||
:::
|
||||
|
||||
Aside from installing the plugin with NPM, you need to pass the plugin you installed into the `plugins` array defined in `medusa-config.js`. This array is then exported along with other configurations you’ve added:
|
||||
|
||||
```jsx
|
||||
module.exports = {
|
||||
projectConfig: {
|
||||
// previous configurations mentioned...
|
||||
},
|
||||
plugins,
|
||||
}
|
||||
```
|
||||
|
||||
### Add a Plugin Without Configuration
|
||||
|
||||
To add a plugin that doesn’t need any configurations, you can simply add its name to the `plugins` array:
|
||||
|
||||
```jsx
|
||||
const plugins = [
|
||||
// other plugins...
|
||||
`medusa-my-plugin`,
|
||||
]
|
||||
```
|
||||
|
||||
### Add a Plugin With Configuration
|
||||
|
||||
To add a plugin with configurations, you need to add an object to the `plugins` array with the plugin’s name and configurations:
|
||||
|
||||
```jsx
|
||||
const plugins = [
|
||||
// other plugins...
|
||||
{
|
||||
resolve: `medusa-my-plugin`,
|
||||
options: {
|
||||
apiKey: `test`,
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
It is recommended to use environment variables to store values of options instead of hardcoding them in `medusa-config.js`.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Medusa architecture overview](../fundamentals/architecture-overview.md)
|
||||
- [Plugins](../plugins/overview.mdx)
|
||||
11
docs/content/development/backend/development.module.css
Normal file
11
docs/content/development/backend/development.module.css
Normal file
@@ -0,0 +1,11 @@
|
||||
.osTabs {
|
||||
background-color: var(--ifm-note-background);
|
||||
padding: 10px;
|
||||
border: 1px solid var(--ifm-note-border-color);
|
||||
border-radius: var(--ifm-global-radius);
|
||||
color: var(--ifm-alert-foreground-color);
|
||||
}
|
||||
|
||||
.osTabs li:not([aria-selected=true]) {
|
||||
color: var(--ifm-color-content);
|
||||
}
|
||||
104
docs/content/development/backend/install.mdx
Normal file
104
docs/content/development/backend/install.mdx
Normal file
@@ -0,0 +1,104 @@
|
||||
---
|
||||
description: 'This quickstart guide will help you set up a Medusa backend in three steps.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
import Feedback from '@site/src/components/Feedback';
|
||||
|
||||
# Install Medusa Backend
|
||||
|
||||
This document will guide you through setting up your Medusa backend in a three steps.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Node.js
|
||||
|
||||
Medusa supports Node versions 14 and 16. You can check which version of Node you have by running the following command:
|
||||
|
||||
```bash noReport
|
||||
node -v
|
||||
```
|
||||
|
||||
You can install Node from the [official website](https://nodejs.org/en/).
|
||||
|
||||
### Git
|
||||
|
||||
Git is required for this setup. You can find instructions on how to install it from the [Set up your dev environment documentation](../../development/backend/prepare-environment.mdx#git).
|
||||
|
||||
---
|
||||
|
||||
## Create a Medusa Backend
|
||||
|
||||
:::tip
|
||||
|
||||
It is recommended to use [Yarn](https://yarnpkg.com/getting-started/install) for the installation process as it's much faster than using NPM.
|
||||
|
||||
:::
|
||||
|
||||
### 1. Install Medusa CLI
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/medusa-cli -g
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
If you run into any errors while installing the CLI tool, check out the [troubleshooting guide](../../troubleshooting/cli-installation-errors.mdx).
|
||||
|
||||
:::
|
||||
|
||||
### 2. Create a new Medusa project
|
||||
|
||||
```bash noReport
|
||||
medusa new my-medusa-store --seed
|
||||
```
|
||||
|
||||
### 3. Start your Medusa backend
|
||||
|
||||
```bash noReport
|
||||
cd my-medusa-store
|
||||
medusa develop
|
||||
```
|
||||
|
||||
<Feedback
|
||||
event="survey_server_quickstart"
|
||||
question="Did you set up the backend successfully?"
|
||||
positiveQuestion="Is there anything that should improved?"
|
||||
negativeQuestion="Please describe the issue you faced."
|
||||
/>
|
||||
|
||||
### Test the Backend
|
||||
|
||||
After these three steps and in only a couple of minutes, you now have a complete commerce engine running locally. You can test it out by sending a request using a tool like Postman or through the command line:
|
||||
|
||||
```bash noReport
|
||||
curl localhost:9000/store/products
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Learn about the Architecture
|
||||
|
||||
Medusa backend is made up of different resources that make it a powerful server. Get an overview of them in the [Medusa Architecture Overview](../fundamentals/architecture-overview.md) documentation.
|
||||
|
||||
### Set Up Development Environment
|
||||
|
||||
For an optimal experience developing with Medusa and to make sure you can use its advanced functionalities, you'll need to install more tools such as Redis or PostgreSQL.
|
||||
|
||||
Follow [this documentation to learn how to set up your development environment](../../development/backend/prepare-environment.mdx).
|
||||
|
||||
### Backend Configurations
|
||||
|
||||
It's important to configure your Medusa backend properly and learn how environment variables are loaded.
|
||||
|
||||
You can learn more about configuring your backend and loading environment variables in the [Configure your Backend documentation](../../development/backend/configurations.md).
|
||||
|
||||
### File Service Plugin
|
||||
|
||||
To upload product images to your Medusa backend, you must install and configure one of the following file service plugins:
|
||||
|
||||
- [MinIO](../../plugins/file-service/minio.md) (Recommended for local development)
|
||||
- [S3](../../plugins/file-service/s3.md)
|
||||
- [DigitalOcean Spaces](../../plugins/file-service/spaces.md)
|
||||
288
docs/content/development/backend/prepare-environment.mdx
Normal file
288
docs/content/development/backend/prepare-environment.mdx
Normal file
@@ -0,0 +1,288 @@
|
||||
---
|
||||
description: 'Learn how to prepare your development environment while using Medusa. This guide includes how to install Node.js, Git, Medusa CLI tool, PostgreSQL, and Redis.'
|
||||
---
|
||||
|
||||
import styles from './development.module.css';
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Prepare Development Environment
|
||||
|
||||
This document will guide you to prepare your development environment to efficiently and properly use Medusa.
|
||||
|
||||
## Required Tools
|
||||
|
||||
To get your development environment ready you need to install the following tools:
|
||||
|
||||
### Node.js
|
||||
|
||||
Node.js is the environment that makes it possible for Medusa to run, so you must install Node.js on your computer to start Medusa development.
|
||||
|
||||
:::caution
|
||||
|
||||
Medusa supports versions 14 and 16 of Node.js. You can check your Node.js version using the following command:
|
||||
|
||||
```bash noReport
|
||||
node -v
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
<Tabs groupId="operating-systems" wrapperClassName={styles.osTabs}>
|
||||
<TabItem value="windows" label="Windows" default>
|
||||
|
||||
You can install the executable directly from [the Node.js website](https://nodejs.org/en/#home-downloadhead).
|
||||
|
||||
For other approaches, you can check out [Node.js’s guide](https://nodejs.org/en/download/package-manager/#windows-1).
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="linux" label="Linux">
|
||||
|
||||
You can use the following commands to install Node.js on Ubuntu:
|
||||
|
||||
```bash
|
||||
#Ubuntu
|
||||
sudo apt update
|
||||
sudo apt install nodejs
|
||||
```
|
||||
|
||||
For other Linux distributions, you can check out [Node.js’s guide](https://nodejs.org/en/download/package-manager/).
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="macos" label="macOS">
|
||||
|
||||
You can use the following commands to install Node.js on macOS:
|
||||
|
||||
<Tabs groupId="homebrew" wrapperClassName='code-tabs'>
|
||||
<TabItem value="homebrew" label="Homebrew">
|
||||
|
||||
```bash
|
||||
brew install node
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="no-homebrew" label="Without Homebrew">
|
||||
|
||||
```bash
|
||||
curl \
|
||||
"https://nodejs.org/dist/latest/node-${VERSION:-$(wget -qO- \
|
||||
https://nodejs.org/dist/latest/ | sed -nE \
|
||||
's|.*>node-(.*)\.pkg</a>.*|\1|p')}.pkg" \
|
||||
> "$HOME/Downloads/node-latest.pkg" &&
|
||||
sudo installer -store -pkg "$HOME/Downloads/node-latest.pkg" -target "/"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
For other approaches, you can check out [Node.js’s guide](https://nodejs.org/en/download/package-manager/#macos).
|
||||
|
||||
:::tip
|
||||
|
||||
Make sure that you have Xcode command line tools installed; if not, run the following command to install it: `xcode-select --install`
|
||||
|
||||
:::
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Git
|
||||
|
||||
Medusa uses Git behind the scenes when you create a new project so you'll have to install it on your computer to get started.
|
||||
|
||||
<Tabs groupId="operating-systems" wrapperClassName={styles.osTabs}>
|
||||
<TabItem value="windows" label="Windows" default>
|
||||
|
||||
To install Git on Windows, you need to [download the installable package](https://git-scm.com/download/win).
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="linux" label="Linux">
|
||||
|
||||
For Debian/Ubuntu, you can use the following command:
|
||||
|
||||
```bash
|
||||
apt-get install git
|
||||
```
|
||||
|
||||
As for other Linux distributions, please check [git’s guide](https://git-scm.com/download/linux).
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="macos" label="macOS">
|
||||
|
||||
You should already have Git installed as part of the Xcode command-line tools.
|
||||
|
||||
However, if for any reason you need to install it manually, you can install it with Homebrew:
|
||||
|
||||
```bash
|
||||
brew install git
|
||||
```
|
||||
|
||||
You can also check out [git’s guide](https://git-scm.com/download/mac) for more installation options.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Medusa CLI
|
||||
|
||||
The final installation required to get started with Medusa is the Medusa CLI. It is an NPM package you can install globally on your machine to get instant access to commands that help you manage and run your Medusa project.
|
||||
|
||||
You can install Medusa’s CLI with the following command:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/medusa-cli -g
|
||||
```
|
||||
|
||||
You can check that Medusa was installed by running the following command:
|
||||
|
||||
```bash noReport
|
||||
medusa -v
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
If you run into any errors while installing the CLI tool, check out the [troubleshooting guide](../../troubleshooting/cli-installation-errors.mdx).
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Install Medusa Backend
|
||||
|
||||
If you're not interested in installing the optional tools and want to get started with Medusa quickly, check out the [Medusa Backend Quickstart](./install.mdx).
|
||||
|
||||
---
|
||||
|
||||
## Optional Tools
|
||||
|
||||
These tools are not required to have to run a Medusa backend, but it's highly recommended that you have them installed.
|
||||
|
||||
### PostgreSQL
|
||||
|
||||
Although you can use an SQLite database with Medusa which would require no necessary database installations, it is recommended to use a PostgreSQL database for your backend.
|
||||
|
||||
:::tip
|
||||
|
||||
After installing PostgreSQL, check out the [Configure your Backend documentation](./configurations.md#postgresql-configurations) to learn how to configure PostgreSQL to work with Medusa.
|
||||
|
||||
:::
|
||||
|
||||
<Tabs groupId="operating-systems" wrapperClassName={styles.osTabs}>
|
||||
<TabItem value="windows" label="Windows">
|
||||
|
||||
You can [download the PostgreSQL Windows installer](https://www.postgresql.org/download/windows/) from their website.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="linux" label="Linux">
|
||||
|
||||
If you’re using Ubuntu, you can use the following commands to download and install PostgreSQL:
|
||||
|
||||
```bash
|
||||
sudo sh -c \
|
||||
'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
|
||||
wget --quiet -O - \
|
||||
https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
|
||||
sudo apt-get update
|
||||
sudo apt-get -y install postgresql
|
||||
```
|
||||
|
||||
For other distributions, you can check out [PostgreSQL’s website for more guides](https://www.postgresql.org/download/linux/).
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="macos" label="macOS">
|
||||
|
||||
You can download PostgreSQL on your macOS using [the installer on their website](https://www.postgresql.org/download/macosx/).
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="docker" label="Docker">
|
||||
|
||||
Make sure the Docker Desktop app is running, then run the following command to quickly spin up a PostgreSQL instance:
|
||||
|
||||
```bash
|
||||
docker run --name postgres -e POSTGRES_USER=postgres \
|
||||
-e POSTGRES_PASSWORD=postgres -e \
|
||||
POSTGRES_DB=medusa-docker -p 5432:5432 -d postgres
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
- `--name` creates a new container named `postgres`.
|
||||
- `-e` creates environment variables `POSTGRES_USER`, `POSTGRES_PASSWORD` and `POSTGRES_DB`. These will be used to set up a database named `medusa-docker` with the username and password being `postgres`.
|
||||
- `-p` maps the container port `5432` to the external host `5432`. This allows you to connect to the database backend from outside of the container.
|
||||
- `-d` enables Docker to run the container in the background.
|
||||
- The last section of the command, `postgres` grabs the latest postgres image from the Docker hub.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Redis
|
||||
|
||||
Medusa uses Redis as the event queue in the backend. If you want to use subscribers to handle events such as when an order is placed and perform actions based on the events, then you need to install and configure Redis.
|
||||
|
||||
If you don’t install and configure Redis with your Medusa backend, then it will work without any events-related features.
|
||||
|
||||
:::tip
|
||||
|
||||
After installing Redis, check out the [Configure your Backend documentation](./configurations.md#redis) to learn how to configure Redis to work with Medusa.
|
||||
|
||||
:::
|
||||
|
||||
<Tabs groupId="operating-systems" wrapperClassName={styles.osTabs}>
|
||||
<TabItem value="windows" label="Windows">
|
||||
|
||||
To use Redis on Windows, you must have [Windows Subsystem for Linux (WSL2) enabled](https://docs.microsoft.com/en-us/windows/wsl/install). This lets you run Linux binaries on Windows.
|
||||
|
||||
After installing and enabling WSL2, if you use an Ubuntu distribution you can run the following commands to install Redis:
|
||||
|
||||
```bash
|
||||
sudo apt-add-repository ppa:redislabs/redis
|
||||
sudo apt-get update
|
||||
sudo apt-get upgrade
|
||||
sudo apt-get install redis-server
|
||||
|
||||
## Start Redis server
|
||||
sudo service redis-server start
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="linux" label="Linux">
|
||||
|
||||
If you use Ubuntu you can use the following commands to install Redis:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://packages.redis.io/gpg | \
|
||||
sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
|
||||
|
||||
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" \
|
||||
| sudo tee /etc/apt/sources.list.d/redis.list
|
||||
|
||||
sudo apt-get update
|
||||
sudo apt-get install redis
|
||||
|
||||
## Start Redis server
|
||||
sudo service redis-server start
|
||||
```
|
||||
|
||||
For other distributions, you can check out [Redis’ guide on this](https://redis.io/docs/getting-started/installation/install-redis-on-linux/).
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="macos" label="macOS">
|
||||
|
||||
You can install Redis on macOS using Homebrew with the following command:
|
||||
|
||||
```bash
|
||||
brew install redis
|
||||
|
||||
## Start Redis server
|
||||
brew services start redis
|
||||
```
|
||||
|
||||
To install Redis without Homebrew you can check out [Redis’s guide on installing it from source](https://redis.io/docs/getting-started/installation/install-redis-from-source/).
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Install Medusa backend](./install.mdx)
|
||||
- [Configure the Medusa backend](./configurations.md)
|
||||
Reference in New Issue
Block a user