Medusa.js Self-Hosted: Guia Completo para VPS

A arquitetura e-commerce headless tem se tornado o padrão ouro para empresas que buscam escalabilidade, performance e flexibilidade no desenvolvimento de lojas virtuais. Diferente dos monolitos tradicionais, onde frontend e backend estão acoplados, o modelo headless separa a camada de apresentação da lógica de negócios, permitindo que a API de comércio eletrônico alimente múltiplos canais (web, mobile, IoT) simultaneamente.

Neste tutorial técnico, vamos detalhar como realizar o medusa.js self-hosted em um ambiente de VPS Linux otimizado. O Medusa é um framework Node.js open-source que atua como o "backend do e-commerce", oferecendo uma API robusta baseada em GraphQL e REST. Ao hospedar essa solução em sua própria infraestrutura, você assume o controle total dos dados, da segurança e da performance, eliminando as limitações de plataformas SaaS.

Pré-requisitos e Preparação do Ambiente

Antes de iniciar o deploy do Medusa, é fundamental garantir que a VPS atenda aos requisitos mínimos de hardware e software. Para um ambiente de produção estável, recomenda-se uma instância com pelo menos 2 vCPUs e 4GB de RAM. O sistema operacional deve ser uma distribuição Linux recente, como Ubuntu 22.04 LTS ou Debian 12.

O primeiro passo é atualizar o sistema operacional e instalar as dependências básicas do servidor. Acesse seu terminal via SSH com um usuário sudo:

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

Além das ferramentas de linha de comando, o Medusa depende fortemente do Node.js e do PostgreSQL. Para garantir a versão LTS (Long Term Support) mais recente do Node.js, utilize o gerenciador de versões nvm ou adicione o repositório oficial. Neste exemplo, utilizaremos o método via repositório para maior controle:

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

O banco de dados PostgreSQL é o motor de persistência do Medusa. Instale-o e inicie o serviço:

sudo apt install postgresql postgresql-contrib -y
sudo systemctl start postgresql
sudo systemctl enable postgresql

Criação do Banco de Dados e Usuário

O Medusa requer uma conexão estável com o banco de dados. Por questões de segurança, nunca utilize o usuário postgres padrão para a aplicação em produção. Crie um novo usuário e um banco de dados dedicado.

Acesse o shell do PostgreSQL:

sudo -u postgres psql

Dentro do prompt SQL, execute os comandos abaixo para criar o banco e o usuário com senha segura. Substitua medusa_user e strong_password por credenciais reais geradas em um gerenciador de senhas:

CREATE USER medusa_user WITH PASSWORD 'strong_password';
CREATE DATABASE medusa_db OWNER medusa_user;
\q

Verifique se a conexão está funcionando testando o acesso via linha de comando (opcional, mas recomendado para debug):

psql -U medusa_user -d medusa_db -h 127.0.0.1 -W

Inicialização do Projeto Medusa

Agora que a infraestrutura está pronta, vamos provisionar o código da aplicação. Utilizaremos a CLI oficial do Medusa para criar uma nova instância. Isso automatiza a configuração do Node.js ecommerce, instalando todas as dependências necessárias e gerando os arquivos de configuração padrão.

Navegue até o diretório onde deseja hospedar o projeto (ex: /var/www/medusa) e execute:

npm init medusa@latest

O assistente interativo fará as seguintes perguntas. Responda conforme indicado para um setup otimizado:

1. Select a starter: Escolha E-commerce Store (Medusa).
2. Project name: Defina o nome do projeto.
3. Database type: Selecione PostgreSQL.
4. Database URL: Insira a string de conexão: postgres://medusa_user:strong_password@localhost:5432/medusa_db.
5. Install dependencies: Selecione Yes para instalar o Yarn ou NPM automaticamente.

Aguarde a conclusão da instalação. O processo pode levar alguns minutos dependendo da velocidade da sua VPS otimizada e da largura de banda disponível.

Configuração do Ambiente (Environment Variables)

Após a criação do projeto, é crucial configurar as variáveis de ambiente para produção. O arquivo .env controla segredos, chaves de API e configurações de CORS. Copie o modelo existente:

cp .env.template .env

Edite o arquivo .env com seu editor de texto preferido (ex: vim .env) e ajuste as seguintes variáveis críticas:

