202 lines
6.8 KiB
Plaintext
202 lines
6.8 KiB
Plaintext
---
|
|
description: "Learn how to install Medusa's admin dashboard. The admin dashboard gives merchants an easy-to-use interface to manage their data such as orders, products, regions, and more."
|
|
addHowToData: true
|
|
---
|
|
|
|
import Feedback from '@site/src/components/Feedback';
|
|
import DetailsList from '@site/src/components/DetailsList'
|
|
import AdminLoginSection from '../troubleshooting/signing-in-to-admin.md'
|
|
import CorsSection from '../troubleshooting/cors-issues.md'
|
|
|
|
# Admin Dashboard Quickstart
|
|
|
|
This document will guide you through setting up the admin dashboard in the Medusa backend.
|
|
|
|
## Overview
|
|
|
|
The admin dashboard is installed on the Medusa backend. The admin dashboard starts when you start the Medusa backend. This also means you can later deploy the Medusa backend along with the admin dashboard on the same hosting.
|
|
|
|
This guide will explain the steps and configurations required to set up the admin dashboard.
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
### Medusa Backend
|
|
|
|
As the admin dashboard is a plugin installed on the Medusa Backend, you must have a Medusa Backend installed first. You can learn how to install it in [this documentation](../development/backend/install.mdx).
|
|
|
|
### Node.js
|
|
|
|
The Admin uses [Vite v4.1.4](https://vitejs.dev/guide/#scaffolding-your-first-vite-project) which requires v14.8+ or v16+ of Node.js, and as Medusa requires v16 or greater it's recommended you use v16+ of Node.js.
|
|
|
|
You can check which version of Node you have by running the following command:
|
|
|
|
```bash noReport
|
|
node -v
|
|
```
|
|
|
|
You can install Node from the [official website](https://nodejs.org/en/).
|
|
|
|
---
|
|
|
|
## Install and Serve Admin with the Backend
|
|
|
|
This section explains how to install the admin to be served with the Medusa Backend and later deployed together.
|
|
|
|
### Step 1: Install the Package
|
|
|
|
In the directory of your Medusa backend, run the following command to install admin dashboard:
|
|
|
|
```bash npm2yarn
|
|
npm install @medusajs/admin
|
|
```
|
|
|
|
### Step 2: Add Admin to Medusa Configurations
|
|
|
|
In `medusa-config.js`, add the admin plugin into the array of `plugins`:
|
|
|
|
```js title="medusa-config.js"
|
|
const plugins = [
|
|
// ...
|
|
{
|
|
resolve: "@medusajs/admin",
|
|
/** @type {import('@medusajs/admin').PluginOptions} */
|
|
options: {
|
|
// ...
|
|
},
|
|
},
|
|
]
|
|
```
|
|
|
|
The plugin accepts the following options:
|
|
|
|
1. `serve`: (default: `true`) a boolean indicating whether to serve the admin dashboard when the Medusa backend starts. If set to `false`, you can serve the admin dashboard using the [dev command](./configuration.md#dev-command-options).
|
|
2. `path`: (default: `app`) a string indicating the path the admin server should run on when running the Medusa backend in production. It must be prefixed with a slash `/`, but it can't end with a `/`, which throws an error. It also can't be one of the reserved paths: "admin" and "store".
|
|
3. `outDir`: Optional path for where to output the admin build files.
|
|
4. `autoRebuild`: (default: `false`) a boolean indicating whether the admin UI should be rebuilt if there are any changes or if a missing build is detected when the backend starts. If not set, you must [manually build the admin dashboard](./configuration.md#build-command-options).
|
|
5. `develop`: An optional object that accepts the following properties:
|
|
- `open`: (default: `true`) a boolean value that indicates if the browser should be opened when the medusa project is first started.
|
|
- `port`: (default: `7001`) a number indicating the port the admin dashboard runs on.
|
|
|
|
### Optional: Manually Building Admin Dashboard
|
|
|
|
If you have `autoRebuild` disabled, you must build your admin dashboard before starting the Medusa backend. Refer to the [build command](./configuration.md#build-command-options) for more details.
|
|
|
|
### Step 3: Test the Admin Dashboard
|
|
|
|
:::tip
|
|
|
|
If you disabled the `serve` option, you need to run the admin dashboard separately using the [dev command](./configuration.md#dev-command-options)
|
|
|
|
:::
|
|
|
|
You can test the admin dashboard by running the following command in the directory of the Medusa backend:
|
|
|
|
```bash
|
|
npx medusa develop
|
|
```
|
|
|
|
This starts the Medusa Backend and the admin dashboard in a development environment. By default, the admin will be available on the URL `localhost:7001` and the browser will open automatically to the admin dashboard in your default browser, unless you have the `develop.open` option disabled.
|
|
|
|
<Feedback
|
|
event="survey_admin_quickstart"
|
|
question="Did you set up the admin successfully?"
|
|
positiveQuestion="Is there anything that should improved?"
|
|
negativeQuestion="Please describe the issue you faced."
|
|
/>
|
|
|
|
---
|
|
|
|
## Production Path
|
|
|
|
:::note
|
|
|
|
This doesn't apply if you have the `serve` option disabled.
|
|
|
|
:::
|
|
|
|
When you run the Medusa project in a production environment (such as with the `npx medusa start` command), the admin dashboard will be available at `<MEDUSA_URL>/<ADMIN_PATH>`, where:
|
|
|
|
1. `<MEDUSA_URL>` is the URL of your Medusa backend. By default, it'll be `localhost:9000` locally.
|
|
2. `<ADMIN_PATH>` is the path you define in the [admin's configurations](#step-2-add-admin-to-medusa-configurations).
|
|
|
|
So, if you simulate a production environment locally, the admin dashboard will run by default on `localhost:9000/app`.
|
|
|
|
---
|
|
|
|
## Demo Credentials
|
|
|
|
If you installed the demo data when you installed the Medusa backend by running:
|
|
|
|
```bash npm2yarn
|
|
npm run seed
|
|
```
|
|
|
|
You can use the email `admin@medusa-test.com` and password `supersecret` to log in.
|
|
|
|
:::info
|
|
|
|
Passwords in Medusa are hashed using the [scrypt-kdf](https://www.npmjs.com/package/scrypt-kdf). The password hash is then stored in the database.
|
|
|
|
:::
|
|
|
|
---
|
|
|
|
## Create a New Admin User
|
|
|
|
To create a new admin user from the command line, run the following command in the directory holding your Medusa backend:
|
|
|
|
```bash
|
|
npx medusa user -e some@email.com -p some-password
|
|
```
|
|
|
|
This will create a new user that you can use to log into your admin panel.
|
|
|
|
---
|
|
|
|
## Admin User Guide
|
|
|
|
The admin dashboard provides a lot of ecommerce features including managing Return Merchandise Authorization (RMA) flows, store settings, products, orders, and much more.
|
|
|
|
You can learn more about the admin dashboard and its features in the [User Guide](../user-guide.mdx).
|
|
|
|
---
|
|
|
|
## Multi-Language Support
|
|
|
|
Medusa supports multiple languages and translations. Check out available languages [here](../user-guide/tips/languages.md).
|
|
|
|
Refer to [this user guide](../user-guide/users/profile.md#change-admin-language) to learn how to switch the language of the Medusa admin.
|
|
|
|
:::note
|
|
|
|
Can't find your language? Learn how you can contribute by translating the admin to other languages [here](../contribution/admin-translations.md).
|
|
|
|
:::
|
|
|
|
---
|
|
|
|
## Troubleshooting Installation
|
|
|
|
<DetailsList
|
|
sections={[
|
|
{
|
|
title: 'Signing into Admin',
|
|
content: <AdminLoginSection />
|
|
},
|
|
{
|
|
title: 'CORS Errors',
|
|
content: <CorsSection />
|
|
}
|
|
]}
|
|
/>
|
|
|
|
---
|
|
|
|
## See Also
|
|
|
|
- [Admin Configuration](./configuration.md)
|
|
- [Admin widgets](./widgets.md)
|
|
- [Admin UI routes](./routes.md)
|