Install MedusaGo

In this chapter, you'll learn how to install and run a MedusaGo application.

Create MedusaGo Application#

A MedusaGo application is made up of a Go server that also serves the Medusa Admin dashboard. You can optionally install the Next.js Starter Storefront while installing the MedusaGo application, or at a later point.

To create a MedusaGo application, run the create-medusago-app installer with go run:

go run github.com/hitkey-io/medusago/packages/cli/create-medusago-app@latest my-medusa-store

my-medusa-store is the name of the project's directory. The command also creates a PostgreSQL database for the project named medusa-my-medusa-store. While the command runs, it asks whether you want to install the storefront.

The installer creates the project from the MedusaGo starter. The backend, with the Medusa Admin, is in the apps/backend directory. If you chose to install the storefront, it's in the apps/storefront directory.

If your PostgreSQL server doesn't accept the default postgres user without a password, the installer asks for your PostgreSQL username and password.

Successful Installation Result#

Once the installation finishes successfully, the MedusaGo application runs at http://localhost:9000.

The Medusa Admin dashboard runs at http://localhost:9000/app. The installer opens it in your default browser so you can create an admin user. Use that user to log in later.

If you also installed the storefront, it's running at http://localhost:8000.

You can stop the servers by exiting the installer. To run the MedusaGo application again, refer to the Run MedusaGo Application in Development section.

Run MedusaGo Application in Development#

To run the MedusaGo application in development, change to the backend's directory (apps/backend) and run the following command:

go run . develop

This runs your MedusaGo server at http://localhost:9000, and the Medusa Admin dashboard at http://localhost:9000/app.

The develop command watches your project. When you change a file, it rebuilds your application and restarts the server. Learn more in the Medusa CLI reference.

The Health Endpoint#

To check that the server is running, send a request to http://localhost:9000/health. It responds with OK.

Create Medusa Admin User#

Besides creating an admin user in the admin dashboard, you can also create one with the CLI.

Run the following command in the backend's directory (apps/backend) to create a new admin user:

go run . user -e admin@medusajs.com -p supersecret

Replace admin@medusajs.com and supersecret with the user's email and password respectively.

You can then use the user's credentials to log in to the Medusa Admin dashboard.

Project Files#

Your MedusaGo application's project (apps/backend) has the following files and directories:

apps/backend
├── .env.template
├── go.mod
├── main.go
├── medusa-config.go
└── src
    ├── admin
    ├── api
    ├── jobs
    ├── links
    ├── modules
    ├── scripts
    ├── subscribers
    └── workflows

main.go#

The entry point of your application. It runs the Medusa CLI with your project's configuration and customisations. This is why you run commands as go run . <command>.

import (
	"os"

	cli "github.com/hitkey-io/medusago/packages/cli/medusa-cli/src"
)

func main() {
	os.Exit(cli.Run(os.Args[1:], cli.Options{
		Config: medusaConfig,
	}))
}

medusa-config.go#

This file holds your MedusaGo configurations, such as your PostgreSQL database URL. It returns the configuration that main.go passes to the CLI.

.env.template#

A template of the environment variables your application uses. The installer creates the .env file with the values for your database.

src#

This directory is the central place for your custom development. Go has no file-system discovery, so each part that you add is a Go package that you register in main.go or medusa-config.go. The subdirectories are:

• admin: Holds your admin dashboard's custom widgets and UI routes. These are React components, so they're JavaScript or TypeScript files.
• api: Holds your custom API routes that are added as endpoints in your application.
• jobs: Holds your scheduled jobs that run at a specified interval during your application's runtime.
• links: Holds your module links that build associations between data models of different modules.
• modules: Holds your custom modules that implement custom business logic.
• scripts: Holds your custom scripts to be executed using the CLI's exec command.
• subscribers: Holds your event listeners that are executed asynchronously whenever an event is emitted.
• workflows: Holds your custom workflows that can be executed from anywhere in your application.

.medusa#

The build command creates a .medusa directory with the production build. Don't modify its files or commit them to your repository. Learn more in the Build chapter.

Configure MedusaGo Application#

By default, your MedusaGo application is equipped with the basic configuration to start your development.

If you run into issues with configurations, such as CORS errors, or need to change the default configuration, refer to the MedusaGo Configurations guide.

Update MedusaGo Application#

Refer to the Update MedusaGo guide to learn how to update your project.

Next Steps#

In the next chapters, you'll learn about the architecture of your MedusaGo application, then learn how to customise your application to build custom features.