Medusa is an open-source, self-hosted e-commerce platform designed to give developers full customization and control over their storefront. It’s built with a modular architecture to enable seamless integrations and enhanced scalability, making it an excellent choice for businesses seeking a tailored solution. This guide will walk you through installing Medusa, configuring it with a reverse proxy for secure access, managing logs and backups, updating the platform, and leveraging its unique features.
Installing Medusa
📦 Docker/Docker Compose Setup
Using Docker simplifies the deployment of Medusa by isolating dependencies and providing an easily reproducible environment. Below is a docker-compose.yml file for setting up Medusa.
version: '3.8'
services:
medusa:
image: medusajs/medusa:latest
container_name: medusa
ports:
- "9000:9000" # Exposes Medusa on port 9000
environment:
MEDUSA_ADMIN_CORS: http://localhost:7000
MEDUSA_STORE_CORS: http://localhost:8000
DATABASE_URL: postgres://medusa_user:password@postgres:5432/medusa_db
depends_on:
- postgres
volumes:
- ./medusa-data:/data # Persistent storage for Medusa
postgres:
image: postgres:13
container_name: medusa_postgres
environment:
POSTGRES_USER: medusa_user
POSTGRES_PASSWORD: password
POSTGRES_DB: medusa_db
volumes:
- ./postgres-data:/var/lib/postgresql/data # Persistent storage for PostgreSQL
To deploy Medusa with Docker Compose, run the following commands:
mkdir medusa && cd medusa
nano docker-compose.yml # Paste the file above
docker-compose up -d # Start the Medusa service
🚀 Manual Installation
For those who prefer manual installation on a Linux server, follow these steps:
sudo apt update && sudo apt upgrade -y
curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt install -y nodejs yarn
## Install PostgreSQL
sudo apt install -y postgresql postgresql-contrib
sudo -u postgres psql -c "CREATE USER medusa_user WITH PASSWORD 'password';"
sudo -u postgres psql -c "CREATE DATABASE medusa_db;"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE medusa_db TO medusa_user;"
## Clone and install Medusa
git clone https://github.com/medusajs/medusa.git
cd medusa
yarn install
yarn start
This setup will launch Medusa locally on port 9000.
Configuring Nginx as a Reverse Proxy
🌐 Nginx Configuration
To serve Medusa securely, use Nginx as a reverse proxy. Below is an example server block:
server {
listen 80;
server_name yourdomain.com;
location / {
proxy_pass http://localhost:9000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
Save this configuration in /etc/nginx/sites-available/medusa and enable it:
sudo ln -s /etc/nginx/sites-available/medusa /etc/nginx/sites-enabled/
sudo nginx -t # Test the configuration
sudo systemctl reload nginx
🔒 SSL/TLS Setup
Secure your Medusa instance using Let's Encrypt:
sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d yourdomain.com
Automate SSL renewal with a cron job:
sudo crontab -e
## Add the following line:
0 3 * * * certbot renew --quiet
Logging and Debugging Medusa
🗃️ Enabling Debug Logs
Enable debug logs for detailed information. Update the Medusa environment configuration or .env file:
LOG_LEVEL=debug
Restart Medusa to apply changes:
docker-compose restart medusa
📄 Viewing Logs
For Docker-based setups, access logs with:
docker logs -f medusa
For manual installations, logs are typically available in the terminal output or a configured log file.
🛠️ Troubleshooting Common Issues
If Medusa fails to start, common errors include database connectivity issues. Check the logs for errors like:
Error: Unable to connect to database.
Ensure the database credentials and DATABASE_URL environment variable are correct.
📤 Exporting Logs
Forward logs to an external ELK Stack:
docker logs medusa > medusa-logs.log
## Use Filebeat to ship logs to ELK (configure Filebeat accordingly)
Backup and Restore
🗂️ File-Based Backups
Backup the Medusa configuration and data directories:
tar -cvzf medusa-backup.tar.gz ./medusa-data
Restore the backup with:
tar -xvzf medusa-backup.tar.gz -C /path/to/restore
🔄 Database Backups
Dump the PostgreSQL database:
pg_dump -U medusa_user -F c medusa_db > medusa_db_backup.sql
Restore the database:
pg_restore -U medusa_user -d medusa_db medusa_db_backup.sql
📅 Automated Backup Scripts
Schedule periodic backups with cron:
crontab -e
## Add the following line:
0 2 * * * pg_dump -U medusa_user -F c medusa_db > /path/to/backups/medusa_db_$(date +\%F).sql
Updating and Upgrading Medusa
⬆️ Updating Docker Images
Pull the latest Medusa image and restart the service:
docker-compose pull medusa
docker-compose up -d
🛠️ Manual Updates
For manual installations, pull the latest code from the repository and rebuild:
cd medusa
git pull
yarn install
yarn build
yarn start
🔍 Checking for Updates
Verify the latest Medusa version on GitHub and compare it to your installation.
Leveraging Medusa’s Unique Features
🔧 Enabling APIs
Medusa provides APIs for integration. Enable them in your .env file:
MEDUSA_BACKEND_URL=http://yourdomain.com
Test API endpoints with curl:
curl http://yourdomain.com/store/products
🌟 Advanced Configurations
Integrate third-party tools like Redis for caching:
REDIS_URL=redis://localhost:6379
Ensure Redis is installed and running:
sudo apt install redis -y
sudo systemctl enable redis
sudo systemctl start redis
Wrapping Up
This guide has provided a comprehensive walkthrough on deploying, configuring, and managing your self-hosted Medusa instance. By following these steps, you can harness Medusa’s flexibility and customization options to build a powerful and scalable e-commerce solution. Whether you’re debugging, automating backups, or integrating APIs, you now have the tools to make the most of your self-hosted setup. Happy hosting!
