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.

Prerequisites#

Before creating a project, ensure you have:

• A Medusa application whose codebase is hosted in a GitHub repository.
  • If you don't have a Medusa application yet, refer to the Installation guide to set up a new Medusa application.
• A Cloud account with a valid plan that allows creating more projects.
  • If you've exceeded the number of projects limit for your plan, you can contact support to upgrade your plan.

Medusa Application Configurations

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

Steps to Create a Project#

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.

3. If you haven't authenticated with GitHub yet, you'll be asked to authenticate first.
4. Once you're authenticated, you'll need to select a GitHub account and the repository that contains your Medusa application's code. The repository can be public or private.
   • If you don't see your repository, you can click the "Configure repositories" link to manage the GitHub repositories that Medusa can access.
5. Once you find the repository, select it and click the "Next" button.

6. In the next step, configure the project's settings:
   • Enter the name of the project.
   • 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.

7. You can optionally change the "Build and project" settings by expanding its section:
   • 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.
     • If you don't find the region you need, you can contact support to request it.
   • If your project is in a monorepo, you can specify the path to the Medusa project in the repository. Otherwise, leave it empty.
   • 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.

8. You can optionally add Environment Variables by expanding its section:
   • 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.

9. Once you're done configuring the project, click the Create Project 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.

Access Deployed Project#

To access the deployed project, you can access 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 its 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.