• DATABASE_URL: Certifique-se de que está correta e segura.
• REDIS_URL: Para produção, instale o Redis para gerenciar filas e sessões. Instale com sudo apt install redis-server e defina a URL como redis://localhost:6379.
• JWT_SECRET e COOKIE_SECRET: Gere strings aleatórias complexas para estas variáveis. Elas protegem as sessões do usuário e os tokens de autenticação.
• ADMIN_CORS: Restrinja o domínio do painel administrativo para evitar ataques de cross-origin.

Para gerar segredos seguros, utilize comandos como:

openssl rand -hex 32

Migração do Banco de Dados e Seed

Com o código e as configurações prontos, é hora de estruturar o banco de dados. O Medusa utiliza um sistema de migrações para manter a schema atualizada.

npx medusa db:migrate

Em seguida, carregue dados de exemplo (seed) para testar a funcionalidade básica da loja, como produtos e categorias:

npx medusa seed -f ./data/seedOnboarding.json

Se o comando for executado com sucesso, você terá acesso ao painel administrativo do Medusa em http://seu-ip-do-servidor:9000/admin. O usuário padrão geralmente é admin@medusa-test.com e a senha é supersecret, mas isso pode variar dependendo da versão. Altere essas credenciais imediatamente após o primeiro login.

Habilitação do HTTPS com Let's Encrypt

Nunca exponha uma aplicação de e-commerce sem criptografia TLS. O uso de HTTPS é obrigatório para segurança de transações e SEO. Utilizaremos o Nginx como proxy reverso e o Certbot para obter certificados gratuitos.

Instale o Nginx e o Certbot:

sudo apt install nginx certbot python3-certbot-nginx -y

Crie um bloco de servidor no Nginx. Edite o arquivo /etc/nginx/sites-available/medusa:

server {
    listen 80;
    server_name seu-dominio.com www.seu-dominio.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_cache_bypass $http_upgrade;
    }
}

Habilite o site e teste a configuração:

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

Agora, obtenha o certificado SSL. Certbot configurará automaticamente o Nginx para redirecionar HTTP para HTTPS:

sudo certbot --nginx -d seu-dominio.com -d www.seu-dominio.com

Otimização de Performance e Segurança

Para um deploy medusa em produção, a configuração padrão não é suficiente. É necessário ajustar parâmetros do Node.js e do banco de dados para lidar com tráfego real.

Ajustes no PostgreSQL

O PostgreSQL vem configurado para ambientes desktop. Edite /etc/postgresql/15/main/postgresql.conf (o número da versão pode variar) e ajuste:

shared_buffers = 256MB
effective_cache_size = 1GB
work_mem = 4MB
maintenance_work_mem = 64MB

Reinicie o serviço para aplicar:

sudo systemctl restart postgresql

Ajustes no Node.js

O Node.js, por padrão, usa apenas um núcleo da CPU. Para melhorias de performance em VPS multi-core, utilize cluster mode ou ferramentas como PM2 para gerenciar processos e balancear a carga entre os núcleos disponíveis.

npm install -g pm2
pm2 start npm --name "medusa-api" -- start

O PM2 garante que a aplicação reinicie automaticamente em caso de falhas e permite monitoramento básico. Configure-o para iniciar no boot do sistema:

pm2 startup systemd
sudo env PATH=$PATH:/usr/bin pm2 dump medusa-api

Segurança com Firewall (UFW)

Habilite o firewall Uncomplicated Firewall para bloquear portas não essenciais. Libere apenas SSH, HTTP e HTTPS:

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable

Conclusão e Próximos Passos

A conclusão deste tutorial marca o fim da fase de infraestrutura básica. Você agora possui um ambiente medusa.js self-hosted rodando em uma VPS Linux, protegido por HTTPS, com banco de dados otimizado e gerenciador de processos ativo.

Os próximos passos para profissionalizar sua operação incluem:

1. Integração de Pagamentos: Configurar gateways como Stripe, Pagar.me ou Mercado Pago através dos plugins oficiais do Medusa.
2. Frontend Headless: Desenvolver ou integrar um storefront (como Next.js ou Gatsby) que consome a API criada aqui.
3. Backup Automatizado: Implementar scripts de backup diário para o banco PostgreSQL e para os uploads de mídia do servidor.
4. Monitoramento: Integrar ferramentas como Prometheus e Grafana ou Datadog para monitorar métricas de latência e uso de recursos.

Hospedar seu próprio backend de e-commerce oferece controle absoluto sobre a arquitetura ecommerce headless. Embora exija mais manutenção operacional do que soluções SaaS, a flexibilidade, segurança e custo-benefício a longo prazo tornam o Medusa uma escolha estratégica para negócios em crescimento.