Как установить и настроить Medusa на VPS

MAATRIX

Medusa — не готовый магазин с темой и корзиной из коробки, а движок под капотом: backend на Node.js, отдающий API, и отдельный фронтенд, который вы верстаете сами или берёте за основу стартер. Если вам нужен именно контроль над витриной — своя логика оформления заказа, нестандартная структура каталога, интеграция с внешними системами без борьбы с чужими шаблонами — Medusa на своём VPS даёт этот контроль. Дальше — пошагово: от чистого сервера до запущенного backend с админкой и подключённого фронтенда.

Что такое Medusa и когда она подходит

Medusa — open-source headless-платформа электронной коммерции на TypeScript/Node.js. «Headless» означает, что backend (управление товарами, заказами, ценами, скидками, платежами) полностью отделён от витрины: он отдаёт данные через REST/JSON API, а как их показывать покупателю — решаете вы. Из коробки в проект входят два основных слоя:

• Medusa backend — сервер с API, встроенной админ-панелью (доступна по адресу /app на том же порту) и модульной архитектурой: платежи, доставка, склад, скидки — каждый блок можно заменить своим модулем.
• Storefront — отдельное клиентское приложение. Официальный стартер собран на Next.js, но фронтенд может быть на чём угодно, если он умеет ходить в Medusa API.

Кому это подходит: командам, которым тесно в Shopify/Tilda-подобных конструкторах и нужна гибкость на уровне кода, а не только настроек темы. Кому не подходит: если нужен магазин «за вечер» без разработки — здесь придётся писать или адаптировать фронтенд, это не WordPress с плагином, где хватает установщика в браузере.

Технически Medusa ближе к PrestaShop как самостоятельной платформе, чем к WooCommerce-подходу — только вместо PHP-монолита с веб-установщиком у вас Node.js-сервис, который вы поднимаете руками через терминал.

Требования к серверу

Официальный минимум для Medusa скромный, но на практике для боевого проекта закладывайте запас — Node.js-процесс под API, PostgreSQL и (в проде) Redis работают одновременно на одной машине, если вы не разносите их по разным серверам.

Точные цифры зависят от размера каталога, трафика и того, сколько сервисов вы держите на одном VPS. Если ставите backend, storefront, PostgreSQL и Redis на одну машину — не экономьте на памяти, каждый из этих процессов держит своё резидентное потребление, и на 2 ГБ всё это будет постоянно упираться в своп.

Устанавливаем Node.js, PostgreSQL и Redis

Дальше — Ubuntu 24.04, но шаги переносятся на Debian почти без изменений.

Обновите систему и поставьте базовые пакеты:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git build-essential

Node.js ставим через NodeSource-репозиторий, а не из стандартных пакетов Ubuntu — там версия обычно старее, чем нужно Medusa:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
node -v
npm -v

PostgreSQL — из репозитория Ubuntu этого достаточно. Подробный разбор установки и первичной настройки PostgreSQL, если делаете это впервые, есть в отдельной статье про PostgreSQL на Ubuntu 24.04. Здесь — минимум для Medusa:

sudo apt install -y postgresql postgresql-contrib
sudo -u postgres psql

CREATE DATABASE medusa_store;
CREATE USER medusa_user WITH ENCRYPTED PASSWORD 'СЛОЖНЫЙ_ПАРОЛЬ';
GRANT ALL PRIVILEGES ON DATABASE medusa_store TO medusa_user;
\q

Redis для теста можно пропустить — Medusa в режиме разработки использует in-memory реализации очереди событий и кэша. Для продакшена ставьте его сразу, чтобы не переносить конфигурацию позже:

sudo apt install -y redis-server
sudo systemctl enable --now redis-server
redis-cli ping

Ответ PONG подтверждает, что Redis поднялся и слушает локально.

Создаём проект Medusa и настраиваем окружение

Официальный способ развернуть новый проект — CLI-инструмент create-medusa-app. Он спрашивает имя проекта, параметры подключения к базе и предлагает сразу поставить storefront-стартер:

cd /var/www
npx create-medusa-app@latest

CLI Medusa развивается быстро, и набор вопросов/флагов между релизами может отличаться — если запускаете без интерактивного диалога (например, в CI), сверьтесь с npx create-medusa-app@latest --help на актуальной версии, а не полагайтесь на флаги из старых мануалов.

После создания проекта зайдите в его папку и откройте .env — там уже будут базовые переменные, часть из них нужно проверить и дополнить под ваш сервер:

cd medusa-store
nano .env

Ключевые переменные:

