From 1cc4f9ac2dd6350e29ab811110d5ae5aecc9f2c8 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 27 Jun 2022 16:57:24 +0300 Subject: [PATCH] docs: improve troubleshooting (#1739) * docs: improve troubleshooting * fixes --- docs/content/troubleshooting/cors-issues.md | 12 +++-- .../troubleshooting/documentation-error.md | 6 +-- .../missing-payment-providers.md | 15 ++++-- docs/content/troubleshooting/redis-events.md | 30 +++++++----- .../troubleshooting/signing-in-to-admin.md | 13 +++-- .../transaction-error-in-checkout.md | 48 ++++++++++++------- 6 files changed, 78 insertions(+), 46 deletions(-) diff --git a/docs/content/troubleshooting/cors-issues.md b/docs/content/troubleshooting/cors-issues.md index e1611aa11d..6cad1e6b18 100644 --- a/docs/content/troubleshooting/cors-issues.md +++ b/docs/content/troubleshooting/cors-issues.md @@ -1,21 +1,25 @@ # CORS issues -If you are experiencing connection issues when trying to access your Medusa instance from a storefront, it is most likely due to CORS issues. +If you are experiencing connection issues when trying to access your Medusa server from a storefront, it is most likely due to CORS issues. You might see a log in your browser console, that looks like this: ![CORS error log](https://i.imgur.com/jnHK115.png) -In your `medusa-config.js` , you should ensure that you've configured your CORS settings correctly. By default, the Medusa starter run on port 9000, Medusa Admin on port 7000, and the storefront starters on port 8000. +In your `medusa-config.js` , you should ensure that you've configured your CORS settings correctly. By default, the Medusa starter runs on port `9000`, Medusa Admin runs on port `7000`, and the storefront starters run on port `8000`. The default configuration uses the following CORS settings: ```jsx // CORS when consuming Medusa from admin -const ADMIN_CORS = process.env.ADMIN_CORS || "http://localhost:7000" +const ADMIN_CORS = process.env.ADMIN_CORS || "http://localhost:7000,http://localhost:7001" // CORS to avoid issues when consuming Medusa from a client const STORE_CORS = process.env.STORE_CORS || "http://localhost:8000" ``` -If you wish to run your storefront or Medusa admin on other ports, you should update the above settings accordinly. +If you wish to run your storefront or Medusa admin on other ports, you should update the above settings accordingly. + +## Additional Resources + +To learn more about CORS configurations, check out the [Configure your Server](../usage/configurations.md) documentation. diff --git a/docs/content/troubleshooting/documentation-error.md b/docs/content/troubleshooting/documentation-error.md index 4769bbfad0..d16945be1d 100644 --- a/docs/content/troubleshooting/documentation-error.md +++ b/docs/content/troubleshooting/documentation-error.md @@ -1,7 +1,7 @@ # Documentation Error -If you have installed the dependencies in the root of this repository (i.e., if you have a `node_modules` directory at the root of this repository), this will cause an error when running this documentation website. This is because the content resides in `docs/content` and when that content is being imported from there, a mix up can happen between the dependencies which will cause an `invalid hook call` error. +If you have installed the dependencies in the root of the Medusa repository (i.e., if you have a `node_modules` directory at the root of the Medusa repository), this will cause an error when running the documentation website. -For that reason, we added a `clean-node-modules` script that deletes the `node_modules` directory, and we call that script before the `start` and `build` scripts are ran. +This is because the content resides in `docs/content`. When that content is being imported from there, a mix up can happen between the dependencies in the root of the Medusa repository and the dependencies in `www/docs` which causes an `invalid hook call` error. -So, everytime you run these 2 scripts, the `node_modules` directory at the root will be deleted. +For that reason, when the `start` and `build` scripts in `www/docs` are used, the `clean-node-modules` script is called. This script deleted the `node_modules` directory in the root of the Medusa repository. diff --git a/docs/content/troubleshooting/missing-payment-providers.md b/docs/content/troubleshooting/missing-payment-providers.md index e0ab0ae5c8..edca037a70 100644 --- a/docs/content/troubleshooting/missing-payment-providers.md +++ b/docs/content/troubleshooting/missing-payment-providers.md @@ -1,4 +1,4 @@ -# Stripe not showing in checkout +# Payment Provider (Stripe) not showing in checkout You add payment providers to your Medusa instance by adding them as plugins in `medusa-config.js`: @@ -17,14 +17,19 @@ const plugins = [ ]; ``` -And installing them through your favourite package manager: +And installing them with your favourite package manager: ```bash npm2yarn npm install medusa-payment-stripe ``` -Though, to be able to also show them as part of your checkout flow, you need to add them to your regions. +However, to also show them as part of your checkout flow you need to add them to your regions. -In Medusa Admin go to Settings -> Regions and select your newly added payment provider: +In the Medusa Admin go to Settings > Regions and for each region scroll down to the Payment Provider input and choose the payment provider you want to use in that region: -![](https://i.imgur.com/CfR9BCV.png) +![Enable Payment Provider](https://i.imgur.com/FH5vgWh.png) + +## Additional Resources + +- Learn how to install [Stripe](../add-plugins/stripe.md) as a payment provider. +- Learn more about the [Payment architecture](../advanced/backend/payment/overview.md). diff --git a/docs/content/troubleshooting/redis-events.md b/docs/content/troubleshooting/redis-events.md index d47d566f7f..c730cf6761 100644 --- a/docs/content/troubleshooting/redis-events.md +++ b/docs/content/troubleshooting/redis-events.md @@ -1,25 +1,29 @@ # Redis not emitting events -When you create a new Medusa project, Redis is disabled by default. Instead, we use a fake Redis server, that allows you to start your project, but holds no functionality. +When you create a new Medusa server, Redis is disabled by default. Instead, a fake Redis server is used that allows you to start your project but does not actually emit any events. -To enable a real Redis server, you need to install and start it up on your PC. Install it directly from their [website](https://redis.io/download) or use Homebrew and run the following commands: +To enable a real Redis server, you need to install Redis on your machine and configure it with Medusa. -```bash -brew install redis -brew services start redis -``` +You can learn how to [install Redis in the Set Up your Development Environment documentation](../tutorial/0-set-up-your-development-environment.mdx#redis). -Additonally, ensure that `redis_url` is not commented out in your project configuration in the bottom of your `medusa-config.js`. +After installing it, make sure to configure your Medusa server to use Redis: ```jsx module.exports = { projectConfig: { - redis_url: REDIS_URL, // <-- Enables a real Redis server - database_url: DATABASE_URL, - database_type: "postgres", - store_cors: STORE_CORS, - admin_cors: ADMIN_CORS, + //... + redis_url: REDIS_URL, }, - plugins, } ``` + +By default, Medusa connects to Redis over the URL `redis://localhost:6379`. If you need to change that URL, set the following environment variable: + +```bash +REDIS_URL= +``` + +## Additional Resources + +- Learn how to [set up your development environment](../tutorial/0-set-up-your-development-environment.mdx). +- Learn how to [configure your server](../usage/configurations.md). diff --git a/docs/content/troubleshooting/signing-in-to-admin.md b/docs/content/troubleshooting/signing-in-to-admin.md index 6df2d6ec13..4896aa7225 100644 --- a/docs/content/troubleshooting/signing-in-to-admin.md +++ b/docs/content/troubleshooting/signing-in-to-admin.md @@ -1,13 +1,18 @@ # Signing in to Medusa Admin -If you've created a new Medusa project and seeded the database using our predefined script, the default credentials are: +If you've created a new Medusa server with the `--seed` option or used the `seed` script or command, the default credentials are: ```bash -admin@medusa-test.com // supersecret +email: admin@medusa-test.com +password: supersecret ``` -Though, you can create your own users using our CLI: +Alternatively, you can create your own users using the Medusa CLI tool: -``` +```bash medusa user -e some@email.com -p somepassword ``` + +## Additional Resources + +Learn more about our CLI tool in the [CLI reference](../cli/reference.md). diff --git a/docs/content/troubleshooting/transaction-error-in-checkout.md b/docs/content/troubleshooting/transaction-error-in-checkout.md index 42a2e7e7b8..9b096505d8 100644 --- a/docs/content/troubleshooting/transaction-error-in-checkout.md +++ b/docs/content/troubleshooting/transaction-error-in-checkout.md @@ -1,45 +1,59 @@ # Error 409 in checkout -To provide the most frictionless onboarding and quick start, we default to SQLite as database. SQLite runs on all PCs, which is why it allows you to get quickly started without installing Postgres. Though, it comes at the expense of important features, that are needed in a production environment. +To provide the most frictionless onboarding and quickstart, Medusa uses SQLite as the server's database by default. SQLite runs on all machines and operating systems. So, it allows you to get quickly started without installing PostgreSQL. -Therefore, you might experience the following error when going through a checkout flow in our starters: +However, this comes at the expense of important features that are needed in a production environment. -``` +Therefore, you might experience the following error when going through a checkout flow in one of Medusa's starters while using SQLite: + +```bash Error: Transaction already started for the given connection, commit current transaction before starting a new one. ``` -This error occurs because SQLite does not allow for multiple write transactions at the same time. To resolve it, you need to use Postgres instead. +This error occurs because SQLite does not allow for multiple write transactions at the same time. To resolve it, you need to use PostgreSQL instead. -First install and start Postgres on your local machine. You can either [download it directly from their website](https://www.postgresql.org/download/) or use Homebrew: +You can learn how to install PostgreSQL on your machine in the [Set Up your Development Environment documentation](../tutorial/0-set-up-your-development-environment.mdx#postgresql). -```bash -brew install postgresql -brew services start postgresql -createdb -``` - -Then in your `medusa-config.js`, you should change the project config to use Postgres as database type: +Then in your `medusa-config.js`, you should change the project configuration to use Postgres as the database type: ```jsx module.exports = { projectConfig: { - redis_url: REDIS_URL, - // The following two lines will enable Postgres + //... database_url: DATABASE_URL, database_type: "postgres", - store_cors: STORE_CORS, - admin_cors: ADMIN_CORS, }, plugins, } ``` +Where `DATABASE_URL` is the 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). + +Make sure to also remove the following lines that are used to configure an SQLite database: + +```jsx +database_type: "sqlite", +database_database: "./medusa-db.sql", +``` + +Then, migrate the database schema to the new PostgreSQL database: + +```bash +medusa migrations run +``` + :::tip -When changing from SQLite to Postgres, you should seed the database again using: +If you want to add demo data into your server, you should also seed the database using the following command: ```bash npm2yarn npm run seed ``` ::: + +## Additional Resources + +- Learn how to [set up your development environment](../tutorial/0-set-up-your-development-environment.mdx). +- Learn how to [configure your server](../usage/configurations.md). +- Learn more about [the Medusa CLI tool](../cli/reference.md).