260 lines
13 KiB
Plaintext
260 lines
13 KiB
Plaintext
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.
|
|
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, 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>
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
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).
|
|
|
|
|
|
|
|
### 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](../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.
|
|
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](../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.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
### 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.
|
|
|
|
|