Medusa.js Self-Hosted: Guia Completo de Instalação

O mercado de e-commerce moderno exige velocidade, flexibilidade e escalabilidade. A arquitetura headless tem se destacado como a solução preferida para marcas que buscam desacoplar o frontend do backend, permitindo experiências personalizadas em múltiplos canais sem comprometer a lógica de negócios por trás das cortinas. O Medusa.js emerge nesse cenário como a alternativa open-source mais robusta ao Shopify, oferecendo uma base sólida para desenvolvedores que preferem manter o controle total sobre sua infraestrutura.

Neste tutorial técnico, vamos detalhar o processo completo de instalação e configuração do Medusa.js em um ambiente self-hosted (hospedagem própria). O foco é a implementação em uma VPS (Virtual Private Server), garantindo que você tenha uma loja online escalável pronta para produção. Abordaremos desde o provisionamento do servidor até o deploy final, utilizando ferramentas essenciais como Node.js, PostgreSQL e Redis.

Pré-requisitos de Infraestrutura

Antes de iniciar a instalação do Medusa.js self-hosted, é fundamental garantir que o ambiente de servidores esteja preparado. A arquitetura headless do Medusa depende fortemente de serviços assíncronos e persistência de dados eficiente. Recomenda-se o uso de uma distribuição Linux moderna, como Ubuntu 22.04 LTS ou Debian 12, em sua VPS.

Os requisitos mínimos de hardware para um ambiente de desenvolvimento leve são 2 vCPUs e 4GB de RAM. Para produção, considere escalar horizontalmente os componentes ou utilizar uma instância maior com pelo menos 4GB a 8GB de RAM para evitar gargalos no processamento de filas de jobs via Redis.

Você precisará ter acesso SSH root ou um usuário com privilégios sudo configurado. Além disso, certifique-se de que o firewall da VPS esteja permitindo conexões na porta 22 (SSH), 80 (HTTP) e 443 (HTTPS). Se você planeja usar um proxy reverso como Nginx ou Traefik posteriormente, essas portas serão cruciais.

Instalação das Dependências do Sistema

O primeiro passo técnico consiste em atualizar o sistema operacional e instalar as ferramentas necessárias para rodar o ambiente Node.js e os bancos de dados. Abra seu terminal e conecte-se à sua VPS via SSH.

sudo apt update
sudo apt upgrade -y

Agora, vamos instalar o NVM (Node Version Manager). Esta é a prática recomendada para gerenciar versões do Node.js sem conflitar com pacotes do sistema. O NVM permite alternar entre versões facilmente e isolar dependências por projeto.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

Após a instalação, recarregue as variáveis de ambiente do seu shell:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm

Instale a versão LTS (Long Term Support) do Node.js, que é a mais estável para ambientes de produção:

nvm install --lts

Verifique as versões instaladas para garantir que tudo ocorreu conforme o esperado:

node -v
npm -v

Configuração do Banco de Dados e Cache

O Medusa.js utiliza PostgreSQL como banco de dados relacional principal e Redis para gerenciamento de filas de jobs e cache. Vamos instalar ambos os serviços.

Instale o PostgreSQL:

sudo apt install postgresql postgresql-contrib -y

Inicie o serviço e garanta que ele esteja ativo no boot do sistema:

sudo systemctl enable postgresql
sudo systemctl start postgresql

Agora, instale o Redis:

sudo apt install redis-server -y

Habilite e inicie o serviço do Redis:

sudo systemctl enable redis-server
sudo systemctl start redis-server

Com os serviços rodando, precisamos criar um usuário específico para o Medusa no PostgreSQL. Isso segue o princípio de menor privilégio. Acesse o shell do PostgreSQL como o usuário padrão do sistema:

sudo -u postgres psql

Dentro do prompt SQL, execute os comandos abaixo para criar um banco de dados e um usuário seguro:

CREATE USER medusa WITH PASSWORD 'senha_forte_aqui';
CREATE DATABASE medusa_db OWNER medusa;
GRANT ALL PRIVILEGES ON DATABASE medusa_db TO medusa;

Substitua senha_forte_aqui por uma senha complexa gerada aleatoriamente. Saia do prompt SQL digitando \q.

Criação do Projeto Medusa

Com o ambiente de sistemas pronto, vamos criar a estrutura do projeto. Navegue até o diretório onde deseja hospedar sua aplicação e utilize a CLI oficial do Medusa para iniciar o projeto.

cd /var/www
npm init medusa@latest

O assistente interativo fará algumas perguntas. Certifique-se de responder corretamente:

• Project name: Escolha um nome para seu projeto (ex: minha-loja-medusa).
• Database type: Selecione PostgreSQL.
• Database url: Forneça a conexão no formato postgresql://medusa:senha_forte_aqui@localhost:5432/medusa_db.
• Redis URL: Use redis://localhost:6379.

A CLI irá baixar todas as dependências, configurar o arquivo .env e criar a estrutura de pastas necessária. Aguarde a conclusão do processo.

Migração do Banco de Dados

O próximo passo crítico é aplicar as migrations que criam as tabelas necessárias no PostgreSQL (produtos, pedidos, clientes, etc.). Navegue até o diretório do projeto criado:

