import { Note, Prerequisites, InlineIcon, getOsShortcut, Kbd } from "docs-ui" import { ChevronUpDown } from "@medusajs/icons"

export const metadata = { title: Create Projects and Deploy to Cloud, }

{metadata.title}

In this guide, you'll learn about projects, how to create them, view their details, and manage their settings in Cloud.

What is a Project?

A project is the collection of resources, environments, deployments, and settings related to a Medusa application deployed to the Cloud. The project is linked to a GitHub repository that hosts the Medusa application's code.

To deploy a Medusa application to the Cloud, you create a project for it. Medusa will automatically set up and configure the necessary resources in the project to run the application, such as PostgreSQL, Redis, and S3.

You can deploy either a Medusa application (server and admin dashboard) only, or a Medusa application along with a storefront.

Each project can have multiple environments, such as production and staging. These environments allow you to test changes before pushing them live to users. You can learn more in the Environments documentation.

---

Create a Project

<Note>

If you've reached the limit of projects allowed in your organization's plan, you need to upgrade your plan to create more projects. Learn more in the Plans & Pricing guide.

</Note>

In this section, you'll learn how to create a project in Cloud to deploy your Medusa application.

To create a project:

<Note title="Tip">

You can also start the project creation flow from the command palette. Press <Kbd>{getOsShortcut()}</Kbd> + <Kbd>K</Kbd>, then select Create Project.

</Note>

1. Make sure you're viewing the correct organization's dashboard in Cloud.
2. Click on the Create Project button in your organization's dashboard.

In the project-creation page, you can either create from a starter or create from an existing application.

---

1. Create Project from a Starter

Medusa provides you with starter templates that you can use to quickly set up your ecommerce application. All templates include a storefront, backend, and admin dashboard. These templates include:

• DTC Starter: Standard Medusa application with fully-fledged commerce features.
• B2B Starter: Medusa application with powerful B2B and commerce features.
• Configurable product starter: Medusa application with the configurable product feature. For example, customers can configure their product's attributes, and the price changes accordingly.
• Grounded starter: Medusa application with a storefront having a modern design, ideal for designers, artists, and brands with a focus on aesthetics.
• Industrials B2B starter: B2B Medusa application with features and a storefront tailored for industrial businesses, such as machinery, equipment, and supplies.
• Quiz-to-product starter: Medusa application with a storefront that includes a quiz to help customers find the right product based on their preferences and needs.
• Essentials starter: Medusa application with storefront suitable for fashion brands.
• Uncut Coffee starter: Medusa application with a storefront that has bold visuals and immersive storytelling. Ideal for modern DTC brands.

Browse and Select Templates

To create a project from a starter template:

1. Click on the Browse Starters button at the top right of the project creation page.

• For each template, you can click on it to view more details, such as its features and the tech stack used in the storefront.

2. Click the Clone button of the starter you want to use.
3. If GitHub is not connected, you'll be directed to the new project form to set up the repository connection.
4. If GitHub is already connected:
   • Choose a GitHub organization or account to clone the starter into in the "GitHub account" field.
   • In the "Repository name" field, enter a name for your new repository.
   • Once you're done, click the Clone button.

The repository will be cloned, and you'll move forward to the Configure step.

---

2. Create Project from an Existing Application

If you already have a Medusa application, you can create a project from it.

Refer to the Prerequisites for Creating Projects guide to ensure your Medusa application meets the necessary prerequisites before deploying it to Cloud. This is especially necessary if you're deploying a storefront along with your Medusa application.

To create a project from an existing Medusa application:

1. In the GitHub section of the project-creation page, authenticate with your GitHub account if you haven't already.
2. Under the Repository section, choose the repository to create the project from.
   • If you don't see your repository, you can click the Configure repositories link to manage the GitHub repositories that Medusa can access.
3. Once you're done, click the Continue button.

You'll move forward to the Configure step.

---

Configure Project During Creation

After selecting the repository, you'll move on to the project configuration step. You can set the following information:

1. Project name: Enter the name of the project.
2. Custom subdomain: Enter a custom subdomain for the Medusa application. All projects are subdomains of medusajs.app.
   • For example, if you enter my-project, the project will be accessible at my-project.medusajs.app. Refer to the subdomain restrictions section for more details.
   • If you're hosting a storefront, it will be accessible at my-project.medusajs.site.
   • Region: Select a region to deploy the project. For better performance, choose a region that's closer to your target users. The region can't be changed later.
3. In the Build details section, set the following:
   • Project root directory: If your project is in a monorepo, specify the path to the Medusa project in the repository. Otherwise, leave it empty.
   • Storefront root directory: If you're deploying a storefront along with your Medusa application, specify the path to the storefront project in the repository. Otherwise, leave it empty.
