added configurations documentation (#1696)

docs/content/add-plugins/slack.md

@@ -33,7 +33,7 @@ Medusa's event system works by pushing data into a queue that is based on [Redis
 
 As the Slack plugin will listen to the `order.placed` event to know when to send notifications, you'll need to have Redis installed and configured with your Medusa server.
 
-You can read the [Set up your development enviornment guideline](https://docs.medusajs.com/tutorial/set-up-your-development-environment) to learn more about how you can install and setup Redis.
+You can read the [Set up your development enviornment guideline](../tutorial/0-set-up-your-development-environment.mdx#redis) to learn more about how you can install and setup Redis.
 
 ## Create Slack App
 

docs/content/admin/quickstart.md

@@ -101,6 +101,12 @@ ADMIN_CORS=<YOUR_ADMIN_URL>
 
 Make sure to replace `<YOUR_ADMIN_URL>` with your URL.
 
+:::info
+
+For more details about the Admin CORS configuration, check out the [Configure your Server documentation](../usage/configurations.md#admin-cors).
+
+:::
+
 ## Admin Features Overview
 
 ### Order Management

docs/content/homepage.md

@@ -40,9 +40,9 @@ Medusa comes with a set of building blocks that allow you to create unique digit
 
 ### The Medusa Server
 
-The first step is to [set up your development environment](tutorial/set-up-your-development-environment) with the requirements necessary to run a Medusa server.
+You can follow our [quickstart guide](quickstart/quick-start.md) to install and run a Medusa server.
 
-Then, you can follow our [quickstart guide](quickstart/quick-start.md) to install and run a Medusa server.
+It's also recommended to learn how to [set up your development environment](tutorial/set-up-your-development-environment) with the requirements tools and services to run a Medusa server, then [configure your Medusa server](usage/configurations.md).
 
 ### The Medusa Admin
 

docs/content/quickstart/quick-start.md

@@ -67,37 +67,11 @@ To upload product images to your Medusa server, you must install and configure o
 - [S3](../add-plugins/s3.md)
 - [DigitalOcean Spaces](../add-plugins/spaces.md)
 
-### Environment Variables
+### Server Configurations
 
-Medusa allows you to choose how to load your environment variables. By default, it will only load environment variables on your system.
+It's important to configure your Medusa server properly and learn how environment variables are loaded.
 
-If you want to load environment variables from a `.env` file add the following at the top of `medusa-config.js`:
+You can learn more about configuring your server and loading environment variables in the [Configure your Server documentation](../usage/configurations.md).
-
-```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) {
- }
-```
 
 ## What's next :rocket:
 

docs/content/starters/gatsby-medusa-starter.md

@@ -69,6 +69,12 @@ Then, on your server, update the environment variable `STORE_CORS` to the URL wi
 STORE_CORS=http://localhost:<PORT>
 ```
 
+:::info
+
+For more details about the Store CORS configuration, check out the [Configure your Server documentation](../usage/configurations.md#storefront-cors).
+
+:::
+
 ### Development Resources
 
 If you’re not familiar with Gatsby, you can learn more about it through the following resources:

docs/content/starters/nextjs-medusa-starter.md

@@ -67,6 +67,12 @@ Then, on your server, update the environment variable `STORE_CORS` to the URL
 STORE_CORS=http://localhost:<PORT>
 ```
 
+:::info
+
+For more details about the Store CORS configuration, check out the [Configure your Server documentation](../usage/configurations.md#storefront-cors).
+
+:::
+
 ### Development Resources
 
 You can learn more about development with Next.js through [their documentation](https://nextjs.org/docs/getting-started).

docs/content/tutorial/0-set-up-your-development-environment.mdx

@@ -177,6 +177,12 @@ PostgreSQL is an open-source relational database system with more than 30 years
 
 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 server.
 
+:::tip
+
+After installing PostgreSQL, check out the [Configure your Server documentation](../usage/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">
 
@@ -216,6 +222,12 @@ Medusa uses Redis as the event queue in the server. If you want to use subscribe
 
 If you don’t install and configure Redis with your Medusa server, then it will work without any events-related features.
 
+:::tip
+
+After installing Redis, check out the [Configure your Server documentation](../usage/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">
 
@@ -290,75 +302,8 @@ Here are some other options:
 
 It is not important which editor you use as long as you feel comfortable working with it.
 
-## Configuring Your Server
-
-After installing all the requirements mentioned above and following along with our [quickstart guide](../quickstart/quick-start.md), you need to configure some information on your server to connect it to some of the requirements you installed.
-
-### PostgreSQL
-
-After creating a new database schema in PostgreSQL, you need to add the URL to connect to it on your Medusa server.
-
-To do that, add the following environment variable to the `.env` file on the root of your Medusa server:
-
-```bash
-DATABASE_URL=postgres://<USER>:<PASSWORD>@<HOST>:<PORT>/<DB_NAME>
-```
-
-Notice that there are some details in the URL above you need to fill in yourself:
-
-- `<USER>`: the username of the user that has access to the database schema you created.
-- `<PASSWORD>`: the password of the user that has access to the database schema you created.
-- `<HOST>`: the hostname where the PostgreSQL database is hosted. In local development, you can use `localhost`.
-- `<PORT>`: the port where the PostgreSQL database can be contacted on the host. By default, it’s 5432**.**
-- `<DB_NAME>`: the name of the database schema you created.
-
-Then, in `medusa-config.js`, change the following properties in the object `projecConfig`:
-
-```jsx
-module.exports = {
-  projectConfig: {
-    ...,
-    database_url: DATABASE_URL,
-    database_type: "postgres",
-    // comment out or remove these lines:
-    // database_database: "./medusa-db.sql",
-    // database_type: "sqlite",
-  },
-  plugins,
-};
-```
-
-The last recommended step is running the following command to migrate Medusa’s database schema into your database and seed the database with dummy data:
-
-```bash npm2yarn
-npm run seed
-```
-
-### Redis
-
-After installing Redis and running the Redis server, you must configure Medusa to use it.
-
-In `.env` add a new environment variable:
-
-```bash
-REDIS_URL=redis://localhost:6379
-```
-
-This is the default Redis URL to connect to, especially in development. However, if you’re deploying your server, have configured your Redis installation differently, or just need to check the format of the connection URL, you can check [this guide](https://github.com/lettuce-io/lettuce-core/wiki/Redis-URI-and-connection-details) for more details.
-
-:::tip
-
-If you use the default connection string mentioned here then you can skip over adding the environment variable.
-
-:::
-
-Then, in `medusa-config.js`, comment out the following line in the object `projectConfig`:
-
-```jsx
-redis_url: REDIS_URL,
-```
-
 ## What’s Next 🚀
 
+- Learn how to [configure your Medusa server](../usage/configurations.md).
 - Learn how to install a storefront with [Next.js](../starters/nextjs-medusa-starter.md) or [Gatsby](./../starters/gatsby-medusa-starter.md).
 - Learn how to install the [Medusa Admin](../admin/quickstart.md).

docs/content/usage/configurations.md

@@ -0,0 +1,286 @@
+# 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](../tutorial/0-set-up-your-development-environment.mdx) 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](../advanced/backend/upgrade-guides/1-3-0.md).
+
+:::
+
+### 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`:
+
+```jsx
+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](https://www.npmjs.com/package/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:
+
+```npm2yarn
+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:
+
+```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
+
+For PostgreSQL you mainly need 2 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).
+
+### 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]`.
+
+:::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](../advanced/backend/subscribers/create-subscriber.md).
+
+:::
+
+## JSON Web Token (JWT) Secret
+
+Medusa uses 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.
+
+:::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:
+
+```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.
+
+:::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:
+
+```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`.
+
+## 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:
+
+```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`.
+
+## 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](../advanced/backend/plugins/overview.md).
+
+:::
+
+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`
+    }
+  }
+];
+```
+
+## What’s Next 🚀
+
+- Check out our [Next.js](../starters/nextjs-medusa-starter.md) and [Gatsby](../starters/gatsby-medusa-starter.md) starter storefronts.
+- Install the [Medusa admin](../admin/quickstart.md).
+- Learn about [deploying the Medusa server on Heroku](../how-to/deploying-on-heroku.md).

www/docs/sidebars.js

@@ -40,6 +40,11 @@ module.exports = {
           id: "tutorial/set-up-your-development-environment",
           label: "Set Up your Development Environment"
         },
+        {
+          type: "doc",
+          id: "usage/configurations",
+          label: "Configure your Server"
+        },
         {
           type: "category",
           collapsed: true,