Docker Deployment

This guide shows how to package a Backstage backend into a Docker container so you can run it locally or deploy it with your preferred orchestrator (for example, Kubernetes or Amazon ECS). It walks through the generated backend Dockerfile, local preparation steps, image build and run commands, and CI/CD considerations. Key terms: Backstage Docker image, Docker BuildKit, Yarn v3 (Berry), backend bundle, CI/CD build agents.

Before building, make sure you understand where the Docker build context should be. The Dockerfile expects the backend bundle artifacts under packages/backend/dist in the build context (usually the repository root).

Where the Dockerfile lives

When you create a Backstage app using backstage create-app, a production-ready Dockerfile is generated for the backend package. Dockerfile path: packages/backend/Dockerfile Below is the generated Dockerfile (unchanged):

FROM node:20-bookworm-slim
# Set Python interpreter for `node-gyp` to use
ENV PYTHON=/usr/bin/python3
# Install isolate-vm dependencies, these are needed by the @backstage/plugin-scaffolder-backend.
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update && \
    apt-get install -y --no-install-recommends python3 g++ build-essential && \
    rm -rf /var/lib/apt/lists/*
# Install sqlite3 dependencies. You can skip this if you don't use sqlite3 in the image,
# in which case you should also move better-sqlite3 to "devDependencies" in package.json.
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update && \
    apt-get install -y --no-install-recommends libsqlite3-dev && \
    rm -rf /var/lib/apt/lists/*
# From here on we use the least-privileged `node` user to run the backend.
USER node
# This should create the app dir as `node`.
# If it is instead created as `root` then the `tar` command below will fail: 'can't create directory `packages/`: Permission denied'.
# If this occurs, then ensure BuildKit is enabled ('DOCKER_BUILDKIT=1') so the app dir is correctly created as `node`.
WORKDIR /app
# Copy files needed by Yarn
COPY --chown=node:node .yarn ./.yarn
COPY --chown=node:node .yarnrc.yml ./
COPY --chown=node:node backstage.json ./
# This switches many Node.js dependencies to production
ENV NODE_ENV=production
# This disables node snapshot for Node 20 to work with the Scaffolder.
ENV NODE_OPTIONS="--no-node-snapshot"
# Copy repo skeleton first, to avoid unnecessary docker cache invalidation.
# The skeleton contains the package.json of each package in the monorepo,
# and along with yarn.lock and the root package.json, that's enough to run yarn install.
COPY --chown=node:node yarn.lock package.json packages/backend/dist/skeleton.tar.gz ./
RUN tar xzf skeleton.tar.gz && rm skeleton.tar.gz
RUN --mount=type=cache,target=/home/node/.cache/yarn,sharing=locked,uid=1000,gid=1000 \
    yarn workspaces focus --all --production && rm -rf "$(yarn cache clean)"
# This will include the examples, if you don't need these simply remove this line
COPY --chown=node:node examples ./examples
# Then copy the rest of the backend bundle, along with any other files we might want.
COPY --chown=node:node packages/backend/dist/bundle.tar.gz app-config*.yaml ./
RUN tar xzf bundle.tar.gz && rm bundle.tar.gz
CMD ["node", "packages/backend", "--config", "app-config.yaml", "--config", "app-config.production.yaml"]

Prepare the repository (local or CI)

Before running a Docker build, produce the backend artifacts the Dockerfile expects. Run these steps locally or replicate them in your CI pipeline.

Install dependencies

Use Yarn v3+ (Backstage uses Yarn Berry). Install in immutable mode so the lockfile is enforced:

yarn install --immutable

Generate TypeScript types

Compile or type-check to ensure any generated types are available:

yarn tsc

Build the backend bundle

Produce the bundle.tar.gz and skeleton.tar.gz artifacts under packages/backend/dist.

Option A — build the whole monorepo (recommended):

yarn build

Option B — build only the backend package:

# Use your workspace name if different, e.g.:
yarn workspace @backstage/backend build

After these steps confirm:

packages/backend/dist/bundle.tar.gz
packages/backend/dist/skeleton.tar.gz

exist in your repo root (or in the CI build context).

Important: Docker BuildKit

Make sure Docker BuildKit is enabled when building this Dockerfile (see https://docs.docker.com/develop/develop-images/build_enhancements/). BuildKit is required for the --mount=type=cache and certain ownership behaviors used in the Dockerfile. You can enable it by setting DOCKER_BUILDKIT=1 in your build environment.

BuildKit is required for mount caching and for correct ownership handling that the Dockerfile relies on. In CI, enable BuildKit or use a builder (kaniko/buildah) that supports these Dockerfile features.

Build the Docker image

From the repository root (so the packages/backend/dist artifacts are in context), run:

DOCKER_BUILDKIT=1 docker build -f packages/backend/Dockerfile -t backstage:latest .

Notes:

-f packages/backend/Dockerfile specifies the Dockerfile path.
The final . is the build context (typically the repo root).
DOCKER_BUILDKIT=1 enables BuildKit features.

Run the container locally

By default the Backstage backend listens on port 7000. Run the container and map the port:

docker run --rm -p 7000:7000 backstage:latest

If you override or provide additional configuration files at runtime, either include them in the image during build or mount them at runtime. The generated CMD expects app-config.yaml and app-config.production.yaml to be present in the container.

Quick reference table

Task	Command / Path	Notes
Dockerfile location	`packages/backend/Dockerfile`	The generated Dockerfile used to build the backend image.
Install dependencies	`yarn install --immutable`	Requires Yarn v3 (Berry).
Generate types	`yarn tsc`	Ensures TypeScript artifacts are available.
Build monorepo	`yarn build`	Produces `packages/backend/dist/bundle.tar.gz`.
Build image	`DOCKER_BUILDKIT=1 docker build -f packages/backend/Dockerfile -t backstage:latest .`	Build context must include `packages/backend/dist`.
Run container	`docker run --rm -p 7000:7000 backstage:latest`	Adjust ports/config if necessary.

CI/CD considerations

Reproduce the local preparation steps in your CI pipeline: install dependencies, run yarn tsc, and create the dist artifacts.
Ensure the CI runner enables Docker BuildKit or uses an alternative builder that supports the Dockerfile mount features.
Push the built image to your container registry and deploy through your preferred orchestrator (Kubernetes, AWS ECS, etc.).
For multi-stage or automated pipelines, make sure the build context (or artifacts archive) includes packages/backend/dist so the Dockerfile COPY steps succeed.

Links and references

Backstage documentation: https://backstage.io/docs
Docker BuildKit: https://docs.docker.com/develop/develop-images/build_enhancements/
Yarn v3 (Berry): https://yarnpkg.com/getting-started
Kubernetes: https://kubernetes.io/docs/
Amazon ECS: https://aws.amazon.com/ecs/

This sequence packages your Backstage backend into a production-ready Docker image, following recommended practices for reproducible builds and CI/CD.

Introduction

Backstage Basics

Catalog

Templates

TechDocs & Search

Customization & Plugins

Production Backstage

Where the Dockerfile lives

Prepare the repository (local or CI)

Important: Docker BuildKit

Build the Docker image

Run the container locally

Quick reference table

CI/CD considerations

Links and references

Watch Video

​Where the Dockerfile lives

​Prepare the repository (local or CI)

​Important: Docker BuildKit

​Build the Docker image

​Run the container locally

​Quick reference table

​CI/CD considerations

​Links and references

Watch Video

Where the Dockerfile lives

Prepare the repository (local or CI)

Important: Docker BuildKit

Build the Docker image

Run the container locally

Quick reference table

CI/CD considerations

Links and references