8.1 KiB
Configure your Server
In this document, you’ll learn what configurations you can add to your Medusa server and how to add them.
Prerequisites
This document assumes you already followed along with the “Set up your development environment” documentation and have installed a Medusa server.
Medusa Configurations File
The configurations for your Medusa server 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.
:::
Load from .env
A common way to use environment variables during development or in production is using .env files.
To load environment variables from a .env file, add the following at the top of medusa-config.js:
const dotenv = require('dotenv')
let ENV_FILE_NAME = '';
switch (process.env.NODE_ENV) {
case 'production':
ENV_FILE_NAME = '.env.production';
break;
case 'staging':
ENV_FILE_NAME = '.env.staging';
break;
case 'test':
ENV_FILE_NAME = '.env.test';
break;
case 'development':
default:
ENV_FILE_NAME = '.env';
break;
}
try {
dotenv.config({ path: process.cwd() + '/' + ENV_FILE_NAME });
} catch (e) {
//handle error
}
This code snippet uses the dotenv library to load environment variables from a local file. The file chosen to be loaded will be loaded based on the current environment.
:::note
dotenv should be available to use in your Medusa server project without the need to install it. However, if it’s not available you can install it with the following command:
npm install dotenv --save
:::
Database Configuration
Medusa supports 2 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 2 configurations:
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
For PostgreSQL you mainly need 2 configurations:
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.
Common Configuration
As Medusa internally uses Typeorm to connect to the database, the following configurations are also available:
database_logging: enable or disable logging.database_extra: extra options that you can pass to the underlying database driver.
These configurations are not required and can be omitted.
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:
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].
:::tip
By default, the Redis connection string should be redis://localhost:6379 unless you made any changes to the default configurations during the installation.
:::
If you omit this configuration, events will not be emitted and subscribers will not work.
:::info
You can learn more about Subscribers and events in the Subscriber documentation.
:::
JSON Web Token (JWT) Secret
Medusa uses JWT to handle user authentication. To set the JWT secret:
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.
:::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 server will crash.
:::
Cookie Secret
This configuration is used to sign the session ID cookie. To set the cookie secret:
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.
:::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 server will crash.
:::
Admin CORS
Medusa uses Cross-Origin Resource Sharing (CORS) to only allow specific origins to access the server. To make sure your Admin dashboard can access the Medusa server’s admin endpoints, set this configuration:
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.
Storefront CORS
Medusa uses CORS to only allow specific origins to access the server. To make sure your Storefront dashboard can access the Medusa server, set this configuration:
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.
Plugins
On your Medusa server, 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.
:::
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:
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:
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:
const plugins = [
//other plugins...
{
resolve: `medusa-my-plugin`,
options: {
apiKey: `test`
}
}
];
What’s Next 🚀
- Check out our Next.js and Gatsby starter storefronts.
- Install the Medusa admin.
- Learn about deploying the Medusa server on Heroku.