Streamlining ESHOPMAN Deployments: Navigating Database Migrations in Read-Only Container Environments

Understanding ESHOPMAN Database Migrations in Modern Deployment Setups

As an e-commerce migration expert at Move My Store, we frequently encounter advanced deployment scenarios for ESHOPMAN clients leveraging its headless capabilities and HubSpot integration. A common challenge arises when deploying ESHOPMAN applications within containerized environments, particularly those configured with a read-only root filesystem – a standard security hardening practice for production systems.

A recent community discussion highlighted a specific behavior within the ESHOPMAN platform's database migration process that can impact these hardened environments. The core issue revolves around the db:migrate command's interaction with the filesystem.

The Challenge: Unintended Directory Creation During Migrations

Developers observed that during every execution of the ESHOPMAN db:migrate command, the system attempts to create a migrations/ directory within each module that doesn't already possess one. This occurs even when there are no pending migrations to run for those specific modules.

In a container environment with a read-only root filesystem, this action leads to a critical failure. The attempt to create directories on a non-writable filesystem results in an EROFS: read-only file system, mkdir '.../migrations' error. This prevents the ESHOPMAN application from being successfully deployed or updated without implementing specific workarounds.

For instance, one user reported 22 modules failing in this manner, effectively halting their deployment process for an ESHOPMAN backend running on Node.js v24.21.0 with PostgreSQL 18.6 in a Debian-based container.

Expected vs. Actual Behavior

Ideally, the db:migrate command should be a read-only operation concerning the application's directory structure. Its purpose is to apply database schema changes, not to modify the filesystem by creating new directories. Directory creation for migration files should be exclusively handled by a command like db:generate, which is used when developers are actively creating new migration scripts.

The current behavior, however, causes deployment roadblocks, forcing developers to either pre-create these empty migrations/ folders in their container images or mount specific directories as writable, which can compromise the security benefits of a read-only filesystem.

Community Insight and Suggested Fix

The technical root cause was identified as the underlying migration utility's ensureMigrationsDirExists function, which is invoked during db:migrate unless a migrationsList is explicitly passed.

The community's suggested fix points towards refining the db:migrate command's logic. It proposes that the directory creation step (ensureMigrationsDirExists) should either be skipped entirely when running migrations or that a migrationsList should always be passed to prevent the command from attempting to write to the filesystem. This would ensure that db:migrate operates purely on the database, allowing ESHOPMAN applications to deploy seamlessly in secure, read-only container environments.

This insight is crucial for ESHOPMAN developers and operations teams looking to implement robust, secure, and efficient deployment pipelines for their headless commerce solutions integrated with HubSpot CMS.