4. You can expand the "Initial user" section to optionally set up the credentials of the initial admin user for the Medusa Admin:
   • Email: The email of the initial admin user.
   • Password: The password of the initial admin user.
5. You can expand the "Environment variables" section to optionally add environment variables for both backend and storefront:
   • Enter the key and value for each environment variable you want to add.
   • Mark the variable as "Sensitive" to hide its value in the UI.
   • To add more variables, click the "Add another" button.
   • You can also add and change environment variables later in the project's environment settings.
6. Once you're done configuring the project, click the "Create" button.

After creating the project, it will take a few minutes to create the necessary resources for it and deploy it. Once the deployment is complete, you'll be able to access the project from your organization's dashboard.

<Note>

If the project creation takes too long, check out the troubleshooting section.

</Note>

If you click on the project, you'll be taken to the project's dashboard, where you can view its details and status.

Once the project is created and deployed, you'll receive a notification in the Cloud dashboard. You can also view its status in the list of projects and in the project's details.

---

Troubleshooting Project Creation

If you encounter any issues while creating a project, check common deployment issues and their solutions

<Note>

If the issue isn't related to your application, check the Cloud status page for ongoing Cloud incidents that may be affecting project creation.

</Note>

---

Subdomain Restrictions for Projects

Your backend's URL must be a subdomain of medusajs.app. For example, if you choose my-store as your subdomain, your project's URL will be my-store.medusajs.app.

When you choose a subdomain for your project, it must be at least five characters long. It also can't be one of the following reserved subdomains:

• medusa
• admin
• staging
• production
• preview
• development
• proxy

If you also deployed a storefront with your Medusa application, its URL will be a subdomain of medusajs.site. For example, if your backend's subdomain is my-store, your storefront's URL will be my-store.medusajs.site. You can also add a custom domain, as explained in the Custom Domains guide.

---

Available Regions for Projects in Cloud

Medusa supports hosting your Medusa projects on Cloud in the following regions:

• US East (us-east-1)
• Europe Central (eu-central-1)
• Asia Southeast (ap-southeast-1)

All your project's deployments will be in the selected region. For better performance, choose a region that's closer to your target users. If you need to host your Medusa project in a different region, contact support.

---

Access Deployed Project

To access the deployed project, you can navigate to:

• The Backend URL of the environment. Clicking this URL will open the Medusa Admin in a new tab.
• The Storefront URL of the environment (if you deployed a storefront along with your Medusa application). Clicking this URL will open the storefront in a new tab.

Learn more in the Access Deployment guide.

---

Clone Project Locally

If you created your project from a starter, Cloud clones the starter's code into a GitHub repository in the account or organization you chose. To customize your store, you clone that repository to your machine and run the application locally.

Learn how to do that in the Clone a Cloud Project Locally guide.

---

Open Project Dashboard

To open a project's dashboard:

1. If you're in a different organization, switch to the organization.
2. Click Projects in the sidebar and select the project. This will open the project's dashboard.

When you open a project's dashboard, its name will be shown at the top left next to the organization switcher.

Find Project Details

On the project's dashboard, you can view the following details:

1. Region: The region where the project is deployed. You'll find it below the project name.
2. Long-Lived Environments: The long-lived environments for the project are shown as cards. By default, you'll find the Production environment. You can learn more about environments in the Environments guide.
   • The Production environment is the live environment where your Medusa application is deployed and clients connect to.
   • Other Long-lived environments like Staging will be shown here if you create them. These are useful for testing changes before deploying them to Production.
   • Each environment card shows the environment's name, URLs, and status.
3. Preview Environments: The Preview environments for the project are shown in a table below the long-lived environments.
   • Previews environments are created whenever you create a pull request in the linked GitHub repository. They allow you to preview changes before merging them into the main branch.
   • Learn more in the Preview Environments guide.
4. Production URL: The URL of the project's production deployment. You'll find the backend and storefront URLs (if deployed) under their respective titles in the Production environment card.
   • If no backend custom domain is configured for the production environment, you'll see a Setup Custom Domain link that allows you to configure a custom domain directly from the environment card.
5. Repository: The GitHub repository linked to the project. You'll find it as a "Repository" button at the top right of the project's dashboard. Clicking it will open the repository in a new tab.
6. Production Deployment Status: The deployment status of the project for the backend and storefront. If it's "Live", then the deployment was successful. Learn more in the Deployments guide.

Switch Projects

The project's name at the top left of the dashboard is also a project switcher.

To switch to a different project:

1. Click on the <InlineIcon Icon={ChevronUpDown} alt="switch project" /> icon next to the project's name at the top left of the Cloud dashboard, next to the organization name.
2. Choose the project you want to switch to from the dropdown.

