asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: added Docker local installation guide (#13022)

Browse Source 
* docs: added Docker local installation guide

* fixes
This commit is contained in:
Shahed Nasser
2025-07-23 19:00:38 +03:00
committed by GitHub
parent bf4b6c80d2
commit c71ace0be2
10 changed files with 884 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

416
www/apps/book/public/llms-full.txt
View File

@@ -1087,7 +1087,7 @@ The `baseUrl` option sets the base directory to `src/admin`, and the `paths` opt
Next, update the `vite` configuration in `medusa-config.ts` to include the `resolve.alias` configuration:
```ts title="medusa-config.ts"
import path from 'path'
import path from "path"
module.exports = defineConfig({
// ...
@@ -1135,7 +1135,7 @@ For example, if you set the `@/*` alias to point to `./components/*`:
Then, the `vite` alias configuration would be:
```ts title="medusa-config.ts"
import path from 'path'
import path from "path"
module.exports = defineConfig({
// ...
@@ -4681,7 +4681,7 @@ moduleIntegrationTestRunner<BlogModuleService>({
moduleModels: [Post],
resolve: "./src/modules/blog",
injectedDependencies: {
[Modules.EVENT_BUS]: new MockEventBusService()
[Modules.EVENT_BUS]: new MockEventBusService(),
},
testSuite: ({ service }) => {
describe("BlogModuleService", () => {
@@ -4757,7 +4757,7 @@ module.exports = {
{
jsc: {
parser: { syntax: "typescript", decorators: true },
target: "es2021"
target: "es2021",
},
},
],
@@ -9636,10 +9636,10 @@ You can create data migration scripts in a TypeScript or JavaScript file under t
For example, to create a data migration script for the Blog Module example, create the file `src/migration-scripts/migrate-blog-data.ts` with the following content:
```ts title="src/migration-scripts/migrate-blog-data.ts" highlights={dataMigrationHighlights}
import { MedusaModule } from "@medusajs/framework/modules-sdk";
import { ExecArgs } from "@medusajs/framework/types";
import { BLOG_MODULE } from "../modules/blog";
import { createWorkflow } from "@medusajs/framework/workflows-sdk";
import { MedusaModule } from "@medusajs/framework/modules-sdk"
import { ExecArgs } from "@medusajs/framework/types"
import { BLOG_MODULE } from "../modules/blog"
import { createWorkflow } from "@medusajs/framework/workflows-sdk"
export default async function migrateBlogData({ container }: ExecArgs) {
// Check that the blog module exists
@@ -18780,6 +18780,404 @@ This step's executions fail if they run longer than two seconds.
A step’s timeout error is returned in the `errors` property of the workflow’s execution, as explained in [this chapter](https://docs.medusajs.com/learn/fundamentals/workflows/errors/index.html.md). The error’s name is `TransactionStepTimeoutError`.
# Install Medusa with Docker
In this chapter, you'll learn how to install and run a Medusa application using Docker.
The main supported installation method is using [create-medusa-app](https://docs.medusajs.com/learn/installation/index.html.md). However, since it requires prerequisites like PostgreSQL, Docker may be a preferred and easier option for some users. You can follow this guide to set up a Medusa application with Docker in this case.
You can follow this guide on any operating system that supports Docker, including Windows, macOS, and Linux.
### Prerequisites
- [Docker](https://docs.docker.com/get-docker/)
- [Docker Compose](https://docs.docker.com/compose/install/)
- [Git CLI tool](https://git-scm.com/downloads)
## 1. Clone Medusa Starter Repository
To get started, clone the Medusa Starter repository that a Medusa application is based on:
```bash
git clone https://github.com/medusajs/medusa-starter-default.git --depth=1 my-medusa-store
```
This command clones the repository into a directory named `my-medusa-store`.
***
## 2. Create `docker-compose.yml`
In the cloned repository, create a file named `docker-compose.yml` with the following content:
```yaml title="docker-compose.yml"
services:
# PostgreSQL Database
postgres:
image: postgres:15-alpine
container_name: medusa_postgres
restart: unless-stopped
environment:
POSTGRES_DB: medusa-store
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
ports:
- "5432:5432"
volumes:
- postgres_data:/var/lib/postgresql/data
networks:
- medusa_network
# Redis
redis:
image: redis:7-alpine
container_name: medusa_redis
restart: unless-stopped
ports:
- "6379:6379"
networks:
- medusa_network
# Medusa Server
# This service runs the Medusa backend application
# and the admin dashboard.
medusa:
build: .
container_name: medusa_backend
restart: unless-stopped
depends_on:
- postgres
- redis
ports:
- "9000:9000"
environment:
- NODE_ENV=development
- DATABASE_URL=postgres://postgres:postgres@postgres:5432/medusa-store
- REDIS_URL=redis://redis:6379
env_file:
- .env
volumes:
- .:/app
- /app/node_modules
networks:
- medusa_network
volumes:
postgres_data:
networks:
medusa_network:
driver: bridge
```
You define three services in this file:
- `postgres`: The PostgreSQL database service that stores your Medusa application's data.
- `redis`: The Redis service that stores session data.
- `medusa`: The Medusa service that runs the server and the admin dashboard. It connects to the PostgreSQL and Redis services.
You can add environment variables either in the `environment` section of the `medusa` service or in a separate `.env` file.
### Recommendations for Multiple Local Projects
If this isn't the first Medusa project you're setting up with Docker on your machine, make sure to:
- Change the `container_name` for each service to avoid conflicts.
- For example, use `medusa_postgres_myproject`, `medusa_redis_myproject`, and `medusa_backend_myproject` instead of the current names.
- Change the volume names to avoid conflicts.
- For example, use `postgres_data_myproject` instead of `postgres_data`.
- Change the network name to avoid conflicts.
- For example, use `medusa_network_myproject` instead of `medusa_network`.
- Change the ports to avoid conflicts with other projects. For example:
- Use `"5433:5432"` for PostgreSQL.
- Use `"6380:6379"` for Redis.
- Use `"9001:9000"` for the Medusa server.
- Update the `DATABASE_URL` and `REDIS_URL` environment variables accordingly.
***
## 3. Create `start.sh`
Next, you need to create a script file that [runs database migrations](https://docs.medusajs.com/learn/fundamentals/data-models/write-migration/index.html.md) and starts the Medusa development server.
Create the file `start.sh` with the following content:
### Yarn
```shell title="start.sh"
#!/bin/sh
# Run migrations and start server
echo "Running database migrations..."
npx medusa db:migrate
echo "Seeding database..."
yarn seed || echo "Seeding failed, continuing..."
echo "Starting Medusa development server..."
yarn dev
```
### NPM
```shell title="start.sh"
#!/bin/sh
# Run migrations and start server
echo "Running database migrations..."
npx medusa db:migrate
echo "Seeding database..."
npm run seed || echo "Seeding failed, continuing..."
echo "Starting Medusa development server..."
npm run dev
```
Make sure to give the script executable permissions:
Setting permissions isn't necessary on Windows, but it's recommended to run this command on Unix-based systems like macOS and Linux.
```bash
chmod +x start.sh
```
***
## 4. Create `Dockerfile`
The `Dockerfile` defines how the Medusa service is built.
Create a file named `Dockerfile` with the following content:
### Yarn
```dockerfile title="Dockerfile"
# Development Dockerfile for Medusa
FROM node:20-alpine
# Set working directory
WORKDIR /server
# Copy package files and yarn config
COPY package.json yarn.lock .yarnrc.yml ./
# Install all dependencies using yarn
RUN yarn install
# Copy source code
COPY . .
# Expose the port Medusa runs on
EXPOSE 9000
# Start with migrations and then the development server
CMD ["./start.sh"]
```
### NPM
```dockerfile title="Dockerfile"
# Development Dockerfile for Medusa
FROM node:20-alpine
# Set working directory
WORKDIR /server
# Copy package files and npm config
COPY package.json package-lock.json ./
# Install all dependencies using npm
RUN npm install
# Copy source code
COPY . .
# Expose the port Medusa runs on
EXPOSE 9000
# Start with migrations and then the development server
CMD ["./start.sh"]
```
In the `Dockerfile`, you use the `node:20-alpine` image as the base since Medusa requires Node.js v20 or later.
Then, you set the working directory to `/server`, copy the necessary files, install dependencies, expose the `9000` port that Medusa uses, and run the `start.sh` script to start the server.
While it's more common to use `/app` as the working directory, it's highly recommended to use `/server` for the Medusa service to avoid conflicts with Medusa Admin customizations. Learn more in [this troubleshooting guide](https://docs.medusajs.com/resources/troubleshooting/medusa-admin/no-widget-route#errors-in-docker/index.html.md).
***
## 5. Install Dependencies
The Medusa Starter repository has a `yarn.lock` file that was generated by installing dependencies with Yarn v1.22.19.
If you're using a different Yarn version, or you're using NPM, you need to install the dependencies again to ensure compatibility with the Docker setup.
To install the dependencies, run the following command:
```bash npm2yarn
npm install
```
This will update `yarn.lock` or generate a `package-lock.json` file, depending on your package manager.
***
## 6. Update Scripts in `package.json`
Next, you need to update the `scripts` section in your `package.json` file to start the development server using Docker.
Add the following scripts in `package.json`:
```json title="package.json"
{
"scripts": {
// Other scripts...
"docker:up": "docker compose up --build -d",
"docker:down": "docker compose down"
}
}
```
Where:
- `docker:up` starts the development server in a Docker container as a background process.
- `docker:down` stops and removes the Docker containers.
***
## 7. Update Medusa Configuration
If you try to run the Medusa application now with Docker, you'll encounter an SSL error as the server tries to connect to the PostgreSQL database.
To resolve the error, add the following configurations in `medusa-config.ts`:
```ts title="medusa-config.ts"
import { loadEnv, defineConfig } from "@medusajs/framework/utils"
loadEnv(process.env.NODE_ENV || "development", process.cwd())
module.exports = defineConfig({
projectConfig: {
// ...
databaseDriverOptions: {
ssl: false,
sslmode: "disable",
},
},
})
```
You add the [projectConfig.databaseDriverOptions](https://docs.medusajs.com/learn/configurations/medusa-config#databasedriveroptions/index.html.md) to disable SSL for the PostgreSQL database connection.
***
## 8. Add `.dockerignore`
To ensure only the necessary files are copied into the Docker image, create a `.dockerignore` file with the following content:
```dockerignore title=".dockerignore"
node_modules
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.git
.gitignore
README.md
.env.test
.nyc_output
coverage
.DS_Store
*.log
dist
build
```
***
## 9. Create `.env` File
You can add environment variables either in the `environment` section of the `medusa` service in `docker-compose.yml` or in a separate `.env` file.
If you don't want to use a `.env` file, you can remove the `env_file` section from the `medusa` service in `docker-compose.yml`.
Otherwise, copy the `.env.template` file to `.env` and update the values as needed.
***
## 10. Start the Medusa Application with Docker
All configurations are now ready. You can start the Medusa application using Docker by running the following command:
```bash npm2yarn
npm run docker:up
```
Docker will pull the necessary images, start the PostgreSQL and Redis services, build the Medusa service, and run the development server in a Docker container.
You can check the logs to ensure everything is running smoothly with the following command:
```bash
docker compose logs -f
```
Once you see the following message, the Medusa server and admin are ready:
```shell
✔ Server is ready on port: 9000 – 3ms
info: Admin URL → http://localhost:9000/app
```
You can now access the Medusa server at `http://localhost:9000` and the Medusa admin dashboard at `http://localhost:9000/app`.
***
## Create Admin User
To create an admin user, run the following command:
```bash
docker compose run --rm medusa npx medusa user -e admin@example.com -p supersecret
```
Make sure to replace `admin@example.com` and `supersecret` with your desired email and password.
You can now log in to the Medusa admin dashboard at `http://localhost:9000/app` using the email and password you just created.
***
## Stop the Medusa Application Running in Docker
To stop the Medusa application running in Docker, run the following command:
```bash npm2yarn
npm run docker:down
```
This command stops and removes the Docker containers created by the `docker-compose.yml` file.
This doesn't delete any data in your application or its database. You can start the server again using the `docker:up` command.
***
## Check Logs
You can check the logs of the Medusa application running in Docker using the following command:
```bash
docker compose logs -f medusa
```
This command shows the logs of the `medusa` service, allowing you to see any errors or messages from the Medusa application.
***
## 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).
# Install Medusa
In this chapter, you'll learn how to install and run a Medusa application.
@@ -18788,6 +19186,8 @@ In this chapter, you'll learn how to install and run a Medusa application.
A Medusa application is made up of a Node.js server and an admin dashboard. You can optionally install the [Next.js Starter Storefront](https://docs.medusajs.com/resources/nextjs-starter/index.html.md) separately either while installing the Medusa application or at a later point.
While this is the recommended way to create a Medusa application, you can alternatively [install a Medusa application with Docker](https://docs.medusajs.com/learn/installation/docker/index.html.md).
### Prerequisites
- [Node.js v20+](https://nodejs.org/en/download)