From 03be1cfb0aa238ae82e90cfc9da3ecb67f618b97 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Thu, 28 Nov 2024 15:29:07 +0200 Subject: [PATCH] docs(v1): remove installation instructions --- www/apps/docs/content/create-medusa-app.mdx | 256 +----------------- .../content/development/backend/install.mdx | 165 +---------- 2 files changed, 5 insertions(+), 416 deletions(-) diff --git a/www/apps/docs/content/create-medusa-app.mdx b/www/apps/docs/content/create-medusa-app.mdx index 2631a49e3a648..4879a55f7ccb0 100644 --- a/www/apps/docs/content/create-medusa-app.mdx +++ b/www/apps/docs/content/create-medusa-app.mdx @@ -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: - - - - - ```bash - npx create-medusa-app@latest - ``` - - - {/* - - ```bash - yarn create medusa-app - ``` - - */} - - - ```bash - pnpm dlx create-medusa-app@latest - ``` - - - - -
- Command Options - - The `create-medusa-app` command can accept the following options: - - - `--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. - - `--with-nextjs-starter`: Installs the Next.js starter storefront under the `-storefront` directory, where `` is the name of the project you enter in the first question. If the `-storefront` directory already exists, random characters are added at the end of `-storefront`. -
- -
- Example: 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. - - ::: -
- -
- Example: Connect to a Supabase Database - - 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.:@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. - - ::: -
- -## 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 `-storefront` directory, where `` is the name of the project you specified in step 2. - -If you want to install the storefront, type `y` and press enter. If not, you can use the default value `N` and just press enter. - -:::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. - - - ---- - -## Next Steps: Start your Development - -Based on what you're building, you can find a development path for you in the Recipes page. - - - ---- - -## Troubleshooting - - - }, - { - title: 'Can\'t connect to database with --db-url option', - content: - }, - { - title: 'Error: EADDRINUSE', - content: - }, - { - title: "Can't Connect to PostgreSQL Docker Container", - content: - }, - { - title: "EAGAIN error", - content: - }, - { - title: "TypeError: cmd is not a function", - content: - }, - { - title: "Error: connect ECONNREFUSED ::1:5432", - content: - }, - { - title: "Invalid Token Error after Using --no-browser option", - content: - }, - { - title: 'AwilixResolutionError: Could Not Resolve X', - content: - }, - { - title: "Other Errors", - content: - }, - ]} -/> diff --git a/www/apps/docs/content/development/backend/install.mdx b/www/apps/docs/content/development/backend/install.mdx index e83f74ba06902..e33845ffc3e47 100644 --- a/www/apps/docs/content/development/backend/install.mdx +++ b/www/apps/docs/content/development/backend/install.mdx @@ -1,170 +1,11 @@ --- description: 'This quickstart guide will help you set up a Medusa backend in three steps.' -addHowToData: true --- -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 SaslSection from '../../troubleshooting/database-errors/_sasl.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 DockerSection from '../../troubleshooting/database-errors/_docker.md' - # Install Medusa Backend -This document will guide you through setting up your Medusa backend in a three steps. - -## Prerequisites - -Before you can install and use Medusa, you need the following tools installed on your machine: - -- [Node.js v16+](./prepare-environment.mdx#nodejs) -- [Git](./prepare-environment.mdx#git) -- [PostgreSQL](./prepare-environment.mdx#postgresql) - ---- - -## Create a Medusa Backend - -:::tip - -It is recommended to use [Yarn](https://yarnpkg.com/getting-started/install) for the installation process as it's much faster than using NPM. - -::: - -### 1. Install Medusa CLI - - To install the Medusa backend, you need Medusa's CLI tool. You can install it globally or, alternatively, use it through npx with `npx @medusajs/medusa-cli `. - - ```bash npm2yarn - npm install @medusajs/medusa-cli -g - ``` - -:::note - -If you run into any errors while installing the CLI tool, check out the [troubleshooting guide](../../troubleshooting/cli-installation-errors.mdx). - -::: - -### 2. Create a new Medusa project - - ```bash noReport - medusa new my-medusa-store # or npx @medusajs/medusa-cli new - ``` - - You'll then be asked to specify your PostgreSQL database credentials. You can choose "Continue" to use the default credentials shown in the terminal, choose "Change credentials" to specify your PostgreSQL credentials, or choose "Skip database setup" to create the database later. - -:::warning - -If you choose "Skip database setup" you will need to [set the database configurations](../../references/medusa_config/interfaces/medusa_config.ConfigModule.mdx) and [run migrations](../entities/migrations/overview.mdx#migrate-command) later. - -::: - -### 3. Start your Medusa backend - -:::note - -Make sure your PostgreSQL server is running before you run the Medusa backend. - -::: - - ```bash noReport - cd my-medusa-store - medusa develop # or npx medusa develop - ``` - -After these three steps and in only a couple of minutes, you now have a complete commerce engine running locally. You can test it out by sending a request using a tool like Postman or through the command line: - -```bash noReport -curl localhost:9000/store/products -``` - - - ---- - -## Troubleshooting Installation - - - }, - { - title: "Can't Connect to PostgreSQL Docker Container", - content: - }, - { - title: 'Error: connect ECONNREFUSED ::1:5432', - content: - }, - { - title: 'Error: EADDRINUSE', - content: - }, - { - title: 'AwilixResolutionError: Could Not Resolve X', - content: - }, - ]} -/> - ---- - -## Seed Data - -For better testing, you can add demo data to your Medusa backend by running the seed command in your Medusa backend directory: - -```bash -medusa seed --seed-file=data/seed.json -# or npx medusa seed --seed-file=data/seed.json -``` - ---- - -## Health Route - -You can access `/health` to get health status of your backend. - ---- +:::danger -## Next Steps +New installations of Medusa v1 are no longer supported. Refer to the [v2 documentation](https://docs.medusajs.com/learn/installation) to install Medusa. - +::: \ No newline at end of file