This will change the view to the selected project, and you'll see its details, environments, and settings.

---

View Project Deployments

To view the deployments of a project, click Deployments in the sidebar of the project's dashboard. This will show you a list of all deployments for the project, including their status, environment, and how long the deployment took.

Learn more in the Deployments guide.

---

Add Storefront to Existing Project

If you initially created a project with only a Medusa application and later want to add a storefront to it, you can do it from the organization or project's dashboard.

Before adding a storefront, make sure you've changed your repository structure to a monorepo that includes both the Medusa application and storefront code. Learn how to create the monorepo in the Prerequisites for Creating Projects guide.

Then, to add a storefront to an existing project:

1. Open the project's dashboard.
2. Click on the "Add storefront" button at the Production environment card.
3. In the "Add Storefront" form, enter the following details:
   • Storefront root directory: The path to the storefront project in the repository.
   • Environment variables: (Optional) Expand this section to add any necessary environment variables.
4. Once you're done, click the "Create" button.

Cloud will then deploy the storefront along with the Medusa application. Once the deployment is complete, you'll be able to access the storefront from the Production environment card in the project's dashboard.

You can also set a custom domain for the storefront, as explained in the Custom Domains guide.

---

Edit Project Details

After creating a project, you can edit its general details, such as the project name and root directory in the repository, and manage its preview settings.

To edit a project's general details:

1. Open the project's dashboard.
2. Click Settings > General in the sidebar.
3. You can edit the project's name and root directories of the backend and storefront in the repository.
   • Changing the root directory is useful if the structure of your repository has changed.
4. Once you're done making changes, click the "Save changes" button next to the input field.

Editing Previews Settings

You can also edit a project's preview settings, which are general settings related to Previews environments, by clicking Settings > Preview Settings in the sidebar.

Learn more in the Preview Environments guide.

---

Change Connected GitHub Repository

You can change the GitHub repository connected to your project from the project's general settings page. This is useful if you've moved your Medusa application to a different repository.

To change the connected repository:

1. Open the project's dashboard.
2. Click Settings > General in the sidebar.
3. In the "Repository" section, click the Change button.
4. In the modal that opens, choose the new repository to connect.
   • If you're not connected to GitHub yet, you'll need to connect first.
5. Click Save Changes.

The next time you push to the new repository, your project will be built from there.

---

Change Project Infrastructure Specifications

By default, all your projects use the infrastructure specifications defined in your organization's plan.

In some scenarios, you may have projects that don't require heavy infrastructure specifications, such as a project used for testing or development purposes. In such cases, you can change the infrastructure specifications of a project to use lighter specifications. This can help reduce costs and optimize resource usage.

You can also change the infrastructure specifications of a project to use heavier specifications if your project requires more resources, such as a project with high traffic or complex operations.

To change the infrastructure specifications of a project:

1. Open the project's dashboard.
2. Click Settings > General in the sidebar.
3. Enable the "Infrastructure specs" toggle.
4. In the dropdown that shows, select the plan that you want to use its specs for the project. Below the dropdown, the cost estimates will change based on the plan you select.
   • You can learn more about the available plans and their specifications in the Plans & Pricing guide.
   • If your organization is on a bespoke plan and you haven't selected a custom infrastructure override, you'll see a bespoke-specific note instead of a standard cost estimate. Once you select a custom override, the standard cost estimate is shown.
5. Once you're done making changes, click the "Save changes" button next to the input field.

The infrastructure specifications of the project will be updated based on the selected plan.

Revert to Organization's Plan Specs

If you want to revert the infrastructure specifications of a project to use the specifications defined in your organization's plan, you can do so by disabling the "Infrastructure specs" toggle in the Settings > General page.

The project will then use the specifications defined in your organization's plan.

---

Delete Storefront

<Note type="warning" title="Danger">

Deleting the storefront is irreversible. This action permanently removes the storefront associated with the project. You can re-add the storefront if needed.

</Note>

If your project has a storefront deployed, you can permanently delete it from the project settings.

To delete the storefront:

1. Open the project's dashboard.
2. Click Settings > General in the sidebar.
3. Click the Delete button in the Delete Storefront section.
4. Confirm the deletion by entering the verification phrase in the confirmation prompt, then click Delete.

This will remove your storefront from the project. Future deployments include the backend only.

---

Delete Project

<Note type="warning" title="Danger"> Deleting a project will delete all its environments and deployments. This action is irreversible. You won't be able to recover any data after deletion. </Note>

To delete a project:

1. Open the project's dashboard.
2. Click Settings > General in the sidebar.
3. Click the "Delete" button in the "Delete project" section at the bottom.
4. Confirm the deletion by typing "delete project" in the confirmation input, then click the "Delete" button.