Skip to main content

Running Strapi in a Docker container

Page summary:

This page guides you through running Strapi in Docker containers for development and production environments, including Dockerfile examples, Docker Compose configurations, and troubleshooting common issues.

Caution

Strapi does not build any official container images. The following instructions are provided as a courtesy to the community. If you have any questions please reach out on Discord.

Containerizing Strapi makes the runtime environment reproducible across machines and simplifies dependency management for deployment. This page covers building custom Docker images for an existing Strapi 5 project, with separate instructions for development and production environments, a troubleshooting section, and a list of community tools. If you would rather not write your own Dockerfile, see Community tools and images for packaged alternatives.

Prerequisites

Development environment​

Development images use npm run develop and mount your local source code for hot-reload. Before creating the Dockerfile, set up 2 required files: .dockerignore and .env.

Create a .dockerignore file​

A .dockerignore file prevents local files from being copied into the Docker image. Without it, your local node_modules directory gets included in the build context, which causes architecture mismatches (e.g., x64 binaries on ARM) and increases the image size.

Create a .dockerignore file at the root of your Strapi project:

./.dockerignore
node_modules/
.tmp/
.cache/
.git/
build/
.env

Create the Dockerfile​

The following Dockerfile can be used to build a non-production Docker image for a Strapi project.

./Dockerfile
FROM node:22-alpine
# Installing libvips-dev for sharp compatibility
RUN apk update && apk add --no-cache build-base gcc autoconf automake zlib-dev libpng-dev bash vips-dev git
ARG NODE_ENV=development
ENV NODE_ENV=${NODE_ENV}

WORKDIR /opt/
COPY package.json package-lock.json ./
RUN npm install -g node-gyp
RUN npm config set fetch-retry-maxtimeout 600000 -g && npm ci
ENV PATH=/opt/node_modules/.bin:$PATH

WORKDIR /opt/app
COPY . .
RUN chown -R node:node /opt/app
USER node
EXPOSE 1337
CMD ["npm", "run", "develop"]
Optional: pre-build the admin panel

You can add RUN ["npm", "run", "build"] before the EXPOSE line to pre-build the admin panel and speed up the first start. This is not required since npm run develop rebuilds it in watch mode.

Alternative base image for restricted networks

If your CI environment has limited network access (e.g., DNS restrictions that prevent downloading Sharp prebuilt binaries from GitHub), consider using node:22-slim instead of node:22-alpine. The Debian-based slim image avoids the need to compile native dependencies like libvips from source, and Sharp's prebuilt binaries work out of the box:

FROM node:22-slim
RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*

This trades a slightly larger image for fewer build dependencies and fewer network requirements.

Set up environment variables​

Create a .env file at the root of your Strapi project. Docker Compose reads this file automatically when starting containers, so there is no need to export them in your shell.

The following environment variables are required in order to run Strapi in a Docker container:

Variable nameDescription
NODE_ENVThe environment in which the application is running.
DATABASE_CLIENTThe database client to use.
DATABASE_HOSTThe database host.
DATABASE_PORTThe database port.
DATABASE_NAMEThe database name.
DATABASE_USERNAMEThe database username.
DATABASE_PASSWORDThe database password.
JWT_SECRETThe secret used to sign the JWT for the Users-Permissions plugin.
ADMIN_JWT_SECRETThe secret used to sign the JWT for the Admin panel.
APP_KEYSThe secret keys used to sign the session cookies.
API_TOKEN_SALTThe salt used to generate API tokens.
TRANSFER_TOKEN_SALTThe salt used to generate transfer tokens.
ENCRYPTION_KEYThe key used to encrypt secrets stored in the database (e.g., provider credentials configured through the admin panel).

You can also set some optional environment variables.

The following example contains placeholder values. Replace them with your own values before starting the containers:

./.env
# Server
HOST=0.0.0.0
PORT=1337

# Database
# Use 'mysql' for MySQL or MariaDB, and change DATABASE_PORT to 3306
DATABASE_CLIENT=postgres
DATABASE_HOST=strapiDB
DATABASE_PORT=5432
DATABASE_NAME=strapi
DATABASE_USERNAME=strapi
DATABASE_PASSWORD=strapi

# Secrets
APP_KEYS=toBeModified1,toBeModified2
API_TOKEN_SALT=tobemodified
ADMIN_JWT_SECRET=tobemodified
TRANSFER_TOKEN_SALT=tobemodified
JWT_SECRET=tobemodified
ENCRYPTION_KEY=tobemodified

# Environment
NODE_ENV=development

Add Docker Compose for the database​

The following docker-compose.yml starts a database container and a Strapi container on a shared network.

Note

For more information about Docker Compose and its commands, see the Docker Compose documentation.

