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

export const metadata = {
  title: `Projects`,
}

# {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.

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](../environments/page.mdx).

---

## Create a Project

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

<Note title="Prerequisites">

Make sure your organization's plan supports creating more projects. If you've exceeded the number of projects limit for your plan, contact support to upgrade your plan.

</Note>

To create a project:

1. Make sure you're viewing the [correct organization's dashboard in Cloud](../organizations/page.mdx#switch-organization).
2. Click on the **Create Project** button in your organization's dashboard.

In the project-creation page, you can either [create from a starter](#1-create-project-from-a-starter) or [create from an existing application](#2-create-project-from-an-existing-application).

---

## 1. Create Project from a Starter

Medusa provides you with the following starters that you can use to quickly set up your ecommerce application:

- **DTC Starter**: Standard Medusa application with fully-fledged commerce features.
- **B2B Starter**: Medusa application with powerful B2B and commerce features.

To create a project from either of these starters:

1. Click on the **Browse Starters** button at the top right of the [project creation page](#create-a-project).
2. Click the **Clone** button of the starter you want to use.
3. In the Repository step, authenticate with your GitHub account if you haven't already.
4. Choose a GitHub organization to clone the starter into in the "Organization" field.
    - If you don't see your organization, you can click the **Configure accessible organizations** link to manage accessible organizations in GitHub.
5. In the "Repository name" field, enter a name for your new repository.
6. Once you're done, click the **Continue** button.

The repository will be cloned and you'll move forward to the [Configure step](#configure-project-during-creation).

---

## 2. Create Project from an Existing Application

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

### Prerequisite: Medusa Application Configurations

Your existing Medusa application doesn't need specific configurations to be deployed to Cloud. Medusa will automatically:

- Create the necessary [server and worker instances](!docs!/learn/production/worker-mode).
- Scale your Medusa application's resources based on the traffic it receives.
- Set up and configure production resources and modules for your Medusa application:
    - [Redis Cache Module](!resources!/infrastructure-modules/cache/redis)
    - [Redis Event Module](!resources!/infrastructure-modules/event/redis)
    - [Redis Locking Module Provider](!resources!/infrastructure-modules/locking/redis)
    - [Redis Workflow Engine Module](!resources!/infrastructure-modules/workflow-engine/redis)
    - [S3 File Provider Module](!resources!/infrastructure-modules/file/s3)

So, make sure to remove any of these modules from your `medusa-config.ts` file, unless you want to use custom options for them. In that case, you're expected to manually set up and manage those resources externally and configure them in your Medusa application.

### Project Creation Steps

To create a project from an existing Medusa application:

1. In the GitHub section of the [project-creation page](#create-a-project), 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).

---

## 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. **Project subdomain**: Enter a custom subdomain for the project. 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](#subdomain-restrictions-for-projects) section for more details.
3. You can expand the "Build details" section to optionally change its configurations:
    - **Region**: Select a [region](#available-regions-for-projects-in-cloud) to deploy the project. For better performance, choose a region that's closer to your target users. The region can't be changed later.
    - **Project root directory**: If your project is in a monorepo, specify the path to the Medusa project in the repository. Otherwise, leave it empty.
4. You can expand the "Environment variables" section to optionally add environment variables:
    - 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.
5. 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.
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. You'll be redirected to the organization dashboard, where you can see the project in the list of projects.

<Note>

If the project creation takes too long, check out the [troubleshooting section](#troubleshooting-project-creation).

</Note>

![The organization dashboard with a project in the list of projects](https://res.cloudinary.com/dza7lstvk/image/upload/v1749742078/Cloud/CleanShot_2025-06-12_at_18.27.34_2x_voskmq.png)

If you click on the project, you'll be taken to the project's dashboard, where you can view [its details and status](#find-project-details).

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.

![The project status in the list of projects](https://res.cloudinary.com/dza7lstvk/image/upload/v1749743107/Cloud/CleanShot_2025-06-12_at_18.40.07_2x_asgpxm.png)

---

## Troubleshooting Project Creation

If you encounter any issues while creating a project:

- [Check the build and runtime logs of the project's production deployment](../logs/page.mdx).
- Contact support for help.

---

## Subdomain Restrictions for Projects

Your project'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`

---

## 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 URL of its Production environment.

Learn more in the [Deployments](../deployments/page.mdx#access-live-deployment) guide.

---

## Open Project Dashboard

To open a project's dashboard:

1. Make sure you're viewing the [correct organization's dashboard in Cloud](../organizations/page.mdx#switch-organization).
2. Open the project's dashboard by clicking on the project card in the organization's dashboard.

When you open a project's dashboard, its name will be shown at the top left next to the [organization switcher](../organizations/page.mdx#organization-switcher).

![The project name at the top left of the Cloud dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1749801071/Cloud/CleanShot_2025-06-13_at_10.50.43_2x_m1snj2.png)

### Find Project Details

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

![The project dashboard with the details of a project](https://res.cloudinary.com/dza7lstvk/image/upload/v1759405506/Cloud/CleanShot_2025-10-02_at_14.42.33_2x_w4ql3x.png)

1. **Region**: The region where the project is deployed. You'll find it below the project name.
2. **Environments**: The environments for the project are shown as cards. By default, you'll find Production and Previews environments. You can learn more about environments in the [Environments](../environments/page.mdx) guide.
    - The Production environment is the live environment where your Medusa application is deployed and clients connect to.
    - The 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.
    - Other [Long-lived environments](../environments/long-lived/page.mdx) like Staging will be shown here if you create them.
3. **Production URL**: The URL of the project's production deployment. You'll find it in the "Production" card under the title. Clicking it will open the production Medusa Admin in a new tab.
4. **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.
5. **Production Deployment Status**: The deployment status of the project's environment, which may be "Live" or "Building". Learn more in the [Deployments](../deployments/page.mdx#deployment-statuses-and-lifecycle) 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.

![Project switcher at the top left of the Cloud dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1749743106/Cloud/CleanShot_2025-06-12_at_18.39.27_2x_imjvkt.png)

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 on the "Deployments" tab in 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](../deployments/page.mdx) 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 on the "Settings" tab.
3. In the "General" tab of the Settings page, you can edit the project's name and root directory in the repository.
    - Editing the root directory in the repository is useful if the repository is a monorepo.
4. Once you're done making changes, click the "Save changes" button next to the input field.

![The project settings with the General tab selected](https://res.cloudinary.com/dza7lstvk/image/upload/v1749744080/Cloud/CleanShot_2025-06-12_at_18.58.20_2x_gzis0n.png)

### Editing Previews Settings

You can also edit the "Previews" settings of a project from the "Settings" tab, which are general settings related to Previews environments.

Learn more in the [Preview Environments](../environments/preview/page.mdx) guide.

---

## 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 on the "Settings" tab.
3. In the "General" tab of the Settings page, click the "Delete Project" button.
4. Confirm the deletion by typing the project's name in the confirmation input, then click the "Delete" button.

![The project settings with the General tab selected and the Delete project section highlighted](https://res.cloudinary.com/dza7lstvk/image/upload/v1749744219/Cloud/CleanShot_2025-06-12_at_19.03.10_2x_p6lttt.png)
