Deploying Medusa on AWS: Simplify Your Setup with Microtica

Medusa is an open-source, Node.js-based commerce platform, a flexible alternative to hosted solutions like Shopify. Its modular architecture lets you build exactly the store you need, from product management to payments and fulfilment. Running it on AWS gives you that flexibility on infrastructure you own. This guide deploys a Medusa server and its admin dashboard to your AWS account with Microtica’s Medusa template, step by step.

What Is Medusa and Why Deploy It on AWS?

Medusa is an open-source Node.js commerce engine. It is highly customizable, which is why so many teams choose it: you plug in the features you need and change the ones you don’t like.

A Medusa store has three parts:

• A headless backend that holds the store’s logic and data and exposes the APIs.
• An admin dashboard where store operators manage products and orders.
• A storefront, the website where customers browse and buy.

The template deploys the first two. Your storefront talks to the backend’s store API.

Running Medusa on AWS with the template gives you:

• Serverless containers on Amazon ECS with Fargate, so there are no servers to patch.
• The application, database and files in your own AWS account.
• Managed PostgreSQL and Redis, created for you.
• A build and deploy on every push to your repository.
• Scaling settings and CloudWatch alarms you can tune after launch.

The template is set up to be cost-efficient, but it does create billable AWS resources. Knowing the common AWS cost challenges helps you keep the bill predictable.

What the Template Creates

The Medusa template creates these infrastructure resources in your AWS account:

• Medusa on Amazon ECS with Fargate: one service in Shared mode, or a server and a separate worker in Server & Worker mode.
• An Application Load Balancer in front of the Medusa API.
• A PostgreSQL database on Amazon RDS, unless you point Medusa at a database you already have.
• Redis on Amazon ElastiCache.
• An Amazon EFS file system for uploads and an S3 bucket for media.
• The admin dashboard, hosted in S3 behind Amazon CloudFront.
• Logs and CloudWatch alarms for CPU, memory and request volume.

Before You Start

You need:

• A Microtica account. Sign up with your email or a Git account.
• A connected Git account. Connect GitHub, GitLab or Bitbucket under Integrations. Microtica creates the Medusa repository there.
• An AWS account. You connect it to your environment during the deploy, if it isn’t connected yet.
• An environment on AWS with CloudFormation. Medusa can only go into environments that use AWS and CloudFormation. If none of yours do, the flow links you to Environments to create one.

Step-by-Step Guide to Deploy Medusa

Step 1: Pick the Medusa template

Open Templates in the sidebar. Under Microtica templates, find Medusa in the Infrastructure group and open it. Microtica asks which environment it should go into.

Environments that don’t use AWS with CloudFormation are greyed out. Pick one and continue.

Step 2: Choose where the code goes

Pick the Git account and the owner for the new repository. Microtica names it medusa-server by default. You can change the name, as long as no repository with that name exists yet.

The repository gets the Medusa server code from the template, plus the .microtica folder with its pipeline and infrastructure definition. Every push to master builds and deploys it.

Step 3: Name it and set the admin login

Fill in three settings:

• App Name. Letters only, up to 20 characters. It goes into the name of everything the template creates, so pick something short like shop.
• Admin Dashboard Email and Admin Dashboard Password. Medusa creates its first admin user with these. Change the password after you sign in for the first time.

Two more settings keep their defaults unless you open them:

• Mode. Shared runs the API and background jobs in one service. Server & Worker runs the jobs in a separate worker service, which suits busier stores.
• External Database URL. Leave it empty and the template creates a PostgreSQL database on RDS. Fill it in to use a database you already run, in the form postgresql://username:password@host:port/database.

Step 4: Review and deploy

The review lists what Medusa adds to the environment, the new repository, the settings you changed and, in order, what happens when you press the button. Nothing is created before that.

If the environment has no AWS account yet, Microtica asks you to connect one first. Then press Create and deploy.

Step 5: Follow the run

Microtica creates the repository and opens the run. The Package step builds the Medusa server, its admin dashboard and the container image. DeployComponent then deploys everything to your environment.

The first deploy takes a while, mostly while AWS creates the database and the CloudFront distribution. You can close the page; the run keeps going. If a step fails, the run page shows which one and its log, and you can ask Mica to look into the failure.

Step 6: Open the admin dashboard and the API

When the run finishes, open Apps, then your environment and the app you named (shop here). Its Outputs list the addresses:

• AccessUrl opens the Medusa admin dashboard. Sign in with the admin email and password from step 3.
• APIAccessUrl is the Medusa API. Add /health to it to check that the server answers.

Both addresses use plain HTTP at first. To serve the admin and the API on your own domains over HTTPS, open the component’s Settings, fill in Admin Domain name and API Domain name with their certificate ARNs from AWS Certificate Manager, and deploy. The same settings cover replicas, the scaling threshold, environment variables and the store’s CORS origins.

Updating and removing it

Push to master in your Medusa repository and Microtica builds and deploys the change. Each deploy shows up under Deploys on the component page.

To remove the AWS resources, open the component’s menu and choose Undeploy, keep settings. Microtica deletes the resources from AWS but keeps the configuration, so you can deploy it again later. Remove from the environment takes it out of Microtica as well.

Deploy an Existing Medusa Server

If you already have a Medusa repository and want to run it on AWS, you may need to adjust your code for the template’s setup. The Medusa server documentation explains how to configure and import an existing project.

Common Deployment Issues and Troubleshooting

• Settings that don’t validate. The app name takes letters only, and the admin email has to be a valid address. The settings step names whatever is missing before you can continue.
• An environment that won’t take new resources. If an earlier deploy left the environment in a failed state, the review says it has to be undeployed first and links to its settings.
• A failed run. Open the failed step’s log on the run page. Build errors usually come from the code, deploy errors from AWS. Fix the cause, then run it again.
• AWS limits. New AWS accounts have quotas on resources such as load balancers and database instances. If a deploy fails on a limit, the error names it, and you can request an increase in the AWS console.

Following production deployment best practices helps you avoid most of these before they happen.

Conclusion

The Medusa template gives you a complete Medusa backend and admin dashboard on AWS in a few steps: the database, Redis, storage, load balancing and the deploy pipeline included. It runs in your own account, and every push to your repository ships the next version.