DATABASE_URL=postgres://medusa_user:СЛОЖНЫЙ_ПАРОЛЬ@localhost:5432/medusa_store
REDIS_URL=redis://localhost:6379
JWT_SECRET=сгенерируйте_случайную_строку
COOKIE_SECRET=сгенерируйте_другую_случайную_строку
STORE_CORS=https://shop.example.com
ADMIN_CORS=https://admin.example.com
AUTH_CORS=https://shop.example.com,https://admin.example.com

Секреты для JWT_SECRET и COOKIE_SECRET не берите из головы — сгенерируйте случайно:

openssl rand -base64 32

STORE_CORS, ADMIN_CORS и AUTH_CORS — это не формальность, а реальная защита: без правильных значений браузер будет блокировать запросы фронтенда к API по политике CORS, и вы получите рабочий backend, который «не отвечает» из витрины.

Если планируете держать редакторов и загружаемые изображения товаров, для продакшена стоит сразу подумать про объектное хранилище вместо локального диска — иначе при переезде на другой сервер или при масштабировании на несколько инстансов backend файлы придётся переносить руками. Развернуть S3-совместимое хранилище на своём VPS можно через MinIO — как это сделать, разобрано в статье про установку MinIO на VPS.

Первый запуск: миграции и админ-пользователь

Прежде чем поднимать сервер, накатите миграции базы данных:

npx medusa db:migrate

Если команда падает с ошибкой подключения — почти всегда дело в DATABASE_URL: неверный пароль, порт или PostgreSQL слушает не на localhost, а на другом интерфейсе. Проверьте вручную подключение через psql с теми же учётными данными, прежде чем разбираться дальше.

Создайте первого администратора для входа в панель:

npx medusa user -e admin@example.com -p СЛОЖНЫЙ_ПАРОЛЬ

Запустите сервер в режиме разработки, чтобы убедиться, что всё поднимается:

npx medusa develop

По умолчанию backend слушает порт 9000. Админ-панель доступна на том же порту по пути /app — то есть http://ваш-сервер:9000/app. Если сервер поднялся и логин с созданным пользователем проходит — переходите к продакшен-запуску, dev-режим для боевой работы не годится: он не оптимизирован по производительности и пересобирает код на лету.

Продакшен: сборка, PM2 и автозапуск

Соберите продакшен-версию перед первым боевым стартом:

npx medusa build

Команда собирает и backend, и клиентскую часть админки. Дальше сервер запускается уже собранным билдом:

npx medusa start

Запускать так напрямую в терминале нельзя — процесс умрёт при отключении SSH-сессии. Используйте менеджер процессов; проще всего — PM2:

sudo npm install -g pm2
pm2 start npm --name medusa --cwd /var/www/medusa-store -- run start
pm2 save
pm2 startup

Последняя команда pm2 startup выведет строку с командой для конкретного вашего дистрибутива — её нужно выполнить отдельно от имени root, чтобы PM2 поднимал процессы автоматически после перезагрузки сервера.

Проверить, что процесс жив и не падает в цикле рестартов:

pm2 status
pm2 logs medusa

Если видите постоянные рестарты в pm2 status — почти всегда причина в .env: либо PostgreSQL/Redis недоступны на момент старта (например, сервисы ещё не поднялись после перезагрузки сервера), либо неверный порт уже занят другим процессом.

Nginx, домен, SSL и подключение сторфронта

Backend слушает 9000 только локально — наружу его лучше не выставлять напрямую, а завернуть через Nginx как обратный прокси с доменом и SSL. Общий принцип настройки обратного прокси на Nginx подробно разобран в статье про Nginx как reverse proxy на Ubuntu 24.04, здесь — конфиг именно под Medusa:

server {
    listen 80;
    server_name admin.example.com;

    location / {
        proxy_pass http://127.0.0.1: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;
    }
}

Заголовки Upgrade/Connection нужны, потому что Medusa admin использует не только обычные HTTP-запросы. После проверки конфига (sudo nginx -t) и перезагрузки Nginx выпустите сертификат — порядок действий с Let's Encrypt для домена расписан в статье про SSL от Let's Encrypt на VPS.

Storefront (например, официальный Next.js-стартер) — отдельное приложение, которое обычно поднимается на другом порту (по умолчанию у Next.js это 3000) и получает адрес backend через переменную окружения вида NEXT_PUBLIC_MEDUSA_BACKEND_URL=https://admin.example.com. Для него настраивается свой server-блок в Nginx с доменом витрины и своим SSL-сертификатом — по той же схеме обратного прокси, что и для backend, только на другой порт. Storefront можно развернуть на том же VPS, что и backend, если ресурсов хватает, либо вынести на отдельный сервер и обращаться к Medusa API по адресу вашего домена.

Частые вопросы