465 lines
14 KiB
Markdown
465 lines
14 KiB
Markdown
---
|
||
description: 'Learn about the different configurations available in a Medusa backend. This includes configurations related to the database, CORS, plugins, 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 [Prepare 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, modules, 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.
|
||
|
||
---
|
||
|
||
## Database Configuration
|
||
|
||
Medusa only supports using a PostgreSQL database.
|
||
|
||
### 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).
|
||
|
||
:::
|
||
|
||
The following configurations are required for PostgreSQL
|
||
|
||
```js
|
||
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. The connection URL should be of the following format:
|
||
|
||
```bash
|
||
postgres://[user][:password]@[host][:port]/[dbname]
|
||
```
|
||
|
||
Where:
|
||
|
||
- `[user]`: (required) your PostgreSQL username. If not specified, the system's username is used by default.
|
||
- `[:password]`: an optional password for the user. When provided, make sure to put `:` before the password.
|
||
- `[host]`: (required) your PostgreSQL host. When run locally, it should be `localhost`.
|
||
- `[:post]`: an optional port that the PostgreSQL server is listening on. By default, it's `5432`. When provided, make sure to put `:` before the port.
|
||
- `[dbname]`: (required) the name of the database.
|
||
|
||
For example, the connection URL can be `postgres://postgres@localhost/medusa-store`.
|
||
|
||
You can learn more about the connection URL format 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://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 or Setting Database
|
||
|
||
Remember to run migrations after you change or set your database:
|
||
|
||
```bash
|
||
npx @medusajs/medusa-cli 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.
|
||
|
||
```js
|
||
module.exports = {
|
||
projectConfig: {
|
||
// ...other configurations
|
||
database_logging: true,
|
||
database_extra: {},
|
||
},
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Redis
|
||
|
||
:::note
|
||
|
||
As of v1.8 of the Medusa core package, Redis is only used for scheduled jobs. For events handling, it's now moved into a module and can be configured as explained [here](#modules).
|
||
|
||
:::
|
||
|
||
You must first have Redis installed. You can refer to [Redis's installation guide](https://redis.io/docs/getting-started/installation/). You need to set Redis URL in the configurations:
|
||
|
||
```js
|
||
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, scheduled jobs 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.
|
||
|
||
---
|
||
|
||
## 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:
|
||
|
||
```js
|
||
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:
|
||
|
||
```js
|
||
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:
|
||
|
||
```js
|
||
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 processor.
|
||
|
||
:::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`.
|
||
|
||
:::
|
||
|
||
---
|
||
|
||
## Modules
|
||
|
||
In Medusa, commerce and core logic are modularized to allow developers to extend or replace certain modules with custom implementations.
|
||
|
||
:::tip
|
||
|
||
You can learn more about Modules in the [Modules Overview documentation](../modules/overview.mdx).
|
||
|
||
:::
|
||
|
||
Aside from installing the module with NPM, you need to add into the exported object in `medusa-config.js`. For example:
|
||
|
||
```js
|
||
module.exports = {
|
||
// ...
|
||
modules: {
|
||
// ...
|
||
moduleType: {
|
||
resolve: "<module_name>",
|
||
options: {
|
||
// options if necessary
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
`moduleType` and `<module_name>` are just placeholder that should be replaced based on the type of Module you're adding. For example, if you used the default Medusa starter to create your backend, you should have an `eventBus` module installed:
|
||
|
||
```js
|
||
module.exports = {
|
||
// ...
|
||
modules: {
|
||
// ...
|
||
eventBus: {
|
||
resolve: "@medusajs/event-bus-local",
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
Each module can have its own options. You must refer to the module's documentation to learn about its options.
|
||
|
||
### Recommended Event Bus Modules
|
||
|
||
In the default Medusa starter, the local event bus module is used. This module is good for testing out Medusa and during development, but it's highly recommended to use the [Redis event module](../events/modules/redis.md) instead for better development experience and during production.
|
||
|
||
### Recommended Cache Modules
|
||
|
||
In the default Medusa starter, the in-memory cache module is used. This module is good for testing out Medusa and during development, but it's highly recommended to use the [Redis cache module](../cache/modules/redis.md) instead for better development experience and during production.
|
||
|
||
---
|
||
|
||
## HTTP Compression
|
||
|
||
This configuration enables HTTP compression from the application layer. If you have access to the HTTP server, the recommended approach would be to enable it there. However, some platforms don't offer access to the HTTP layer and in those cases, this is a good alternative.
|
||
|
||
To enable HTTP compression, add the `http_compression` option in the `projectConfig` property in `medusa-config.js`:
|
||
|
||
```js title=medusa-config.js
|
||
module.exports = {
|
||
projectConfig: {
|
||
// ...other configurations
|
||
http_compression: {
|
||
enabled: true,
|
||
// optional settings
|
||
level: 6,
|
||
memLevel: 8,
|
||
threshold: 1024,
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
Where:
|
||
|
||
- `enabled`: A boolean flag that indicates where HTTP compression is enabled. It is disabled by default.
|
||
- `level`: A `number` value that indicates the level of zlib compression to apply to responses. A higher level will result in better compression, but will take longer to complete. A lower level will result in less compression, but will be much faster. Default value is 6.
|
||
- `memLevel`: A `number` value that specifies how much memory should be allocated for the internal compression state. It's an integer in the range of 1 (minimum level) and 9 (maximum level). The default value is 8.
|
||
- `threshold`: A `number` or a `string` value in bytes that specifies the minimum response body size that compression is applied on. This is the number of bytes or any string accepted by the bytes module. The default value is `1024`.
|
||
|
||
To disable compression for specific endpoints, you can pass in the request header `"x-no-compression": true`.
|
||
|
||
|
||
:::tip
|
||
|
||
The Medusa core package uses the [compression package provided by Express](https://github.com/expressjs/compression) to perform the HTTP compression.
|
||
|
||
:::
|
||
|
||
---
|
||
|
||
## See Also
|
||
|
||
- [Medusa architecture overview](../fundamentals/architecture-overview.md)
|
||
- [Plugins](../plugins/overview.mdx)
|
||
- [Modules](../modules/overview.mdx)
|