From 3b5590ccecbf668ff96453240fb24775711e5c89 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Thu, 17 Aug 2023 20:21:32 +0300 Subject: [PATCH] docs: added new database options for create-medusa-app (#4777) * docs: added new database options for create-medusa-app * update note * removed stable option * add example to connect to Vercel or Supabase database * added a note about --db-url option * added a note about --no-migrations * added troubleshooting guide for invalid token error with no-browser * fix link --- www/docs/content/create-medusa-app.mdx | 60 ++++++++++++++----- .../create-medusa-app-errors.mdx | 7 +++ .../_no-browser-token-error.md | 5 ++ 3 files changed, 57 insertions(+), 15 deletions(-) create mode 100644 www/docs/content/troubleshooting/create-medusa-app-errors/_no-browser-token-error.md diff --git a/www/docs/content/create-medusa-app.mdx b/www/docs/content/create-medusa-app.mdx index bf8568f5e8..793d4deed2 100644 --- a/www/docs/content/create-medusa-app.mdx +++ b/www/docs/content/create-medusa-app.mdx @@ -6,7 +6,6 @@ addHowToData: true import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import Feedback from '@site/src/components/Feedback'; -import DocCard from '@theme/DocCard'; import DocCardList from '@theme/DocCardList'; import Icons from '@theme/Icon'; import Troubleshooting from '@site/src/components/Troubleshooting' @@ -16,6 +15,7 @@ import EagainError from "./troubleshooting/create-medusa-app-errors/_eagain-erro import ConnectionErrorSection from './troubleshooting/database-errors/_connection-error.md' import FreshInstallationSection from './troubleshooting/awilix-resolution-error/_fresh-installation.md' import EaddrinuseSection from './troubleshooting/eaddrinuse.md' +import InvalidTokenError from './troubleshooting/create-medusa-app-errors/_no-browser-token-error.md' # Install Medusa with create-medusa-app @@ -23,7 +23,7 @@ In this document, you’ll learn how to use create-medusa-app to set up a Medusa :::tip -`create-medusa-app` allows you to install and setup a Medusa backend project with minimal configurations. If you're more familiar with Medusa and you need to have more control over the configurations of the Medusa backend, please use the [backend quickstart instead](./development/backend/install.mdx). +`create-medusa-app` allows you to install and setup a Medusa backend project with minimal configurations. If you're more familiar with Medusa or you need to have more control over the configurations of the Medusa backend, such as database connection details, you can either use the [command's options](#how-to-create-a-medusa-project) to customize the setup, or use the [backend quickstart instead](./development/backend/install.mdx). ::: @@ -47,12 +47,6 @@ Before you can install and use Medusa, you need the following tools installed on ## How to Create a Medusa Project -:::note - -`create-medusa-app` uses a beta version of the Medusa backend and admin. If you want to use a stable Medusa setup, consider passing the `--stable` option to the command. However, when using this option, you'll have to [install the Medusa admin](./admin/quickstart.mdx) manually. - -::: - In your terminal, run the following command: @@ -82,19 +76,57 @@ In your terminal, run the following command:
Available Options - - `--stable`: A flag that allows you to opt-out of the beta Medusa backend project. When using this option, the Medusa admin won't be installed. - `--repo-url `: The repository URL to create the project from. By default it will be `https://github.com/medusajs/medusa-starter-default`. - `--seed`: A flag indicating whether the database should be seeded with demo data. By default, seeding is disabled. - `--no-boilerplate`: A flag that removes all files added for an enhanced onboarding experience (files under `src/admin`, `src/api`, etc...). This is helpful if you want to create a clean project, and is only recommended if you're familiar with Medusa. + - `--no-browser`: Disables opening the browser at the end of the project creation and only shows success message. + - `--skip-db`: Skips creating the database, running migrations, and seeding, and subsequently skips opening the browser. Useful if you want to set the database URL at a later point in the configurations. + - `--db-url `: Skips database creation and sets the database URL to the provided URL. Throws an error if connection to the database fails. Will still run migrations and open the admin after project creation. Useful if you already have a database created, locally or remotely. + - `--no-migrations`: Skips running migrations, creating admin user, and seeding. If used, it's expected that you pass the `--db-url` option with a URL of a database that has all necessary migrations. Otherwise, unexpected errors will occur. Helpful only if combined with `--db-url`. + - `--directory-path `: Allows specifying the parent directory path to create the directory of the new project in.
+### (Optional) Connect to a Vercel PostgreSQL Database + +If you want to use a PostgreSQL database hosted on Vercel, you must use the `--db-url` option and add to the end of your connection URL `?sslmode=require`. For example: + +```bash +npx create-medusa-app@latest --db-url "postgres://default:.postgres.vercel-storage.com:5432/verceldb?sslmode=require" +``` + +:::note + +If the database already has the necessary migrations and you don't need the command to run migrations, you can pass the `--no-migrations` option. + +::: + +### (Optional) Connect to a Supabase Database + +If you want to connect to a Supabase database, you must use the `--db-url` option with its value beign the connection URL to your Supabase database. For example: + +```bash +npx create-medusa-app@latest --db-url postgresql://postgres:@.supabase.co:5432/postgres +``` + +:::note + +If the database already has the necessary migrations and you don't need the command to run migrations, you can pass the `--no-migrations` option. + +::: + ### Step 1: Specify Project Name You’ll first be asked to enter the name of your project, which is used to create the directory holding your Medusa backend. You can use the default `my-medusa-store` or enter another project name. ### (Optional) Step 2: Specify PostgreSQL credentials +:::note + +This doesn't apply if you supplied the `--db-url` option. In that case, the command will fail if it can't connect to the supplied connection URL. + +::: + By default, this command will try to use the default PostgreSQL credentials to connect to your PostgreSQL server. If they don't work, you'll be prompted to enter your PostgreSQL database and password. If they work, you can move ahead to the next step. These credentials will be used to create a database during this setup and configure your Medusa backend to connect to that database. @@ -116,12 +148,6 @@ After the above steps, the project setup will start which includes: ### Step 5: Log into admin dashboard -:::note - -If you passed the `--stable` option, the `localhost:9000/store/products` endpoint will open in your browser instead. - -::: - Once the project is prepared, the Medusa backend will start and the admin dashboard will be opened in your default browser. You'll then be asked to enter a password for the admin email you entered earlier, as well as other account information. Once you're logged in, you can start using Medusa! Try following the setup guide to create your first product and order. @@ -191,6 +217,10 @@ Based on what you're building, you can find a development path for you in the Re title: "Error: connect ECONNREFUSED ::1:5432", content: }, + { + title: "Invalid Token Error after Using --no-browser option", + content: + }, { title: 'AwilixResolutionError: Could Not Resolve X', content: diff --git a/www/docs/content/troubleshooting/create-medusa-app-errors.mdx b/www/docs/content/troubleshooting/create-medusa-app-errors.mdx index bbabf3f99c..12adf39e84 100644 --- a/www/docs/content/troubleshooting/create-medusa-app-errors.mdx +++ b/www/docs/content/troubleshooting/create-medusa-app-errors.mdx @@ -4,6 +4,7 @@ title: 'Common Create-React-App Errors' import TypeError from './create-medusa-app-errors/_typeerror.md' import OtherErrors from './create-medusa-app-errors/_other-errors.mdx' +import InvalidTokenError from './create-medusa-app-errors/_no-browser-token-error.md' ## TypeError: cmd is not a function @@ -11,6 +12,12 @@ import OtherErrors from './create-medusa-app-errors/_other-errors.mdx' --- +## Invalid Token Error with --no-browser Option + + + +--- + ## Other Errors \ No newline at end of file diff --git a/www/docs/content/troubleshooting/create-medusa-app-errors/_no-browser-token-error.md b/www/docs/content/troubleshooting/create-medusa-app-errors/_no-browser-token-error.md new file mode 100644 index 0000000000..4421ba4b5e --- /dev/null +++ b/www/docs/content/troubleshooting/create-medusa-app-errors/_no-browser-token-error.md @@ -0,0 +1,5 @@ +If you use the `--no-browser` option with the `create-medusa-app` command, you'll find a URL outputted at the end of the command execution. This is the URL that you can use to set a password for your admin user. + +However, if you copy the URL, then try later to access that URL, you may receive an "Invalid Token" error. This is because when you copy the URL, a lot of extra space may be added into the token. So, you must clear out the spaces within the token and the `||` characters, then try again. + +Alternatively, you can create a new user with the [medusa user](../../cli/reference.mdx#user) command.