./docker-compose.yml
services:
  strapi:
    container_name: strapi
    build: .
    image: strapi:latest
    restart: unless-stopped
    env_file: .env  # All variables from .env are injected into the container
    volumes:
      - ./config:/opt/app/config
      - ./src:/opt/app/src
      - ./package.json:/opt/package.json
      - ./package-lock.json:/opt/package-lock.json
      - ./.env:/opt/app/.env  # Needed because Strapi uses dotenv to read .env in development
      - ./public/uploads:/opt/app/public/uploads
    ports:
      - "1337:1337"
    networks:
      - strapi
    depends_on:
      strapiDB:
        condition: service_healthy

  strapiDB:
    container_name: strapiDB
    # platform: linux/amd64  # Uncomment if you encounter platform errors on Apple Silicon
    restart: unless-stopped
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${DATABASE_USERNAME}
      POSTGRES_PASSWORD: ${DATABASE_PASSWORD}
      POSTGRES_DB: ${DATABASE_NAME}
    volumes:
      - strapi-data:/var/lib/postgresql/data/
      #- ./data:/var/lib/postgresql/data/ # if you want to use a bind folder
    ports:
      - "5432:5432"  # Exposed for local debugging tools; remove if not needed
    networks:
      - strapi
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DATABASE_USERNAME} -d ${DATABASE_NAME}"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  strapi-data:

networks:
  strapi:
    name: strapi
    driver: bridge

Build and run​

  1. Build and start all containers:

    docker compose up --build

  2. Open http://localhost:1337/admin in your browser to access the Strapi admin panel.

To stop the containers, run docker compose down. Add the -v flag to also remove the database volume.

Production environment​

Production images differ from development images in 3 key ways: they use multi-stage builds to reduce image size, they install only production dependencies in the final stage, and they run npm run start instead of the develop command. This ensures the image contains only what is needed to serve the application, without development tooling or source maps. A reverse proxy should sit in front of the Strapi container in production (see deployment documentation).

Create the production Dockerfile​

The following Dockerfile.prod uses a multi-stage build. The first stage installs all dependencies, including devDependencies needed for the build step, and builds the admin panel. The second stage copies only production assets into the final image.

./Dockerfile.prod
# Build stage
FROM node:22-alpine AS build
RUN apk update && apk add --no-cache build-base gcc autoconf automake zlib-dev libpng-dev bash vips-dev git > /dev/null 2>&1

WORKDIR /opt/
COPY package.json package-lock.json ./
RUN npm install -g node-gyp
RUN npm config set fetch-retry-maxtimeout 600000 -g && npm ci
ENV PATH=/opt/node_modules/.bin:$PATH

WORKDIR /opt/app
COPY . .
# Uncomment the following lines to set the admin panel URL at build time.
# Without this, the admin panel defaults to localhost:1337.
# ARG STRAPI_ADMIN_BACKEND_URL
# ENV STRAPI_ADMIN_BACKEND_URL=${STRAPI_ADMIN_BACKEND_URL}
ENV NODE_ENV=production
RUN npm run build

# Production stage
FROM node:22-alpine
RUN apk add --no-cache vips-dev
ENV NODE_ENV=production

WORKDIR /opt/
COPY --from=build /opt/package.json /opt/package-lock.json ./
RUN npm ci --omit=dev && npm cache clean --force
ENV PATH=/opt/node_modules/.bin:$PATH

WORKDIR /opt/app
COPY --from=build /opt/app ./

RUN chown -R node:node /opt/app
USER node
EXPOSE 1337
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD wget --quiet --tries=1 --spider http://localhost:1337/_health || exit 1
CMD ["npm", "run", "start"]
Optimize image size

The COPY --from=build /opt/app ./ line copies the entire application directory, including source files. For a leaner image, you can replace it with selective copies (e.g., dist/, build/, config/, public/, src/). This is optional since Strapi needs most of these files at runtime.

Key difference from the development Dockerfile

The build stage installs all dependencies (including devDependencies) because the npm run build step needs them to compile the admin panel. The production stage then installs only production dependencies, keeping the final image lean.

Add Docker Compose for production​

The following docker-compose.prod.yml is suitable for production deployments. It uses PostgreSQL and includes healthchecks. The Strapi port binds to 127.0.0.1 so that only a local reverse proxy can reach it.

