Medusa on AWS User Guide

Overview

This image runs Medusa, the flexible open source headless commerce platform built on Node.js and TypeScript. Medusa provides a modular commerce engine with Store and Admin REST APIs and a built in Admin dashboard, so you can build storefronts, marketplaces and B2B commerce experiences with full control over your data.

The Medusa server runs as a dedicated unprivileged medusa system account under a systemd service that starts it on boot and restarts it on failure. The server is built into /opt/medusa/app/.medusa/server and serves the Admin dashboard at /app, the Store API at /store, the Admin API at /admin and the authentication routes at /auth. PostgreSQL holds the commerce data and Redis backs the workflow engine, the event bus and the cache; both are co located on the instance. The project, the built server output and the PostgreSQL data directory live on /opt/medusa, which is a dedicated, independently resizable EBS data volume.

The Medusa server binds to the loopback interface only and is never exposed directly. An nginx reverse proxy publishes the Admin dashboard and the Store and Admin APIs on port 80. Medusa's own admin user authentication gates the Admin dashboard and the Admin API. The administrator account and password are generated on the first boot of every deployed instance, so two instances launched from the same Amazon Machine Image never share credentials. They are written to /root/medusa-credentials.txt with mode 0600 so that only the root user can read them.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and port 80 for the Admin dashboard and the APIs
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Medusa. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.medium or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network and port 80 for the Admin dashboard and the APIs. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation generates the administrator credentials and starts the commerce server; allow a minute or two after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Medusa Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22 and 80 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.medium \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=medusa}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i <key-name>.pem ubuntu@<public-ip>

Step 4: Retrieve the Admin Credentials

The Medusa administrator account is unique to your instance and was generated on first boot. Read it as root:

sudo cat /root/medusa-credentials.txt

The file lists the Admin dashboard URL, the administrator email and password, and the PostgreSQL database name, user and password. Keep these credentials somewhere safe.

Step 5: Sign In to the Admin Dashboard

The built in Medusa Admin dashboard is served on port 80 at the /app path by nginx. In a browser, go to:

http://<instance-public-ip>/app

Sign in with the administrator email and password from the credentials file. After signing in you land in the Admin dashboard, the starting point for managing your store. The Inventory view lists every stock item and its on-hand quantity.

Open Products to manage your catalogue. Each product has variants, prices, options and inventory, all editable from the dashboard.

Open Settings to configure regions, currencies, sales channels, API key management and the other store wide commerce settings.

Step 6: Confirm Medusa Is Running

Over SSH, confirm the commerce server, PostgreSQL, Redis and the nginx proxy are active and that the ports are listening:

sudo systemctl is-active medusa postgresql redis-server nginx
sudo ss -tlnp | grep -E ':(80|9000) '

You should see the services reported as active, the Medusa server listening on 127.0.0.1:9000 (loopback only), and nginx listening on port 80.

You can also call the unauthenticated health endpoint through the proxy:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/health

This returns 200 when the server is ready.

Step 7: Obtain an Admin API Token

The Admin REST API at /admin is protected by Medusa's authentication. Obtain a JSON Web Token by posting the administrator email and password to the email/password auth route. Replace the email and password with the values from your credentials file:

curl -s -X POST http://127.0.0.1/auth/user/emailpass \
  -H 'Content-Type: application/json' \
  --data '{"email":"admin@example.com","password":"your-password"}'

A successful response contains a token field. Pass that token as a bearer token to call the Admin API, for example to fetch the signed in user:

curl http://<instance-public-ip>/admin/users/me \
  -H "Authorization: Bearer <token>"

Step 8: Use the Store API

The Store REST API at /store is what your storefront calls to read products, manage carts and place orders. Point your storefront at the instance on port 80 and call /store endpoints. Store endpoints use a publishable API key, which you create under Settings then Publishable API Keys in the Admin dashboard. The bare root of the server also responds, redirecting browsers to the Admin dashboard at /app.

Step 9: Create Additional Admin Users

Create more administrator accounts with the Medusa CLI from the built server directory. This command is run on the instance over SSH:

cd /opt/medusa/app/.medusa/server
sudo -u medusa npx medusa user -e newadmin@example.com -p a-strong-password

The new user can then sign in to the Admin dashboard and obtain an API token exactly as above.

Step 10: The Data Volume

The Medusa project, the built server output and the co located PostgreSQL data directory live on a dedicated EBS volume mounted at /opt/medusa. This keeps the commerce store off the operating system disk and lets you resize or snapshot it independently. Confirm the mount with:

df -h /opt/medusa

To grow the store, expand the EBS volume in the AWS console, then grow the filesystem on the instance with sudo resize2fs on the underlying device.

Step 11: Enable HTTPS

The Admin dashboard and APIs are served over plain HTTP on port 80 by nginx. For production use, place them behind TLS. Obtain a certificate for your domain (for example with a managed certificate on an Application Load Balancer in front of the instance, or with Certbot installed on the instance), then configure nginx to listen on 443 with your certificate and proxy to 127.0.0.1:9000 exactly as the bundled site does for port 80. After adding a domain and TLS, set MEDUSA_BACKEND_URL, STORE_CORS, ADMIN_CORS and AUTH_CORS in /opt/medusa/app/.medusa/server/.env to your HTTPS origin and restart the service with sudo systemctl restart medusa. Restrict the security group so ports 80 and 443 are reachable only from the networks that need them.

Step 12: Backup and Maintenance

Back up the store by snapshotting the /opt/medusa EBS volume, which captures the commerce database and the application. For a logical database backup, use pg_dump against the medusa database with the credentials from the credentials file. Apply operating system security updates with sudo apt-get update && sudo apt-get upgrade and reboot when a new kernel is installed; Medusa, PostgreSQL, Redis and nginx all start automatically on boot.

Support

This image is published and supported by cloudimg. Support covers deployment, storefront integration, the Admin and Store APIs, custom modules and workflows, PostgreSQL and Redis tuning, region and currency setup, and TLS. Contact cloudimg through the support channel listed on the AWS Marketplace listing.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.