# 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 developing, shipping, and running 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

# 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.

For more information on the Dockerfile and its commands, please refer to the official Docker documentation (opens new window).

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.

✏️ NOTE

For more information about running Docker compose and it's commands, please refer to the Docker Compose documentation (opens new window).

Sample docker-compose.yml:

# Production Environments

# Dockerfile

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

# Building the production container

Building production Docker images can have several options. The following example uses the docker build command to build a production Docker image for a Strapi project. However, it is recommended you review the Docker documentation (opens new window) for more information on building Docker images with more advanced options.

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

docker build \
  --build-arg NODE_ENV=production \
  # --build-arg STRAPI_URL=https://api.example.com \ # Uncomment to set the Strapi Server URL
  -t mystrapiapp:latest \ # Replace with your image name
  -f Dockerfile.prod .

# (Optional) Publishing the container to a registry

After you have built a production Docker image for a Strapi project, you can publish the image to a Docker registry. Ideally for production usage this should be a private registry as your Docker image will contain sensitive information.

Depending on your hosting provider you may need to use a different command to publish your image. It is recommended you review the Docker documentation (opens new window) for more information on publishing Docker images with more advanced options.

Some popular hosting providers are:

# 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 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 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 →