Skip to main content
Version: Next

Building the Docker image

Audience: Developers and Admins

Summary​

Every production deployment of Backstage starts with a Docker image. The image bundles both the frontend and backend into a single artifact that you can deploy anywhere containers run.

By the end of this page, you will have a Docker image ready to push to a container registry.

What is in the Docker image?​

When you created your app with @backstage/create-app, a Dockerfile was generated at packages/backend/Dockerfile. The build process layers both the frontend and backend into a single image:

  1. The backend is compiled and bundled into packages/backend/dist/.
  2. The frontend is built and served by the @backstage/plugin-app-backend plugin, which is included in the backend by default.
  3. Production dependencies are installed, and the result is packaged into a slim Node.js image.

The image runs as a non-root node user and sets NODE_ENV=production.

Building the image​

The recommended approach is a host build, where compilation happens on your machine (or CI runner) and Docker only packages the result. This is faster and produces better caching behavior.

From the root of your repository:

yarn install
yarn tsc
yarn build:backend

Then build the Docker image:

docker image build . -f packages/backend/Dockerfile --tag backstage

To verify it works locally:

docker run -it -p 7007:7007 backstage

You should see logs in your terminal and be able to open http://localhost:7007 in your browser.

Troubleshooting

If you run into build issues, two Docker flags can help:

  • --progress=plain shows verbose output instead of folded log sections.
  • --no-cache rebuilds all layers from scratch.
docker image build . -f packages/backend/Dockerfile --tag backstage --progress=plain --no-cache

Further reading​

For a full multi-stage Docker build (where everything happens inside Docker) or for deploying the frontend separately, see the Building a Docker image reference documentation.

Next steps​

Before deploying, you need to set up two production dependencies: a database and an authentication provider.