cd minha-loja-medusa

Execute a migração:

npx medusa db migrate

Se tudo estiver configurado corretamente, você verá mensagens de sucesso indicando que as tabelas foram criadas. Em seguida, populamos o banco com dados iniciais essenciais, como tipos de preço e regiões de envio:

npx medusa db seed

Agora, inicie o servidor backend em modo desenvolvimento para verificar se a aplicação está funcionando:

npm run build
npx medusa start

O servidor deve iniciar e ficar escutando na porta 9000. Você pode testar a API acessando http://localhost:9000/store/products em seu navegador ou via curl. Se retornar um JSON com os produtos seedados, o backend está operante.

Hospedagem do Frontend (Storefront)

A grande vantagem da arquitetura headless é a liberdade para criar interfaces personalizadas. O Medusa oferece um boilerplate chamado medusa storefront, baseado em Next.js, que serve como ponto de partida ideal.

Crie uma nova pasta para o frontend:

mkdir ../medusa-storefront && cd ../medusa-storefront

Inicie a criação do projeto storefront:

npx create-medusa-app@latest

Durante a configuração, forneça a URL da API do backend que você acabou de configurar (ex: http://localhost:9000). Este frontend será responsável por renderizar as páginas da loja, carrinho e checkout.

Instale as dependências e construa o projeto:

npm install
npm run build

Configuração de Produção e PM2

Para colocar a loja online escalável em produção, não devemos usar os scripts de desenvolvimento. Precisamos de um gerenciador de processos para manter o Node.js rodando mesmo após reinicializações do servidor ou crashes inesperados. O PM2 é a ferramenta padrão da indústria para isso.

Instale o PM2 globalmente:

sudo npm install -g pm2

No diretório do backend (/var/www/minha-loja-medusa), inicie o serviço com o PM2:

pm2 start "npm run start" --name medusa-backend

No diretório do frontend (/var/www/medusa-storefront), inicie a aplicação Next.js:

pm2 start "npm run start" --name medusa-storefront

Salve a lista de processos para iniciar automaticamente caso a VPS reinicie:

pm2 save
pm2 startup

O PM2 exibirá as portas em que cada serviço está rodando. O backend geralmente fica na 9000 e o frontend, dependendo da configuração do Next.js, pode ficar na 3000.

Proxy Reverso com Nginx

Expor portas diretas como 9000 ou 3000 não é uma prática recomendada para produção. Utilize o Nginx como um proxy reverso para gerenciar o tráfego, oferecer suporte a SSL (HTTPS) e melhorar o desempenho.

Instale o Nginx:

sudo apt install nginx -y

Crie um arquivo de configuração no diretório /etc/nginx/sites-available/medusa.conf. O conteúdo deve direcionar requisições para a API do backend e as rotas da loja para o frontend.

server {
    listen 80;
    server_name seu-dominio.com www.seu-dominio.com;

    # Proxy para a API do Medusa Backend
    location /api/ {
        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_cache_bypass $http_upgrade;
    }

    # Proxy para o Frontend Next.js
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Ative a configuração criando um link simbólico e reinicie o Nginx:

sudo ln -s /etc/nginx/sites-available/medusa.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

Segurança e SSL com Let's Encrypt

Para garantir que sua loja online escalável seja segura e confiável, instale certificados SSL gratuitos utilizando o Certbot.

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d seu-dominio.com -d www.seu-dominio.com

O assistente do Certbot irá modificar automaticamente a configuração do Nginx para forçar o HTTPS e configurar o renovação automática dos certificados. Isso é essencial para SEO e confiança do usuário.

Melhores Práticas para Escalabilidade

Ao operar um servidor proprio ecommerce com Medusa.js, considere os seguintes pontos para manter a performance:

• Monitoramento de Logs: Utilize ferramentas como PM2 monitor ou elasticsearch para acompanhar erros em tempo real. O comando pm2 logs medusa-backend é vital para debugging.
• Otimização de Imagens: Configure um serviço de CDN ou use o plugin de armazenamento do Medusa (como AWS S3 ou Cloudinary) para servir imagens de produtos, reduzindo a carga na VPS.
• Jobs Assíncronos: Em cenários de alto tráfego, considere separar o processamento de filas (Redis/BullMQ) em um nó dedicado para não bloquear a API principal durante picos de vendas.
• Backups Automáticos: Implemente scripts cron para backup diário do banco de dados PostgreSQL e do código fonte.

A instalação do Medusa.js self-hosted em uma VPS oferece um controle sem precedentes sobre sua stack tecnológica. Ao contrário de plataformas SaaS fechadas, você pode otimizar cada camada, desde o kernel do Linux até a lógica de negócio em Node.js. Embora exija mais esforço inicial de configuração e manutenção operacional, a flexibilidade e a economia de custos a longo prazo tornam esta arquitetura headless uma escolha estratégica para negócios em crescimento.

Com a infraestrutura acima descrita, você possui um ambiente robusto pronto para receber integrações complexas, pagamentos personalizados e expansões globais. Lembre-se de atualizar regularmente as dependências do Node.js e os pacotes do Medusa para manter a segurança e aproveitar as novas features lançadas pela comunidade.