diff --git a/www/apps/resources/app/deployment/admin/general/page.mdx b/www/apps/resources/app/deployment/admin/general/page.mdx deleted file mode 100644 index c1c1a89ba418e..0000000000000 --- a/www/apps/resources/app/deployment/admin/general/page.mdx +++ /dev/null @@ -1,86 +0,0 @@ ---- -sidebar_label: "General Guide" ---- - -export const metadata = { - title: `General Deployment Guide for the Medusa Admin`, -} - -# {metadata.title} - - - -The following deployment guide doesn't support Medusa v2 yet. - - - -In this guide, you’ll learn the general steps to follow when deploying the Medusa Admin separately from the Medusa application. - - - -- Deployed Medusa application. -- [GitHub repository with the Medusa Admin's code](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository). - - - -## Configure Build Command - -In the `package.json` of the Medusa application, add or change a build script for the admin: - -```json title="package.json" -"scripts": { - // other scripts - "build:admin": "medusa-admin build --deployment", -} -``` - -When using the `--deployment` option, the Medusa application's URL is loaded from the `MEDUSA_ADMIN_BACKEND_URL` environment variable. You'll configure this environment variable in a later step. - ---- - -## Deploy to Hosting Provider - -The steps to deploy the admin are different based on the hosting provider you use. The following points cover common configurations across hosting providers: - -- If your hosting provider supports choosing a Framework Preset, choose the “Other” option as the Medusa Admin doesn’t follow known framework presets. -- Set the build command of your deployed project to use the `build:admin` command: - -```bash npm2yarn -npm run build:admin -``` - -- Set the output directory of your deployed project to `build`. -- Add the environment variable `MEDUSA_ADMIN_BACKEND_URL` and set its value to the URL of your deployed Medusa application. -- If your hosting provider supports URL rewrites, add a configuration to rewrite the `/(.*)` URL pattern to `/index.html`. For example, if you’re deploying to Vercel you add the following in `vercel.json`: - -```json -{ - "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }] -} -``` - ---- - -## Configure CORS on the Deployed Application - -To send requests from the Medusa Admin dashboard to the Medusa application, set the `ADMIN_CORS` environment variable on your Medusa application to the admin’s URL: - -```bash -ADMIN_CORS= -``` - -Where `` is the URL of your admin dashboard. - -Then, restart your Medusa application. Once the application is running again, you can use your admin dashboard. - ---- - -## Create Admin User - -To create an admin user, run the following command on your deployed Medusa application: - -```bash -npx medusa user --email admin@medusa-test.com --password supersecret -``` - -You can then log in using the specified email and password. diff --git a/www/apps/resources/app/deployment/admin/vercel/page.mdx b/www/apps/resources/app/deployment/admin/vercel/page.mdx index a77bb78e5d393..5f1c68e58234a 100644 --- a/www/apps/resources/app/deployment/admin/vercel/page.mdx +++ b/www/apps/resources/app/deployment/admin/vercel/page.mdx @@ -8,50 +8,51 @@ export const metadata = { # {metadata.title} - - -The following deployment guide doesn't support Medusa v2 yet. - - - -This guide explains how to deploy the Medusa Admin separately from the Medusa application to Vercel. +In this document, you’ll learn how to deploy the Medusa Admin to [Vercel](https://vercel.com). -Per Vercel’s [license and plans](https://vercel.com/pricing), their free plan can only be used for personal, non-commercial projects. So, you can deploy the Medusa Admin on the free plan for development purposes, but for commercial projects, you must update your Vercel plan. +As Medusa v2 is still in active development, it's highly recommended not to deploy it for production purposes. The deployment process may also change. -[Vercel](https://vercel.com/) is a cloud platform for static sites and serverless functions. It provides developers with a platform to deploy web projects quickly and easily. +--- -- Deployed Medusa application. -- [Vercel account](https://vercel.com/) -- [GitHub repository with the Medusa Admin's code](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository). +- [Medusa application](!docs!)’s codebase hosted on GitHub repository. +- [Deployed Medusa application](../../page.mdx#medusa-application). -## Configure Build Script +## 1. Configure Admin in Medusa -In the `package.json` of the Medusa application, add or change a build script for the admin: +In `medusa-config.js`, set the following admin configuration: -```json -"scripts": { - // other scripts - "build:admin": "medusa-admin build --deployment", -} +```js title="medusa-config.js" +module.exports = defineConfig({ + // ... + admin: { + disable: process.env.DISABLE_MEDUSA_ADMIN === "true", + backendUrl: process.env.MEDUSA_BACKEND_URL, + path: process.env.MEDUSA_ADMIN_PATH + }, +}) ``` -When using the `--deployment` option, the Medusa application's URL is loaded from the `MEDUSA_ADMIN_BACKEND_URL` environment variable. You'll configure this environment variable in a later step. +Where: + +- You set `disable` to the environment variable `DISABLE_MEDUSA_ADMIN`. In the deployed Medusa application, you set the environment variable’s value to `true` to disable the admin, and when deploying the admin you set it to `false`. +- `backendUrl` will be the URL of the deployed Medusa backend. +- `path` is the base path of the admin, which is `/app` by default. When you set the environment variable `MEDUSA_ADMIN_PATH` later while deploying the admin, you’ll set it to `/`. --- -## Add Vercel Configurations +## 2. Add Vercel Rewrite -In the root directory of the Medusa application, create a new file `vercel.json` with the following content: +Create the file `vercel.json` in the root directory of your Medusa application with the following content: -```json +```json title="vercel.json" { "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }] } @@ -59,87 +60,85 @@ In the root directory of the Medusa application, create a new file `vercel.json` --- -## Push Changes to GitHub - -After making all the previous changes, push them to GitHub before starting the deployment on Vercel: - -```bash -git add . -git commit -m "prepare repository for deployment" -git push -``` - ---- - -## Deploy to Vercel - -This section covers how to deploy the Medusa Admin, either using the Vercel website or using Vercel’s CLI tool. +## 3. Create Vercel Project -### Option 1: Using the Vercel Website + -This section explains how to deploy the admin using the Vercel website: +Push all changes you’ve made in the previous step to the GitHub repository before proceeding. -1. Open the [Vercel dashboard](https://vercel.com/dashboard) after logging in. -2. Click on the “Add New…” button next to the search bar. -3. Choose Project from the dropdown. -4. In the new page that opens, find the Git repository that holds your Medusa application or Medusa Admin and click on the Import button. If you haven’t connected your Vercel account to any Git provider, you must do that first. -5. In the Configure Project form: - 1. Set the Framework Preset to Other. - 2. Open the Build and Output Settings collapsible, and set the Build Command to `yarn build:admin` and the Output Directory to `build`. - 3. Open the Environment Variables collapsible, and add an environment variable with the name `MEDUSA_ADMIN_BACKEND_URL` with the value being the URL to your deployed Medusa application. - 4. You can optionally edit the Project Name. -6. Once you’re done, click on the “Deploy” button. + -This will start the deployment of the admin. Once it’s done, you’ll be redirected to the main dashboard of your new project. +To create a Vercel project, on your Vercel dashboard: + +1. Click on the Add New button at the top right. +2. Choose Project from dropdown. +3. In the list of GitHub repository shown, find the GitHub repository and click its Import button. +4. This shows a form to configure the project: + 1. Choose Other for the Framework Preset field. + 2. Keep the root directory to `.` + 3. Expand the Build and Output Settings section: + - Set the Build Command field to the following: + + ```bash npm2yarn + npm run build + ``` + + - Set the Output Directory field to `build`. + - Set the Install Command field to the following: + + ```bash npm2yarn + npm run build + ``` + + 4. Expand the Environment Variables section and add the following variables: + + ```bash + DISABLE_MEDUSA_ADMIN=false + MEDUSA_BACKEND_URL = # URL of deployed Medusa application + MEDUSA_ADMIN_PATH=/ + ``` + + +Where the value of `MEDUSA_BACKEND_URL` is the URL to your deployed Medusa application. + +Then, click the Deploy button to deploy the admin. This takes a couple of minutes. Once the deployment is done, click the Continue to Dashboard button. - +--- -At this point, when you visit the admin, you'll face errors related to Cross-Origin Resource Sharing (CORS). Before you start using the Medusa Admin, follow along the [Configure CORS on the Medusa Application](#configure-cors-on-the-medusa-application) section. +## 4. Set Admin URL - +Vercel generates a random domain name for your project. You can use it or [set a custom domain name](https://vercel.com/guides/how-do-i-add-a-custom-domain-to-my-vercel-project). -### Option 2: Using Vercel’s CLI Tool +Once you have the admin’s domain name, you must set the `ADMIN_CORS` environment variable in the Medusa application to the admin’s URL: -This section explains how to deploy the admin using the Vercel CLI tool. You should have the CLI tool installed first, as explained in [Vercel’s documentation](https://vercel.com/docs/cli). +```bash +ADMIN_CORS=https://admin-... +``` -In the directory of your Medusa application, run the following command to deploy your Medusa Admin: +And add the admin URL to the `AUTH_CORS` environment variable in the Medusa application: ```bash -vercel --build-env MEDUSA_ADMIN_BACKEND_URL= +AUTH_CORS=,https://admin-... ``` -Where `` is the URL of your deployed Medusa application. - -You’ll then be asked to log in if you haven’t already, and to choose the scope to deploy your project to. You can also decide to link the admin to an existing project, or change the project’s name. +Where `` are URLs added previously to `AUTH_CORS`, such as the URL of a storefront. URLs in `AUTH_CORS` are separated by a comma. -When asked, ”In which directory is your code located?”, keep the default `./` and just press Enter. +Then, redeploy the Medusa application. -The project setup will then start. When asked if you want to modify the settings, answer `y`. You’ll then be asked a series of questions: +--- -1. “Which settings would you like to overwrite”: select Build Command and Output Directory using the space bar, then press Enter. -2. “What's your **Build Command**?”: enter `yarn build:admin`. -3. “What's your **Output Directory**?”: enter `build`. +## Test the Admin -After that, it will take a couple of minutes for the deployment to finish. The link to the admin will be shown in the final output of the command. +To test the admin, open its URL and login with an admin user’s credentials. -At this point, when you visit the admin, you'll face errors related to Cross-Origin Resource Sharing (CORS). Before you start using the Medusa Admin, follow along the [Configure CORS on the Medusa Application](#configure-cors-on-the-medusa-application) section. +If you don’t have an admin user on your Medusa application, use the [user command of the Medusa CLI tool](../../../medusa-cli/page.mdx#user). --- -## Configure CORS on the Medusa Application - -To send requests to the Medusa application from the admin dashboard, set the `ADMIN_CORS` environment variable on your deployed Medusa application to the admin’s URL. - -On your Medusa application, add the following environment variable: - -```bash -ADMIN_CORS= -``` - -Where `` is the URL of the deployed Medusa Admin. +## Troubleshooting -Then, restart your Medusa application. Once the application is running again, you can use your admin dashboard. +If you’re running into issues in your admin, find the logs in your Vercel project’s dashboard under the Logs tab. diff --git a/www/apps/resources/app/deployment/storefront/general/page.mdx b/www/apps/resources/app/deployment/storefront/general/page.mdx deleted file mode 100644 index 40361cbcb4517..0000000000000 --- a/www/apps/resources/app/deployment/storefront/general/page.mdx +++ /dev/null @@ -1,55 +0,0 @@ ---- -sidebar_label: "General Guide" ---- - -export const metadata = { - title: `General Deployment Guide for the Next.js Starter`, -} - -# {metadata.title} - - - -The following deployment guide doesn't support Medusa v2 yet. - - - -In this guide, you’ll learn the general steps to follow when deploying the Next.js Starter. - - - -- Deployed Medusa application. -- [GitHub repository with the Next.js Starter's code](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository). - - - -## Deploy to Hosting Provider - -The steps to deploy the Next.js Starter are different based on the hosting provider you use. The following points cover common configurations across hosting providers: - -- If your hosting provider supports choosing a framework preset, set it to Next.js. You can then skip setting the build command and output directory as they are default Next.js configurations. If not: - - Set the build command of your deployed project to the `build` command: - - ```bash npm2yarn - npm run build - ``` - - - Set the output directory of your deployed project to `.next`. -- Add the following environment variables: - - `NEXT_PUBLIC_MEDUSA_BACKEND_URL`: The URL of your deployed Medusa application. - - `NEXT_PUBLIC_BASE_URL`: The URL of the storefront. If you still don’t have the URL you can wait until later to add it. However, you may face errors when using the storefront. - - `REVALIDATE_SECRET`: A secret used for revalidating data. Learn more in the [Next.js documentation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#on-demand-revalidation). - ---- - -## Configure CORS on the Deployed Medusa Application - -To send requests from the Next.js Starter storefront to the Medusa application, you must set the `STORE_CORS` environment variable on your Medusa application to the storefront’s URL: - -```bash -STORE_CORS= -``` - -Where `` is the URL of your storefront. - -Then, restart your Medusa application. Once the Medusa application is running again, you can use your storefront. diff --git a/www/apps/resources/app/deployment/storefront/vercel/page.mdx b/www/apps/resources/app/deployment/storefront/vercel/page.mdx index ba6fa5c9c4c99..46428020bea60 100644 --- a/www/apps/resources/app/deployment/storefront/vercel/page.mdx +++ b/www/apps/resources/app/deployment/storefront/vercel/page.mdx @@ -8,102 +8,140 @@ export const metadata = { # {metadata.title} - - -The following deployment guide doesn't support Medusa v2 yet. - - - -This guide explains how to deploy the Medusa Admin separately from the Medusa application to Vercel. +In this document, you’ll learn how to deploy the Next.js storefront to [Vercel](https://vercel.com). -Per Vercel’s [license and plans](https://vercel.com/pricing), their free plan can only be used for personal, non-commercial projects. So, you can deploy the Next.js Starter on the free plan for development purposes, but for commercial projects, you must update your Vercel plan. +As Medusa v2 is still in active development, it's highly recommended not to deploy it for production purposes. The deployment process may also change. -[Vercel](https://vercel.com/) is a cloud platform for static sites and serverless functions. It provides developers with a platform to deploy web projects quickly and easily. +--- -- Deployed Medusa application. -- [Vercel account](https://vercel.com/) -- [GitHub repository with the Next.js Starter's code](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository). +- [Storefront codebase](../../../nextjs-starter/page.mdx) hosted in a GitHub repository. +- [Deployed Medusa application](../../page.mdx#medusa-application) with at least one region. -## Deploy to Vercel +## 1. Create Vercel Project -This section covers how to deploy the storefront, either using the Vercel website or using Vercel’s CLI tool. +On your Vercel dashboard: -### Option 1: Using the Vercel Website +1. Click on the Add New button at the top right. +2. Choose Project from the dropdown. +3. In the list of repositories, click on the Import button of the storefront’s repository. -This section explains how to deploy the storefront using the Vercel website: +This opens a form to configure your project. -1. Open the [Vercel dashboard](https://vercel.com/dashboard) after logging in. -2. Click on the “Add New…” button next to the search bar. -3. Choose Project from the dropdown. -4. In the new page that opens, find the Git repository that holds your Next.js Starter Template and click on the Import button. If you haven’t connected your Vercel account to any Git provider, you must do that first. -5. In the Configure Project form: - 1. Open the Environment Variables collapsible, and add the following environment variables: - - `NEXT_PUBLIC_MEDUSA_BACKEND_URL`: the URL to your deployed Medusa application. - - `NEXT_PUBLIC_BASE_URL`: The URL of your storefront. If you don't have a domain ready yet, you can add it later. However, you may face some errors in your storefront. - - `REVALIDATE_SECRET`: A secret used for revalidating data. Learn more in the [Next.js documentation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#on-demand-revalidation). - 2. You can optionally edit the Project Name. -6. Once you’re done, click on the “Deploy” button. +### Configure Storefront Project -This will start the deployment of the storefront. Once it’s done, you’ll be redirected to the main dashboard of your new project. +In the Configure Project form, choose Next.js for the Framework Preset field. This sets for you the build and install scripts, and the output directory - +
-At this point, when you visit the storefront, you'll face errors related to Cross-Origin Resource Sharing (CORS). Before you start using the storefront, follow along the [Configure CORS on the storefront](#configure-cors-on-the-medusa-application) section. +- `build` script: + +```bash npm2yarn +npm run build +``` - +- `install` script: + +```bash npm2yarn +npm install +``` -### Option 2: Using Vercel’s CLI Tool +- output directory: `.next` -This section explains how to deploy the storefront using the Vercel CLI tool. You should have the CLI tool installed first, as explained in [Vercel’s documentation](https://vercel.com/docs/cli). +
-In the directory holding your storefront, run the following command to deploy your storefront: +Then, expand the Environment Variables section and add the following variables: ```bash -vercel --build-env NEXT_PUBLIC_MEDUSA_BACKEND_URL= -vercel --build-env NEXT_PUBLIC_BASE_URL= -vercel --build-env REVALIDATE_SECRET= +NEXT_PUBLIC_MEDUSA_BACKEND_URL= # URL of Medusa application +NEXT_PUBLIC_DEFAULT_REGION=us # or a different region that you prefer +NEXT_PUBLIC_PUBLISHABLE_KEY= # publishable API key of the storefront's sales channel +REVALIDATE_SECRET=supersecret # TODO generate random string ``` Where: -- ``: the URL of your deployed Medusa application. -- ``: The URL of your storefront. If you don't have a domain ready yet, you can add it later. However, you may face some errors in your storefront. -- ``: A secret used for revalidating data. Learn more in the [Next.js documentation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#on-demand-revalidation). +1. `NEXT_PUBLIC_MEDUSA_BACKEND_URL` is the URL of your deployed Medusa application +2. `NEXT_PUBLIC_DEFAULT_REGION` is the country code of a region to be used by default, if the customer hasn’t selected a region. +3. `NEXT_PUBLIC_PUBLISHABLE_KEY` is the publishable API key of the storefront. You can create one or find the default one in the Medusa Admin dashboard. +4. `REVALIDATE_SECRET` is a random string for [Next.js revalidation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#on-demand-revalidation). -You’ll then be asked to log in if you haven’t already, and to choose the scope to deploy your project to. You can also decide to link the storefront to an existing project, or change the project’s name. +Make sure to add other relevant environment variables. For example, if you’re using the Stripe Payment Module Provider in the Medusa application, add the `NEXT_PUBLIC_STRIPE_KEY` environment variable. -When asked `In which directory is your code located?`, keep the default `./` and just press Enter. +### Deploy Application -The project setup will then start. When asked if you want to modify the settings, answer `N` to keep the default settings. +Click the Deploy button when you’re done. The deployment will take a few minutes. -It'll take a couple of minutes for the deployment to finish. The link to the storefront will be shown in the final output of the command. +Once the deployment is done, there’s still more work to do before you can use the storefront. Click on the Continue to Dashboard button to go to the project’s dashboard. - +--- + +## 2. Set Storefront URL + +Vercel generates a random domain name for your project. You can use it or [set a custom domain name](https://vercel.com/guides/how-do-i-add-a-custom-domain-to-my-vercel-project). -At this point, when you visit the storefront, you'll face errors related to Cross-Origin Resource Sharing (CORS). Before you start using the storefront, follow along the [Configure CORS on the storefront](#configure-cors-on-the-medusa-application) section. + + +Find your generated domain name at Settings → Domains in your project’s dashboard. ---- +Once you have your domain name: + +1. Go to Settings → Environment Variables +2. Add a new environment variable: + +```bash +NEXT_PUBLIC_BASE_URL=https://nextjs-storefront... +``` -## Configure CORS on the Medusa application +Set the value to the storefront’s URL. -To send requests to the Medusa application from the Next.js Starter, set the `STORE_CORS` environment variable on your Medusa application to the deployed storefront's URL. +### Set STORE_CORS and AUTH_CORS in Deployed Medusa Application -On your Medusa application, add the following environment variable: +You must also set the `STORE_CORS` environment variable in your Medusa application to the storefront’s URL: ```bash -STORE_CORS= +STORE_CORS=https://nextjs-storefront... ``` -Where `` is the URL of your storefront. + + +If you have multiple storefront URLs, separate them by commas in `STORE_CORS` + + + +And add the URL to `AUTH_CORS`'s value: + +```bash +AUTH_CORS=,https://nextjs-storefront... +``` + +Where `` are other storefront or admin URLs added previously to `AUTH_CORS`. + +### Redeploy Storefront + +Once the environment variables changes are deployed in the Medusa application, do the following to redeploy the storefront: + +1. Go to Deployments in the storefront Vercel project. +2. Find the last production deployment, and click on the three dots icon at the right. +3. Choose Redeploy from the dropdown, and confirm redeployment in the new window. + +--- + +## Test the Deployed Storefront + +Once the redeployment is done, test out the storefront by going to its URL. Try to browse the products or place an order to ensure everything is working as expected. + +--- + +## Troubleshooting -Then, restart your Medusa application. Once the application is running again, you can use your storefront. +If you’re running into issues in your storefront, find the logs in your Vercel project’s dashboard under the Logs tab. diff --git a/www/apps/resources/generated/files-map.mjs b/www/apps/resources/generated/files-map.mjs index ca7be71609318..e583e9f23e290 100644 --- a/www/apps/resources/generated/files-map.mjs +++ b/www/apps/resources/generated/files-map.mjs @@ -651,10 +651,6 @@ export const filesMap = [ "filePath": "/www/apps/resources/app/create-medusa-app/page.mdx", "pathname": "/create-medusa-app" }, - { - "filePath": "/www/apps/resources/app/deployment/admin/general/page.mdx", - "pathname": "/deployment/admin/general" - }, { "filePath": "/www/apps/resources/app/deployment/admin/vercel/page.mdx", "pathname": "/deployment/admin/vercel" @@ -667,10 +663,6 @@ export const filesMap = [ "filePath": "/www/apps/resources/app/deployment/page.mdx", "pathname": "/deployment" }, - { - "filePath": "/www/apps/resources/app/deployment/storefront/general/page.mdx", - "pathname": "/deployment/storefront/general" - }, { "filePath": "/www/apps/resources/app/deployment/storefront/vercel/page.mdx", "pathname": "/deployment/storefront/vercel" diff --git a/www/apps/resources/generated/sidebar.mjs b/www/apps/resources/generated/sidebar.mjs index e5174e6bc3d7b..5fb00b759451b 100644 --- a/www/apps/resources/generated/sidebar.mjs +++ b/www/apps/resources/generated/sidebar.mjs @@ -7008,13 +7008,6 @@ export const generatedSidebar = [ "hasTitleStyling": true, "autogenerate_path": "/deployment/admin", "children": [ - { - "loaded": true, - "isPathHref": true, - "path": "/deployment/admin/general", - "title": "General Guide", - "children": [] - }, { "loaded": true, "isPathHref": true, @@ -7031,13 +7024,6 @@ export const generatedSidebar = [ "hasTitleStyling": true, "autogenerate_path": "/deployment/storefront", "children": [ - { - "loaded": true, - "isPathHref": true, - "path": "/deployment/storefront/general", - "title": "General Guide", - "children": [] - }, { "loaded": true, "isPathHref": true,