Medusa позиционирует себя как open-source альтернативу Shopify и в этой роли завоевала аудиторию: более 20,000 звёзд на GitHub, тысячи магазинов в продакшн. Разница с Shopify принципиальная: Shopify — SaaS с $29–299/месяц, транзакционными комиссиями и ограниченной кастомизацией. Medusa — open-source платформа которую вы разворачиваете на собственном сервере, платите только за хостинг и модифицируете как угодно.
Актуальная версия — Medusa v2. Построена на Node.js и TypeScript, работает на порту 9000, использует PostgreSQL как основную СУБД и Redis для фоновых задач. Лицензия: MIT — самая разрешительная из open-source, коммерческое использование без ограничений.
В этом руководстве разберём кому подходит Medusa, как установить её на VPS THE.Hosting в любой из 50+ локаций — от Германии (Франкфурт) до Японии (Токио) — и как запустить в продакшн с PostgreSQL, Redis, PM2 и Nginx.
Что такое Medusa и чем отличается от Shopify
Сравнение с Shopify помогает быстро понять что Medusa делает, а что нет.
Shopify — монолит: магазин, витрина, хостинг, платёжная система, CDN — всё вместе в одном SaaS. Быстро запустить, не нужен разработчик, но каждое нестандартное требование превращается в костыль или дорогой плагин. Плюс транзакционные комиссии на каждый заказ.
Medusa — API-first фреймворк: бэкенд предоставляет REST API и GraphQL для всех операций с магазином, фронтенд строится отдельно. Нет ограничений на кастомизацию checkout, логику цен, интеграции с любыми платёжными системами. Никаких транзакционных комиссий Medusa не берёт вообще.
Из коробки в Medusa: управление продуктами и каталогом, корзина и checkout, управление заказами, клиенты и их история, скидки и промокоды, поддержка нескольких регионов с разными валютами и налогами, управление запасами. Административный дашборд доступен по /app на том же сервере.
Medusa — инструмент для разработчиков. Настроить магазин через интерфейс без написания кода можно, но фронтенд придётся строить самостоятельно или через официальный Next.js Starter Storefront.
Системные требования
- Node.js v20 или выше (v20, v22, v24 — официально тестируются)
- PostgreSQL 10+ (основная и рекомендуемая СУБД)
- Redis 6+ (для фоновых задач и воркера)
- Минимум 2 GB RAM — официальная рекомендация Medusa для продакшн
- 10+ GB дискового пространства
Важно про Next.js Storefront Starter: если планируете установить вместе с витриной, Node.js v24 LTS — максимум. Версия v25+ со стартером несовместима.
Подготовка VPS
Подключаетесь:
ssh root@ваш-IP-адрес
Обновляете систему:
apt update && apt upgrade -y
apt install -y curl wget git build-essential
Создаёте пользователя:
adduser medusa
usermod -aG sudo medusa
su - medusa
Файрвол:
ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 9000/tcp # временно, для проверки
ufw enable
Временная зона:
timedatectl set-timezone Europe/Berlin
Установка Node.js 22
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
nvm alias default 22
node --version # v22.x.x
Установка PostgreSQL
sudo apt install postgresql postgresql-contrib -y
sudo systemctl start postgresql
sudo systemctl enable postgresql
Создаёте базу и пользователя:
sudo -u postgres psql
CREATE DATABASE medusa_db;
CREATE USER medusa_user WITH PASSWORD 'сильный_пароль';
GRANT ALL PRIVILEGES ON DATABASE medusa_db TO medusa_user;
\c medusa_db
GRANT ALL ON SCHEMA public TO medusa_user;
\q
Установка Redis
sudo apt install redis-server -y
sudo systemctl start redis-server
sudo systemctl enable redis-server
redis-cli ping # PONG
Создание Medusa проекта
Используете официальный CLI:
cd ~
npx create-medusa-app@latest my-store
При создании CLI спрашивает:
- What's the name of your project? — имя проекта (или Enter для
my-store) - Would you like to install the Next.js Starter Storefront? — Yes, если нужна витрина сразу; No, если только бэкенд
CLI автоматически подключится к локальному PostgreSQL, создаст базу данных (если указали имя новой), применит миграции и засеет начальные данные.
После завершения установки сервер запускается автоматически. Откройте в браузере http://ваш-IP:9000/app — дашборд попросит создать аккаунт администратора.
Остановите сервер (Ctrl+C) и переходите к продакшн настройке.
Конфигурация окружения
В корне проекта есть файл .env. Открываете:
cd ~/my-store
nano .env
Для продакшн обязательно задайте секретные ключи и убедитесь что DATABASE_URL указывает на правильные данные:
DATABASE_URL=postgres://medusa_user:сильный_пароль@localhost:5432/medusa_db
REDIS_URL=redis://localhost:6379
JWT_SECRET=длинная_случайная_строка_минимум_32_символа
COOKIE_SECRET=другая_длинная_случайная_строка
NODE_ENV=production
Сгенерировать случайные строки для секретов:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
Запустите дважды — для JWT_SECRET и COOKIE_SECRET.
Сборка для продакшн
cd ~/my-store
npm run build
Команда компилирует TypeScript и собирает административный дашборд. Занимает 1–3 минуты.
PM2 для продакшн запуска
npm install -g pm2
Создаёте конфиг PM2:
nano ~/my-store/ecosystem.config.js
module.exports = {
apps: [
{
name: 'medusa-server',
script: 'npm',
args: 'run start',
cwd: '/home/medusa/my-store',
instances: 1,
env: {
NODE_ENV: 'production',
PORT: 9000,
},
},
],
};
Запускаете:
cd ~/my-store
pm2 start ecosystem.config.js
pm2 save
pm2 startup
# скопируйте и выполните команду которую выведет pm2 startup
Проверяете:
pm2 status
pm2 logs medusa-server
Должны видеть строку: Server is ready on port: 9000.
Nginx как обратный прокси
sudo apt install nginx -y
sudo nano /etc/nginx/sites-available/medusa
Содержимое:
server {
listen 80;
server_name api.yourstore.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
server_name api.yourstore.com;
ssl_certificate /etc/letsencrypt/live/api.yourstore.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/api.yourstore.com/privkey.pem;
client_max_body_size 50M;
location / {
proxy_pass http://localhost:9000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
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;
proxy_cache_bypass $http_upgrade;
}
}
sudo ln -s /etc/nginx/sites-available/medusa /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
SSL-сертификат:
sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d api.yourstore.com
После — закрываете прямой доступ:
ufw delete allow 9000/tcp
Настройка CORS
Medusa по умолчанию блокирует запросы с посторонних доменов. В medusa-config.ts (или medusa-config.js) укажите домены вашего фронтенда и дашборда:
module.exports = defineConfig({
projectConfig: {
http: {
storeCors: process.env.STORE_CORS || 'https://yourstore.com',
adminCors: process.env.ADMIN_CORS || 'https://api.yourstore.com',
authCors: process.env.AUTH_CORS || 'https://yourstore.com',
},
databaseUrl: process.env.DATABASE_URL,
redisUrl: process.env.REDIS_URL,
},
});
Добавьте соответствующие переменные в .env:
STORE_CORS=https://yourstore.com
ADMIN_CORS=https://api.yourstore.com
AUTH_CORS=https://yourstore.com
Какой VPS выбрать на THE.Hosting
Минимум для продакшн: официальная рекомендация — 2 GB RAM. Берите Standard VPS с 2 vCPU / 4 GB RAM / 40 GB NVMe — с запасом для PostgreSQL и Redis.
Для роста: 4 vCPU / 8 GB RAM если планируете высокий трафик или несколько регионов с активной синхронизацией инвентаря.
Европейский рынок: Германия (Франкфурт) — GDPR, финансовый хаб; Нидерланды (Меппел) — лучшая связность; Великобритания (Лондон) — для UK-магазинов; Франция (Париж) — франкоязычная аудитория.
Американская аудитория: США (Нью-Джерси, Secaucus) — восточное побережье; Канада (Торонто); Бразилия (Сан-Паулу) — крупнейший рынок Латинской Америки.
Азиатский рынок: Япония (Токио) — минимальный пинг для Восточной Азии; Гонконг — доступ к Китаю; Южная Корея (Сеул).
СНГ: Молдова (Кишинёв) — Dedicated серверы; Финляндия (Хельсинки).
Medusa хорошо масштабируется горизонтально: воркер можно вынести на отдельный VPS, PostgreSQL — на выделенный сервер. Для старта один VPS с 4 GB RAM закроет большинство сценариев.
Типичные проблемы
Ошибка подключения к PostgreSQL. Проверьте что в DATABASE_URL правильный пароль и имя базы. Для PostgreSQL 15+ нужно явно выдать права на схему: GRANT ALL ON SCHEMA public TO medusa_user; в psql.
CORS ошибки при открытии дашборда. В medusa-config.ts в adminCors должен быть указан точный домен откуда открывается дашборд — включая протокол и порт если нестандартный.
PM2 не находит npm или скрипт. Убедитесь что в cwd указан абсолютный путь к проекту, и что Node.js доступен в PATH для пользователя под которым запущен PM2. Если ставили через nvm — добавьте в ~/.bashrc нужный путь.
medusa requires at least v20 of Node.js даже при v22. Это известная проблема когда в системе несколько версий Node.js. Проверьте: which node и node --version. Если путь не совпадает с nvm — перезапустите терминал или выполните nvm use 22.
Сборка падает по памяти. На VPS с 1 GB RAM npm run build может упасть из-за нехватки памяти при сборке TypeScript. Увеличьте лимит: NODE_OPTIONS=--max-old-space-size=1024 npm run build.
Готовы запустить собственную альтернативу Shopify?
На VPS THE.Hosting с NVMe дисками и root доступом вы получаете полный контроль: никаких транзакционных комиссий, никаких ограничений на кастомизацию. 50+ локаций — выбирайте ближайшую к вашей аудитории.
FAQ:
Medusa бесплатная? Open-source ядро под лицензией MIT — полностью бесплатно, включая коммерческое использование. Medusa Inc также предлагает управляемое облако (Medusa Cloud) от $299/месяц — для тех кто не хочет самостоятельно обслуживать инфраструктуру. Self-hosted на VPS не стоит ничего кроме хостинга.
Нужен ли отдельный фронтенд? Да. Medusa предоставляет API и административный дашборд, но витрины для покупателей из коробки нет. Официальный Next.js Starter Storefront можно установить при создании проекта — это готовая витрина которую подключаете к своему Medusa бэкенду.
Чем Medusa отличается от Vendure? Оба — Node.js/TypeScript платформы с API-first подходом. Medusa активнее позиционируется как Shopify-замена и имеет более зрелую поддержку мультирегионов, сложных промо-механик и управления запасами. Vendure построен на NestJS и GraphQL, Medusa — REST API с опциональным GraphQL. У Medusa 20,000+ звёзд на GitHub против менее активного комьюнити Vendure — экосистема плагинов шире.
Работает ли с любым платёжным провайдером? Да. Medusa поддерживает Stripe, PayPal, Klarna, Mollie, Braintree и другие через официальные и community плагины. Плюс можно написать свой провайдер под любую платёжную систему — API открытый.
Можно ли мигрировать с Shopify на Medusa? Технически да — через импорт продуктов, клиентов и заказов в PostgreSQL. Официального автоматического мигратора нет, но сообщество поддерживает несколько инструментов. Сложность миграции зависит от количества кастомизаций в Shopify.
Полезные ссылки THE.Hosting:
- VPS в Германии (Франкфурт)
- VPS в Нидерландах (Меппел)
- VPS в США (Нью-Джерси)
- VPS в Японии (Токио)
- Dedicated Servers
- База знаний
Ресурсы Medusa: