docs: fixes to docker installation guide (#13847)

* docs: fixes to docker installation guide * more fixes * re-organize troubleshooting * add title
2025-10-24 12:18:36 +03:00
parent 7c31276f98
commit 1d3231d37a
3 changed files with 155 additions and 11 deletions
--- a/www/apps/book/app/learn/installation/docker/page.mdx
+++ b/www/apps/book/app/learn/installation/docker/page.mdx
@@ -43,6 +43,14 @@ git clone https://github.com/medusajs/medusa-starter-default.git --depth=1 my-me

 This command clones the repository into a directory named `my-medusa-store`.

+Make sure to change into the newly created directory:
+
+```bash
+cd my-medusa-store
+```
+
+The rest of the steps will be performed inside this directory.
+
 ---

 ## 2. Create `docker-compose.yml`
@@ -96,8 +104,8 @@ services:
    env_file:
      - .env
    volumes:
-      - .:/app
-      - /app/node_modules
+      - .:/server
+      - /server/node_modules
    networks:
      - medusa_network

@@ -238,7 +246,7 @@ WORKDIR /server
 COPY package.json package-lock.json ./

 # Install all dependencies using npm
-RUN npm install
+RUN npm install --legacy-peer-deps

 # Copy source code
 COPY . .
@@ -272,10 +280,30 @@ If you're using a different Yarn version, or you're using NPM, you need to insta

 To install the dependencies, run the following command:

-```bash npm2yarn
-npm install
+<CodeTabs group="npm2yarn">
+  <CodeTab value="npm" label="npm">
+
+```bash
+npm install --legacy-peer-deps
 ```

+  </CodeTab>
+  <CodeTab value="yarn" label="yarn">
+
+```bash
+yarn install
+```
+
+  </CodeTab>
+  <CodeTab value="pnpm" label="pnpm">
+
+```bash
+pnpm install
+```
+
+  </CodeTab>
+</CodeTabs>
+
 This will update `yarn.lock` or generate a `package-lock.json` file, depending on your package manager.

 ---
@@ -437,6 +465,53 @@ This command shows the logs of the `medusa` service, allowing you to see any err

 ---

+## Troubleshooting
+
+### start.sh Not Found Error
+
+If you get the following error when starting the Medusa application with Docker:
+
+```bash
+medusa_backend exited with code 127 (restarting)
+medusa_backend   | /usr/local/bin/docker-entrypoint.sh: exec: line 11: ./start.sh: not found
+```
+
+This is a common error for Windows users. It usually occurs when the `start.sh` file uses CRLF line endings instead of LF.
+
+To fix this, ensure that the `start.sh` file uses LF line endings. You can configure Git to maintain LF line endings by following [this guide from GitHub](https://docs.github.com/en/get-started/git-basics/configuring-git-to-handle-line-endings).
+
+### Couldn't Find X File or Directory Errors
+
+If you encounter errors indicating that certain files or directories couldn't be found, make sure you're running the commands from the root directory of your Medusa application (the same directory where the `docker-compose.yml` file is located).
+
+For example, if you run the `docker:up` command and see an error like this:
+
+```bash
+error Couldn't find a package.json file in "/"
+```
+
+Ensure that your terminal's current working directory is the root of your Medusa application, then try running the command again.
+
+### Container Name Conflicts
+
+If you're running multiple Medusa projects with Docker or have previously run this guide, you may encounter container name conflicts.
+
+To resolve this, ensure that the `container_name` values in your `docker-compose.yml` file are unique for each project. You can modify them by appending a unique identifier to each name.
+
+For example, change:
+
+```yaml title="docker-compose.yml"
+container_name: medusa_postgres
+```
+
+to
+
+```yaml title="docker-compose.yml"
+container_name: medusa_postgres_myproject
+```
+
+---
+
 ## Learn More about your Medusa Application

 You can learn more about your Medusa application and its setup in the [Installation chapter](../page.mdx).
--- a/www/apps/book/generated/edit-dates.mjs
+++ b/www/apps/book/generated/edit-dates.mjs
@@ -123,7 +123,7 @@ export const generatedEditDates = {
  "app/learn/fundamentals/module-links/index/page.mdx": "2025-05-23T07:57:58.958Z",
  "app/learn/fundamentals/module-links/index-module/page.mdx": "2025-10-01T06:07:40.436Z",
  "app/learn/introduction/build-with-llms-ai/page.mdx": "2025-10-02T15:10:49.394Z",
-  "app/learn/installation/docker/page.mdx": "2025-07-23T15:34:18.530Z",
+  "app/learn/installation/docker/page.mdx": "2025-10-24T08:53:46.445Z",
  "app/learn/fundamentals/generated-types/page.mdx": "2025-07-25T13:17:35.319Z",
  "app/learn/introduction/from-v1-to-v2/page.mdx": "2025-09-29T15:33:38.811Z",
  "app/learn/debugging-and-testing/debug-workflows/page.mdx": "2025-07-30T13:45:14.117Z",
--- a/www/apps/book/public/llms-full.txt
+++ b/www/apps/book/public/llms-full.txt
@@ -22864,6 +22864,14 @@ git clone https://github.com/medusajs/medusa-starter-default.git --depth=1 my-me

 This command clones the repository into a directory named `my-medusa-store`.

+Make sure to change into the newly created directory:
+
+```bash
+cd my-medusa-store
+```
+
+The rest of the steps will be performed inside this directory.
+
 ***

 ## 2. Create `docker-compose.yml`
@@ -22917,8 +22925,8 @@ services:
    env_file:
      - .env
    volumes:
-      - .:/app
-      - /app/node_modules
+      - .:/server
+      - /server/node_modules
    networks:
      - medusa_network

@@ -23050,7 +23058,7 @@ WORKDIR /server
 COPY package.json package-lock.json ./

 # Install all dependencies using npm
-RUN npm install
+RUN npm install --legacy-peer-deps

 # Copy source code
 COPY . .
@@ -23078,8 +23086,22 @@ If you're using a different Yarn version, or you're using NPM, you need to insta

 To install the dependencies, run the following command:

-```bash npm2yarn
-npm install
+### npm
+
+```bash
+npm install --legacy-peer-deps
+```
+
+### yarn
+
+```bash
+yarn install
+```
+
+### pnpm
+
+```bash
+pnpm install
 ```

 This will update `yarn.lock` or generate a `package-lock.json` file, depending on your package manager.
@@ -23235,6 +23257,53 @@ This command shows the logs of the `medusa` service, allowing you to see any err

 ***

+## Troubleshooting
+
+### start.sh Not Found Error
+
+If you get the following error when starting the Medusa application with Docker:
+
+```bash
+medusa_backend exited with code 127 (restarting)
+medusa_backend   | /usr/local/bin/docker-entrypoint.sh: exec: line 11: ./start.sh: not found
+```
+
+This is a common error for Windows users. It usually occurs when the `start.sh` file uses CRLF line endings instead of LF.
+
+To fix this, ensure that the `start.sh` file uses LF line endings. You can configure Git to maintain LF line endings by following [this guide from GitHub](https://docs.github.com/en/get-started/git-basics/configuring-git-to-handle-line-endings).
+
+### Couldn't Find X File or Directory Errors
+
+If you encounter errors indicating that certain files or directories couldn't be found, make sure you're running the commands from the root directory of your Medusa application (the same directory where the `docker-compose.yml` file is located).
+
+For example, if you run the `docker:up` command and see an error like this:
+
+```bash
+error Couldn't find a package.json file in "/"
+```
+
+Ensure that your terminal's current working directory is the root of your Medusa application, then try running the command again.
+
+### Container Name Conflicts
+
+If you're running multiple Medusa projects with Docker or have previously run this guide, you may encounter container name conflicts.
+
+To resolve this, ensure that the `container_name` values in your `docker-compose.yml` file are unique for each project. You can modify them by appending a unique identifier to each name.
+
+For example, change:
+
+```yaml title="docker-compose.yml"
+container_name: medusa_postgres
+```
+
+to
+
+```yaml title="docker-compose.yml"
+container_name: medusa_postgres_myproject
+```
+
+***
+
 ## Learn More about your Medusa Application

 You can learn more about your Medusa application and its setup in the [Installation chapter](https://docs.medusajs.com/learn/installation/index.html.md).