# Running Strapi in a Docker container

✋ 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 to the community on Discord (opens new window).

The following documentation will guide you through the process of building a custom Docker (opens new window) container with an existing Strapi project.

Docker is an open platform that allows to develop, ship and run applications by using containers (i.e. packages containing all the parts an application needs to function, such as libraries and dependencies). Containers are isolated from each other and bundle their own software, libraries and configuration files; they can communicate with each other through well-defined channels.

# Prerequisites

To follow the instructions below, the following will be needed:

# Development and/or Staging environments

For working with Strapi locally on your host machine (i.e. development and/or staging environments), you can use the Dockerfile (opens new window) and if needed the docker-compose.yml (opens new window) can also be used to start up a database container.

Both of these methods will require an existing Strapi project, or a new one created with Strapi Quick Start.

# Dockerfile

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

✏️ NOTE

If you are using docker-compose, you can skip setting the environment variables manually, as they will be set in the docker-compose.yml file or a .env file.

There are several environment variables that are required to be set in order to run Strapi in a Docker container, there are also several optional variables you can also set.

The following environment variables are required:

Variable name Description
NODE_ENV The environment in which the application is running.
DATABASE_CLIENT The database client to use.
DATABASE_HOST The database host.
DATABASE_PORT The database port.
DATABASE_NAME The database name.
DATABASE_USERNAME The database username.
DATABASE_PASSWORD The database password.
JWT_SECRET The secret used to sign the JWT for the Users-Permissions plugin.
ADMIN_JWT_SECRET The secret used to sign the JWT for the Admin panel.
APP_KEYS The secret keys used to sign the session cookies.

Sample Dockerfile:

# (Optional) Docker Compose

The following docker-compose.yml can be used to start up a database container and a Strapi container along with a shared network for communication between the two.

# Production Environments

# Dockerfile

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

# Building the production container

# (Optional) Publishing the container to a registry

# (Optional) Deploying to various cloud providers

# Community Tools

There are several community tools that can be used to deploy Strapi to various cloud providers and can assist you in setting up Docker both in a development and production environment.

We strongly support our community efforts and encourage you to check out the following tools, please do help support them by contributing to their development.

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

# @strapi-community/dockerize

The @strapi-community/dockerize package is a CLI tool that can be used to generate a Dockerfile and docker-compose.yml file for a Strapi project.

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

For more information please see the official GitHub repository (opens new window) or the npm package (opens new window).

# Docker FAQ

# Why doesn't Strapi provide official Docker images?

Strapi is a framework that can be used to build many different types of applications. As such, it is not possible to provide a single Docker image that can be used for all use cases.

# Why do we have different Dockerfiles for development and production?

The primary cause for the need for various Docker images is due to the way our Admin panel is built. The Admin panel is built using React and is bundled into the Strapi application during the build process. This means that Strapi backend is simply acting as a web server to serve the Admin panel and thus certain environment variables are statically compiled into the built Admin panel.

It is generally considered a best practice with Strapi to build different Docker images for development and production environments. This is because the development environment is not optimized for performance and is not intended to be exposed to the public internet.

← Project structure →