Projects

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.

Create a Project#

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

To create a project:

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.

Create 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 the Clone button of the starter.
2. In the Repository step, authenticate with your GitHub account if you haven't already.
3. 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.
4. In the "Repository name" field, enter a name for your new repository.
5. Once you're done, click the Continue button.

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

Create 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.
• 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
  • Redis Event Module
  • Redis Locking Module Provider
  • Redis Workflow Engine Module
  • S3 File Provider Module

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.

Creation Steps

To create a project from an existing Medusa application:

1. Click on the Import Repository button at the top right.
2. In the Repository step, authenticate with your GitHub account if you haven't already.
3. 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.
4. Once you're done, click the Continue button.

You'll move forward to the Configure step.

Configure Project#

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 section for more details.
3. You can expand the "Build details" section to optionally change its configurations:
   • 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.
   • Project root directory: If your project is in a monorepo, specify the path to the Medusa project in the repository. Otherwise, leave it empty.
   • Admin email and password: You can change the email and password for the admin user created for the project. These are the credentials you'll use to access the Medusa Admin.
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. 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.

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 the build and runtime logs of the project's production deployment.
• Contact support for help.

Subdomain Restrictions#

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 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)

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 guide.

Open Project Dashboard#

To open a project's dashboard:

1. Make sure you're viewing the correct organization's dashboard in Cloud.
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.

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. 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 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.
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 Status: The status of the project's environment, which may be "Live" or "Building". 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 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 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 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.

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 guide.

Delete Project#

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.