# 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 on Discord (opens new window).

The following documentation will guide you through 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 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 methods require an existing Strapi project or a new one created (see Quick Start guide).

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

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

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.

You can also set some optional environment variables.

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 its commands, please refer to the Docker Compose documentation (opens new window).

Sample docker-compose.yml:

# Production Environments

The Docker image in production is different from the one used in development/staging environments because of the differences in the admin build process in addition to the command used to run the application. Typical production environments will use a reverse proxy to serve the application and the admin panel. The Docker image is built with the production build of the admin panel and the command used to run the application is strapi start.

Once the Dockerfile is created, the production container can be built. Optionally, the container can be published to a registry to make it available to the community. Community tools can help you in the process of building a production Docker image and deploying it to a production environment.

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

Several community tools are available to assist you in deploying Strapi to various cloud providers and setting up Docker in a development or 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).

# @strapi-community/deployify

The @strapi-community/deployify package is a CLI tool that can be used to deploy your application to various cloud providers and hosting services. Several of these also support deploying a Strapi project with a Docker container and will call on the @strapi-community/dockerize package to generate the required files if they don't already exist.

To get started run npx @strapi-community/deployify@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 reason 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 the Strapi backend is 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 →