./docker-compose.prod.yml
services:
  strapi:
    container_name: strapi
    build:
      context: .
      dockerfile: Dockerfile.prod
    image: strapi:latest
    restart: always
    env_file: .env
    environment:
      NODE_ENV: production  # Overrides the development value from .env
    ports:
      - "127.0.0.1:1337:1337"
    networks:
      - strapi
    depends_on:
      strapiDB:
        condition: service_healthy

  strapiDB:
    container_name: strapiDB
    restart: always
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${DATABASE_USERNAME}
      POSTGRES_PASSWORD: ${DATABASE_PASSWORD}
      POSTGRES_DB: ${DATABASE_NAME}
    volumes:
      - strapi-data:/var/lib/postgresql/data/
    networks:
      - strapi
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DATABASE_USERNAME} -d ${DATABASE_NAME}"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  strapi-data:

networks:
  strapi:
    name: strapi
    driver: bridge
Production checklist

Build and publish​

To build a production Docker image, run the following command:

docker build \
  -t mystrapiapp:latest \
  -f Dockerfile.prod .

After building, you can publish the image to a Docker registry. For production usage, use a private registry since your Docker image may contain sensitive configuration.

Popular container registries include:

Community tools and images​

Strapi does not provide official Docker images (see FAQ). The following community-maintained tools and images can help you get started.

If you would like to add your tool to this list, please open a pull request on the Strapi documentation repository.

The @strapi-community/dockerize CLI​

The @strapi-community/dockerize package is a CLI tool that generates a Dockerfile and docker-compose.yml file for a Strapi project.

To get started, run npx @strapi-community/dockerize@latest within an existing Strapi project folder and follow the CLI prompts.

For more information, see the official GitHub repository or the npm package.

Community-maintained Docker images​

Pre-built Docker images maintained by community members are available for Strapi 5. These images let you run Strapi without writing your own Dockerfile.

Caution

These images are community-maintained and not officially supported by Strapi. Review their documentation and source code before using them in production.

Troubleshooting​

The following section details some common issues with Sharp and ARM builds on Apple Silicon-powered machines.

Note

The Dockerfiles on this page do not include nasm in the Alpine package list. It was previously included in older versions of this guide but is not required for Sharp or libvips compilation.

Sharp and libvips errors​

Sharp is the image processing library used by Strapi. It depends on libvips, which requires native compilation on Alpine-based images. Common error messages include Cannot find module 'sharp' or Error: sharp: Installation error.

To resolve Sharp issues:

  1. Verify that your Dockerfile installs the required Alpine packages:

    RUN apk update && apk add --no-cache build-base gcc autoconf automake zlib-dev libpng-dev bash vips-dev git

  2. If the issue persists, switch to node:22-slim (Debian-based) to avoid native library compatibility problems: 

    FROM node:22-slim
    RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*

  3. For ARM builds (see below), add the following environment variable before installing dependencies:

    ENV SHARP_IGNORE_GLOBAL_LIBVIPS=1

Apple Silicon and ARM builds​

The platform: linux/amd64 flag in docker-compose files forces containers to run under x86 emulation on ARM-based machines (Apple M1/M2/M3). This works but is slower than native ARM builds.

For native ARM performance:

  • Remove the platform: linux/amd64 line from your docker-compose file.
  • Use node:22-alpine or node:22-slim as your base image. Both support ARM64 natively.
  • Ensure Sharp dependencies are installed correctly (see Sharp and libvips errors).
Note

The platform: linux/amd64 flag is commented out in the docker-compose examples above. Uncomment it if your database image does not provide an ARM64 variant.

Database connection issues​

Warning

Strapi applications must use a database created by a Strapi application. Connecting to a pre-existing non-Strapi database, or to a Strapi v3 database, is not supported and may result in lost data such as dropped tables.

If Strapi cannot connect to the database in Docker, check the following:

  1. Verify that DATABASE_HOST matches the service name in your docker-compose file (e.g., strapiDB), not localhost or 127.0.0.1. Containers communicate over the Docker network using service names.

  2. Check for port conflicts with local database instances. If a database is already running locally on the same port:

    • Stop the local database,
    • or change the host-side port mapping in your docker-compose file (e.g., "5433:5432").

  3. Set the connection pool min value to 0 in your database configuration, as Docker may kill idle connections:

    ./config/database.js
    module.exports = ({ env }) => ({
      connection: {
        client: env('DATABASE_CLIENT'),
        // ...
        pool: {
          min: 0,
          max: 10,
        },
      },
    });

  4. If the database container becomes unreachable after periods of inactivity, add timeout settings to the pool configuration in your database configuration:

    pool: {
      min: 0,
      max: 10,
      acquireTimeoutMillis: 60000,
      idleTimeoutMillis: 30000,
    },

What to do next?​

Now that Strapi is running in a Docker container, you can:

Set up the admin panel and create your first content types with the Content-Type Builder.
Configure a reverse proxy and deploy to production (see deployment documentation).
Explore environment configuration for fine-tuning your Strapi instance.

Contribute to this page