Deploy Medusa on TurboStack

Run the Medusa Node.js headless commerce platform on TurboStack using the Nginx reverse-proxy pattern with PostgreSQL.

Medusa is a Node.js headless commerce platform. Unlike applications that have a dedicated app_type, Medusa is deployed with the reverse-proxy pattern: each Node.js service runs as its own process and Nginx proxies requests to it. This pattern applies to any Node.js or containerized application, not just Medusa, so you can use the same approach for custom Node apps, separate storefronts, and admin dashboards.

Requirements

Component Value
App type - (reverse proxy)
Runtime Node.js 20+ (LTS versions only)
Database PostgreSQL
Web server Nginx (reverse proxy)

Configure it

  1. Set webserver: nginx at the host level to provide the reverse proxy.
  2. Set postgresql_version to the PostgreSQL release Medusa should use (for example "18").
  3. For each service, add a vhost with a unique app_name, a nodejs_version, and cert_type: letsencrypt.
  4. Set proxy_enabled: true and proxy_upstream_port to the port the Node process listens on. Nginx will proxy public traffic to that port.
  5. Repeat for each service - for example a storefront on port 8000 and the Medusa backend/admin on port 9000.

See Applications for supported deployment patterns and Publish for how to apply your host configuration.

Example configuration

webserver: nginx
postgresql_version: "17"       # Medusa stores its data in PostgreSQL
system_users:
  - username: prod
    vhosts:
      - server_name: shop.example.com www.shop.example.com
        app_name: frontend
        nodejs_version: "24"      # Node.js runtime for the storefront
        cert_type: letsencrypt
        proxy_enabled: true        # nginx proxies to the Node process
        proxy_upstream_port: "8000"
      - server_name: dashboard.shop.example.com
        app_name: dashboard
        nodejs_version: "24"
        cert_type: letsencrypt
        proxy_enabled: true
        proxy_upstream_port: "9000"   # Medusa backend/admin

Why these choices

  • The reverse-proxy pattern (proxy_enabled + proxy_upstream_port) works for any Node.js or containerized application. You keep full control over the runtime, while Nginx handles Transport Layer Security (TLS) and routing.
  • A separate vhost per app_name lets the storefront and the backend/admin run as independent processes on their own ports and domains.
  • nodejs_version pins the Node.js runtime each service runs on.
  • postgresql_version is required because Medusa persists its data in PostgreSQL.
  • cert_type: letsencrypt issues and renews TLS certificates automatically for each domain.

© 2026 Hosted Power — TurboStack