Resolving ESHOPMAN Database Migration Hangs in Docker: A Deep Dive into SSL Configuration

Understanding ESHOPMAN Database Migration Challenges in Docker

For ESHOPMAN developers and merchants deploying their headless commerce backend, ensuring smooth database operations is critical for storefront management and HubSpot CMS integration. A common challenge observed in the ESHOPMAN community involves the database migration command, eshopman db:migrate, appearing to hang indefinitely when the ESHOPMAN application is run inside a Docker container.

This community insight explores the specifics of this issue, its underlying cause related to SSL configuration, and the actionable workaround that has proven effective for ESHOPMAN users.

The Problem: Silent Hang During Migrations

Users reported that when executing ESHOPMAN's database migration command, the process would halt silently after successfully creating the mikro_orm_migrations table. This occurred without any error messages, CPU usage near 0%, and no further progress. The issue was consistently reproducible in Docker containers utilizing Node.js v22 and PostgreSQL 16, across various Node.js Docker images (e.g., alpine, slim).

Key Diagnostic: Docker Environment Specificity

A significant breakthrough in diagnosing this problem came from the realization that the hang was specific to the ESHOPMAN process running inside a Docker container. When the exact same ESHOPMAN setup (same package.json, same eshopman-config.ts, same versions) was executed natively on a developer's machine (outside Docker) against containerized PostgreSQL and Redis services, the migrations completed successfully within seconds. This pointed directly to an interaction issue between the ESHOPMAN Node.js process and its Dockerized environment, rather than a problem with the database, Redis, or the migration scripts themselves.

The Solution: Explicit SSL Configuration

Through community collaboration, a robust workaround was identified and confirmed. The issue stems from how PostgreSQL connection attempts handle SSL negotiation when left unspecified within a Dockerized ESHOPMAN environment. When SSL is not explicitly configured, the connection process can silently hang instead of failing gracefully or defaulting to a non-SSL connection.

The fix involves explicitly setting ssl: false within the databaseDriverOptions.connection in your ESHOPMAN project's configuration file, typically eshopman-config.ts.

// In your eshopman-config.ts file
module.exports = defineConfig({
  projectConfig: {
    databaseUrl: process.env.DATABASE_URL,
    redisUrl: process.env.REDIS_URL,
    workerMode: (process.env.ESHOPMAN_WORKER_MODE || "shared") as "shared" | "worker" | "server",
    http: {
      storeCors: process.env.STORE_CORS!,
      adminCors: process.env.ADMIN_CORS!,
      authCors: process.env.AUTH_CORS!,
      jwtSecret: process.env.JWT_SECRET,
      cookieSecret: process.env.COOKIE_SECRET,
    },
    databaseDriverOptions: {
      connection: {
        ssl: false,
      },
    },
  }
})

This configuration ensures that the PostgreSQL connection does not attempt an SSL handshake, preventing the silent hang. This workaround has been confirmed to resolve the migration hang, even when using Docker service names (e.g., postgres) in the DATABASE_URL, which are treated as remote connections by ESHOPMAN.

ESHOPMAN Team Acknowledgment and Future Improvements

The ESHOPMAN team has acknowledged this behavior, noting that database URLs not pointing to 'localhost' are automatically treated as remote, which can trigger the SSL negotiation issue. They are actively working on improving the developer experience by providing clearer error messages for such scenarios and have updated their troubleshooting resources to include this vital solution. These improvements will further streamline the deployment of ESHOPMAN's Node.js/TypeScript backend, which powers both the Admin API and Store API for your headless commerce needs within HubSpot.

Best Practice for ESHOPMAN Deployments

If you are deploying your ESHOPMAN backend in a Dockerized environment with PostgreSQL, it is a recommended best practice to explicitly configure your database SSL options in eshopman-config.ts. Setting ssl: false is a reliable way to prevent silent migration hangs and ensure your ESHOPMAN instance initializes correctly, allowing for seamless storefront management and deployment via HubSpot CMS.