-
-
Notifications
You must be signed in to change notification settings - Fork 2.9k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs(v1): remove installation instructions
- Loading branch information
1 parent
dbc7dc6
commit 03be1cf
Showing
2 changed files
with
5 additions
and
416 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,263 +1,11 @@ | ||
| --- | ||
| description: 'Learn how to create a composable commerce platform using Medusa. This quickstart guide will help you set up your Medusa backend and the admin dashboard.' | ||
| addHowToData: true | ||
| --- | ||
|
|
||
| import Tabs from '@theme/Tabs'; | ||
| import TabItem from '@theme/TabItem'; | ||
| import Feedback from '@site/src/components/Feedback'; | ||
| import DocCardList from '@theme/DocCardList'; | ||
| import Icons from '@theme/Icon'; | ||
| import DetailsList from '@site/src/components/DetailsList' | ||
| import TypeErrorSection from "./troubleshooting/create-medusa-app-errors/_typeerror.md" | ||
| import OtherErrorsSection from "./troubleshooting/create-medusa-app-errors/_other-errors.mdx" | ||
| import EagainError from "./troubleshooting/create-medusa-app-errors/_eagain-error.md" | ||
| 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' | ||
| import PostgresDockerError from './troubleshooting/database-errors/_docker.md' | ||
| import DbUrlError from './troubleshooting/create-medusa-app-errors/_db-url-error.md' | ||
| import ForwardingError from './troubleshooting/create-medusa-app-errors/_forwarding.md' | ||
|
|
||
| # Install Medusa with create-medusa-app | ||
|
|
||
| Medusa is a toolkit for developers to create digital commerce applications. In its simplest form, Medusa is a Node.js backend with the core API, plugins, and modules installed through npm. | ||
|
|
||
| `create-medusa-app` is a command that facilitates creating a Medusa ecosystem. It installs the Medusa backend and admin dashboard, along with the necessary configurations to run the backend. | ||
|
|
||
| --- | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| Before you can install and use Medusa, you need the following tools installed on your machine: | ||
|
|
||
| - [Node.js v16+](./development/backend/prepare-environment.mdx#nodejs) | ||
| - [Git](./development/backend/prepare-environment.mdx#git) | ||
| - [PostgreSQL](./development/backend/prepare-environment.mdx#postgresql). The PostgreSQL server should also be running during your installation process. | ||
|
|
||
| --- | ||
|
|
||
| ## Step 1: Run create-medusa-app | ||
|
|
||
| In your terminal, run the following command: | ||
|
|
||
| <Tabs groupId="npxyarn" isCodeTabs={true}> | ||
| <TabItem value="npx" label="NPX" default> | ||
|
|
||
| ```bash | ||
| npx create-medusa-app@latest | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| {/* <TabItem value="yarn" label="Yarn"> | ||
| ```bash | ||
| yarn create medusa-app | ||
| ``` | ||
| </TabItem> */} | ||
| <TabItem value="pnpm" label="pnpm"> | ||
|
|
||
| ```bash | ||
| pnpm dlx create-medusa-app@latest | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| <Details> | ||
| <Summary>Command Options</Summary> | ||
|
|
||
| The `create-medusa-app` command can accept the following options: | ||
|
|
||
| - `--repo-url <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 <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 <path>`: Allows specifying the parent directory path to create the directory of the new project in. | ||
| - `--with-nextjs-starter`: Installs the Next.js starter storefront under the `<PROJECT_NAME>-storefront` directory, where `<PROJECT_NAME>` is the name of the project you enter in the first question. If the `<PROJECT_NAME>-storefront` directory already exists, random characters are added at the end of `<PROJECT_NAME>-storefront`. | ||
| </Details> | ||
|
|
||
| <Details className="border-t-0"> | ||
| <Summary>Example: Connect to a Vercel PostgreSQL Database</Summary> | ||
|
|
||
| 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:<password><host-region>.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. | ||
|
|
||
| ::: | ||
| </Details> | ||
|
|
||
| <Details className="border-t-0"> | ||
| <Summary>Example: Connect to a Supabase Database</Summary> | ||
|
|
||
| If you want to connect to a Supabase database, you must use the `--db-url` option with its value being the connection URL to your Supabase database. For example: | ||
|
|
||
| ```bash | ||
| npx create-medusa-app@latest --db-url "postgres://postgres.<host>:<password>@aws-0-eu-central-1.pooler.supabase.com: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. | ||
|
|
||
| ::: | ||
| </Details> | ||
|
|
||
| ## Step 2: 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. | ||
|
|
||
| --- | ||
|
|
||
| ## Step 3: Enter an admin email | ||
|
|
||
| You'll then be prompted to enter an admin email for your admin user. You'll be using this admin email later to login to your admin dashboard. You can use the default `admin@medusa-test.com` or enter any other email. | ||
|
|
||
| --- | ||
|
|
||
| ## (Optional) Step 4: Install Next.js Starter Storefront | ||
|
|
||
| If you didn't pass the `--with-nextjs-starter` option, you'll be asked if you want to install the [Next.js starter storefront](./starters/nextjs-medusa-starter.mdx) along with the Medusa backend. This will install the storefront under the `<PROJECT_NAME>-storefront` directory, where `<PROJECT_NAME>` is the name of the project you specified in step 2. | ||
|
|
||
| If you want to install the storefront, type `y` and press <kbd>enter</kbd>. If not, you can use the default value `N` and just press <kbd>enter</kbd>. | ||
|
|
||
| :::note | ||
| :::danger | ||
|
|
||
| You can always install the storefront at a later point. Medusa is a headless backend, so it operates without a storefront by default. You can connect any storefront to it. The Next.js Starter storefront is a good option to use, but you can also build your own storefront later on. | ||
| New installations of Medusa v1 are no longer supported. Refer to the [v2 documentation](https://docs.medusajs.com/learn/installation) to install Medusa. | ||
|
|
||
| ::: | ||
|
|
||
| --- | ||
|
|
||
| ## (Optional) Step 5: 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. | ||
|
|
||
| After following the above steps, the project setup will start which includes: | ||
|
|
||
| 1. Creating the project directory. The directory name will be the project name you entered in step 1. | ||
| 2. Creating the project database if `--db-url` and `--skip-db` options are not passed. | ||
| 3. Installing dependencies in your project directory. | ||
| 4. Building project | ||
| 5. Running migrations to migrate the Medusa schema into your project database unless `--skip-db` or `--no-migrations` are passed. | ||
| 6. Creating the admin user unless `--skip-db` or `--no-migrations` are passed. | ||
| 7. Seeding the database with demo data unless `--skip-db` or `--no-migrations` are passed. | ||
|
|
||
| --- | ||
|
|
||
| ## Step 6: Log into admin dashboard | ||
|
|
||
| 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. | ||
|
|
||
| <Feedback | ||
| event="survey_create-medusa-app" | ||
| question="Did you set up Medusa successfully?" | ||
| positiveQuestion="Is there anything that should improved?" | ||
| negativeQuestion="Please describe the issue you faced." | ||
| /> | ||
|
|
||
| --- | ||
|
|
||
| ## Next Steps: Start your Development | ||
|
|
||
| Based on what you're building, you can find a development path for you in the Recipes page. | ||
|
|
||
| <DocCardList colSize={4} items={[ | ||
| { | ||
| type: 'link', | ||
| href: '/recipes', | ||
| label: 'Recipes', | ||
| customProps: { | ||
| icon: Icons['map'], | ||
| description: "Find learning paths based on what you're building" | ||
| } | ||
| }, | ||
| { | ||
| type: 'link', | ||
| href: '/development/overview', | ||
| label: 'Medusa Backend Basics', | ||
| customProps: { | ||
| icon: Icons['server-stack-solid'], | ||
| description: 'Learn all the basics of developing with the Medusa backend.' | ||
| } | ||
| }, | ||
| { | ||
| type: 'link', | ||
| href: '/modules/overview', | ||
| label: 'Commerce Modules', | ||
| customProps: { | ||
| icon: Icons['puzzle-solid'], | ||
| description: 'Learn about the available commerce modules and features in the Medusa backend.' | ||
| } | ||
| }, | ||
| ]} /> | ||
|
|
||
| --- | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| <DetailsList | ||
| sections={[ | ||
| { | ||
| title: "Errors when using VSCode or GitHub Codespaces", | ||
| content: <ForwardingError /> | ||
| }, | ||
| { | ||
| title: 'Can\'t connect to database with --db-url option', | ||
| content: <DbUrlError /> | ||
| }, | ||
| { | ||
| title: 'Error: EADDRINUSE', | ||
| content: <EaddrinuseSection /> | ||
| }, | ||
| { | ||
| title: "Can't Connect to PostgreSQL Docker Container", | ||
| content: <PostgresDockerError /> | ||
| }, | ||
| { | ||
| title: "EAGAIN error", | ||
| content: <EagainError /> | ||
| }, | ||
| { | ||
| title: "TypeError: cmd is not a function", | ||
| content: <TypeErrorSection /> | ||
| }, | ||
| { | ||
| title: "Error: connect ECONNREFUSED ::1:5432", | ||
| content: <ConnectionErrorSection /> | ||
| }, | ||
| { | ||
| title: "Invalid Token Error after Using --no-browser option", | ||
| content: <InvalidTokenError /> | ||
| }, | ||
| { | ||
| title: 'AwilixResolutionError: Could Not Resolve X', | ||
| content: <FreshInstallationSection /> | ||
| }, | ||
| { | ||
| title: "Other Errors", | ||
| content: <OtherErrorsSection /> | ||
| }, | ||
| ]} | ||
| /> |
Oops, something went wrong.