From 5819f8d5e17e0b774f8e1bdd8c929fe775024fdf Mon Sep 17 00:00:00 2001 From: Andre Wanlin Date: Thu, 31 Oct 2024 09:34:26 -0500 Subject: [PATCH 1/2] Backstage Yarn Plugin Docs adjustments Signed-off-by: Andre Wanlin --- .changeset/brave-maps-deliver.md | 5 ++ docs/deployment/docker.md | 6 +- .../keeping-backstage-updated.md | 82 +++++++++++-------- .../default-app/packages/backend/Dockerfile | 1 + 4 files changed, 58 insertions(+), 36 deletions(-) create mode 100644 .changeset/brave-maps-deliver.md diff --git a/.changeset/brave-maps-deliver.md b/.changeset/brave-maps-deliver.md new file mode 100644 index 0000000000..51b60af153 --- /dev/null +++ b/.changeset/brave-maps-deliver.md @@ -0,0 +1,5 @@ +--- +'@backstage/create-app': patch +--- + +Updated Dockerfile to include `backstage.json` file diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md index afab8ef54d..e287e327c4 100644 --- a/docs/deployment/docker.md +++ b/docs/deployment/docker.md @@ -85,6 +85,7 @@ 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 mode. ENV NODE_ENV=production @@ -181,7 +182,7 @@ the repo root: FROM node:20-bookworm-slim AS packages WORKDIR /app -COPY package.json yarn.lock ./ +COPY backstage.json package.json yarn.lock ./ COPY .yarn ./.yarn COPY .yarnrc.yml ./ @@ -219,6 +220,7 @@ WORKDIR /app COPY --from=packages --chown=node:node /app . COPY --from=packages --chown=node:node /app/.yarn ./.yarn COPY --from=packages --chown=node:node /app/.yarnrc.yml ./ +COPY --from=packages --chown=node:node /app/backstage.json ./ RUN --mount=type=cache,target=/home/node/.cache/yarn,sharing=locked,uid=1000,gid=1000 \ yarn install --immutable @@ -266,7 +268,9 @@ WORKDIR /app # Copy the install dependencies from the build stage and context COPY --from=build --chown=node:node /app/.yarn ./.yarn COPY --from=build --chown=node:node /app/.yarnrc.yml ./ +COPY --from=build --chown=node:node /app/backstage.json ./ COPY --from=build --chown=node:node /app/yarn.lock /app/package.json /app/packages/backend/dist/skeleton/ ./ + # Note: The skeleton bundle only includes package.json files -- if your app has # plugins that define a `bin` export, the bin files need to be copied as well to # be linked in node_modules/.bin during yarn install. diff --git a/docs/getting-started/keeping-backstage-updated.md b/docs/getting-started/keeping-backstage-updated.md index 08b89db518..677b82682b 100644 --- a/docs/getting-started/keeping-backstage-updated.md +++ b/docs/getting-started/keeping-backstage-updated.md @@ -9,41 +9,6 @@ latest releases. Backstage is more of a library than an application or service; similar to `create-react-app`, the `@backstage/create-app` tool gives you a starting point that's meant to be evolved. -## Managing package versions with the Backstage yarn plugin - -The Backstage yarn plugin makes it easier to manage Backstage package versions, -by determining the appropriate version for each package based on the overall -Backstage version in backstage.json. This avoids the need to update every -package.json across your Backstage monorepo, and means that when adding new -`@backstage` dependencies, you don't need to worry about figuring out the right -version to use to match the currently-installed release of Backstage. - -### Requirements - -In order to use the yarn plugin, you'll need to be using yarn 4.1.1 or greater. - -### Installation - -To install the yarn plugin, run the following command in your Backstage -monorepo: - -```bash -yarn plugin import https://versions.backstage.io/v1/tags/main/yarn-plugin -``` - -The resulting changes in the file system should be committed to your repo. - -### Usage - -When the yarn plugin is installed, versions for currently-released `@backstage` -packages can be replaced in package.json with the string `"backstage:^"`. This -instructs yarn to resolve the version based on the overall Backstage version in -backstage.json. - -The `backstage-cli versions:bump` command documented below will detect the -installation of the yarn plugin, and when it's installed, will automatically -migrate dependencies across the monorepo to use it. - ## Updating Backstage versions with backstage-cli The Backstage CLI has a command to bump all `@backstage` packages and @@ -87,6 +52,53 @@ for any applicable updates when upgrading packages. As an alternative, the a consolidated view of all the changes between two versions of Backstage. You can find the current version of your Backstage installation in `backstage.json`. +## Managing package versions with the Backstage yarn plugin + +The Backstage yarn plugin makes it easier to manage Backstage package versions, +by determining the appropriate version for each package based on the overall +Backstage version in backstage.json. This avoids the need to update every +package.json across your Backstage monorepo, and means that when adding new +`@backstage` dependencies, you don't need to worry about figuring out the right +version to use to match the currently-installed release of Backstage. + +### Requirements + +In order to use the yarn plugin, you'll need to be using yarn 4.1.1 or greater. + +### Installation + +To install the yarn plugin, run the following command in your Backstage +monorepo: + +```bash +yarn plugin import https://versions.backstage.io/v1/tags/main/yarn-plugin +``` + +The resulting changes in the file system should be committed to your repo. + +:::tip + +For best results it's ideal to add the Backstage Yarn plugin when you are about to do a Backstage upgrade as it will make it easier to confirm everything is working. + +::: + +### Usage + +When the yarn plugin is installed, versions for currently-released `@backstage` +packages can be replaced in package.json with the string `"backstage:^"`. This +instructs yarn to resolve the version based on the overall Backstage version in +`backstage.json`. + +:::tip + +The `backstage.json` is key for the plugin to work, make sure this file is included in your CI/CD pipelines and/or any Container builds. + +::: + +The `backstage-cli versions:bump` command documented above will detect the +installation of the yarn plugin, and when it's installed, will automatically +migrate dependencies across the monorepo to use it. + ## More information on dependency mismatches Backstage is structured as a monorepo with diff --git a/packages/create-app/templates/default-app/packages/backend/Dockerfile b/packages/create-app/templates/default-app/packages/backend/Dockerfile index 6a4c257afb..13ff70d961 100644 --- a/packages/create-app/templates/default-app/packages/backend/Dockerfile +++ b/packages/create-app/templates/default-app/packages/backend/Dockerfile @@ -40,6 +40,7 @@ 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 mode. ENV NODE_ENV=production From d97655487a0245ef249f10186fcac3a17cf8a661 Mon Sep 17 00:00:00 2001 From: Andre Wanlin Date: Mon, 18 Nov 2024 15:54:49 -0600 Subject: [PATCH 2/2] Small adjustments Signed-off-by: Andre Wanlin --- docs/getting-started/keeping-backstage-updated.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/getting-started/keeping-backstage-updated.md b/docs/getting-started/keeping-backstage-updated.md index 677b82682b..4804cf91c0 100644 --- a/docs/getting-started/keeping-backstage-updated.md +++ b/docs/getting-started/keeping-backstage-updated.md @@ -22,6 +22,12 @@ yarn backstage-cli versions:bump The reason for bumping all `@backstage` packages at once is to maintain the dependencies that they have between each other. +:::tip + +To make the the version bump process even easier and more streamlined we highly recommend using the [Backstage yarn plugin](#managing-package-versions-with-the-backstage-yarn-plugin) + +::: + By default the bump command will upgrade `@backstage` packages to the latest `main` release line which is released monthly. For those in a hurry that want to track the `next` release line which releases weekly can do so using the `--release next` option. ```bash @@ -56,7 +62,7 @@ can find the current version of your Backstage installation in `backstage.json`. The Backstage yarn plugin makes it easier to manage Backstage package versions, by determining the appropriate version for each package based on the overall -Backstage version in backstage.json. This avoids the need to update every +Backstage version in `backstage.json`. This avoids the need to update every package.json across your Backstage monorepo, and means that when adding new `@backstage` dependencies, you don't need to worry about figuring out the right version to use to match the currently-installed release of Backstage.