https://backstage.io/assets/js/f3b9c749.97b5eb96.js

1"use strict";(self.webpackChunkbackstage_microsite=self.webpackChunkbackstage_microsite||[]).push([["15851"],{748115(e,a,n){n.r(a),n.d(a,{assets:()=>c,contentTitle:()=>r,default:()=>h,frontMatter:()=>o,metadata:()=>t,toc:()=>l});var t=n(383274),s=n(474848),i=n(28453);let o={id:"keeping-backstage-updated",sidebar_label:"006 - Keep Backstage updated",title:"006 - Keeping Backstage up to date",description:"How to keep your Backstage instance up to date with the latest releases"},r,c={},l=[{value:"Summary",id:"summary",level:2},{value:"Updating Backstage versions with backstage-cli",id:"updating-backstage-versions-with-backstage-cli",level:2},{value:"Following create-app template changes",id:"following-create-app-template-changes",level:2},{value:"Managing package versions with the Backstage yarn plugin",id:"managing-package-versions-with-the-backstage-yarn-plugin",level:2},{value:"Requirements",id:"requirements",level:3},{value:"Installation",id:"installation",level:3},{value:"Usage",id:"usage",level:3},{value:"More information on dependency mismatches",id:"more-information-on-dependency-mismatches",level:2},{value:"Proxy",id:"proxy",level:2},{value:"Example Configuration",id:"example-configuration",level:3},{value:"Rollback migrations",id:"rollback-migrations",level:2}];function d(e){let a={a:"a",admonition:"admonition",code:"code",em:"em",h2:"h2",h3:"h3",p:"p",pre:"pre",strong:"strong",...(0,i.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(a.p,{children:"Audience: Developers and Admins"}),"\n",(0,s.jsx)(a.admonition,{type:"note",children:(0,s.jsxs)(a.p,{children:["To better understand the concepts in this section, it's recommended to have an understanding of ",(0,s.jsx)(a.a,{href:"https://semaphoreci.com/blog/what-is-monorepo",children:"Monorepos"}),", ",(0,s.jsx)(a.a,{href:"https://semver.org",children:"Semantic Versioning"})," and ",(0,s.jsx)(a.a,{href:"https://keepachangelog.com",children:"CHANGELOGs"}),"."]})}),"\n",(0,s.jsx)(a.h2,{id:"summary",children:"Summary"}),"\n",(0,s.jsxs)(a.p,{children:["Backstage is always improving, so it's a good idea to stay in sync with the\nlatest releases. Backstage is more of a library than an application or service;\nsimilar to ",(0,s.jsx)(a.code,{children:"create-react-app"}),", the ",(0,s.jsx)(a.code,{children:"@backstage/create-app"})," tool gives you a\nstarting point that's meant to be evolved."]}),"\n",(0,s.jsx)(a.h2,{id:"updating-backstage-versions-with-backstage-cli",children:"Updating Backstage versions with backstage-cli"}),"\n",(0,s.jsxs)(a.p,{children:["The Backstage CLI has a command to bump all ",(0,s.jsx)(a.code,{children:"@backstage"})," packages and\ndependencies you're using to the latest versions:\n",(0,s.jsx)(a.a,{href:"https://backstage.io/docs/tooling/cli/03-commands#versionsbump",children:"versions:bump"}),"."]}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-bash",children:"yarn backstage-cli versions:bump\n"})}),"\n",(0,s.jsxs)(a.p,{children:["The reason for bumping all ",(0,s.jsx)(a.code,{children:"@backstage"})," packages at once is to maintain the\ndependencies that they have between each other."]}),"\n",(0,s.jsx)(a.p,{children:(0,s.jsx)(a.a,{name:"plugin"})}),"\n",(0,s.jsx)(a.admonition,{type:"tip",children:(0,s.jsxs)(a.p,{children:["To make the version bump process even easier and more streamlined we highly recommend using the ",(0,s.jsx)(a.a,{href:"#managing-package-versions-with-the-backstage-yarn-plugin",children:"Backstage yarn plugin"})]})}),"\n",(0,s.jsxs)(a.p,{children:["By default the bump command will upgrade ",(0,s.jsx)(a.code,{children:"@backstage"})," packages to the latest ",(0,s.jsx)(a.code,{children:"main"})," release line which is released monthly. For those in a hurry that want to track the ",(0,s.jsx)(a.code,{children:"next"})," release line which releases weekly can do so using the ",(0,s.jsx)(a.code,{children:"--release next"})," option."]}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-bash",children:"yarn backstage-cli versions:bump --release next\n"})}),"\n",(0,s.jsxs)(a.p,{children:["If you are using other plugins you can pass in the ",(0,s.jsx)(a.code,{children:"--pattern"})," option to update\nmore than just the ",(0,s.jsx)(a.code,{children:"@backstage/*"})," dependencies."]}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-bash",children:"yarn backstage-cli versions:bump --pattern '@{backstage,roadiehq}/*'\n"})}),"\n",(0,s.jsx)(a.h2,{id:"following-create-app-template-changes",children:"Following create-app template changes"}),"\n",(0,s.jsxs)(a.p,{children:["The ",(0,s.jsx)(a.code,{children:"@backstage/create-app"})," command creates the initial structure of your\nBackstage installation from a ",(0,s.jsx)(a.strong,{children:"template"}),". The source of this template in the\nBackstage repository is updated periodically, but your local ",(0,s.jsx)(a.code,{children:"app"})," and ",(0,s.jsx)(a.code,{children:"backend"}),"\npackages are established at ",(0,s.jsx)(a.code,{children:"create-app"})," time and won't automatically get these\ntemplate updates."]}),"\n",(0,s.jsxs)(a.p,{children:["For this reason, any changes made to the template are documented along with\nupgrade instructions in the\n",(0,s.jsx)(a.a,{href:"https://github.com/backstage/backstage/blob/master/packages/create-app/CHANGELOG.md",children:"changelog"}),"\nof the ",(0,s.jsx)(a.code,{children:"@backstage/create-app"})," package. We recommend peeking at this changelog\nfor any applicable updates when upgrading packages. As an alternative, the\n",(0,s.jsx)(a.a,{href:"https://backstage.github.io/upgrade-helper/",children:"Backstage Upgrade Helper"})," provides\na consolidated view of all the changes between two versions of Backstage. You\ncan find the current version of your Backstage installation in ",(0,s.jsx)(a.code,{children:"backstage.json"})," located in the root of your backstage repository."]}),"\n",(0,s.jsx)(a.h2,{id:"managing-package-versions-with-the-backstage-yarn-plugin",children:"Managing package versions with the Backstage yarn plugin"}),"\n",(0,s.jsxs)(a.p,{children:["The Backstage yarn plugin makes it easier to manage Backstage package versions,\nby determining the appropriate version for each package based on the overall\nBackstage version in ",(0,s.jsx)(a.code,{children:"backstage.json"}),". This avoids the need to update every\npackage.json across your Backstage monorepo, and means that when adding new\n",(0,s.jsx)(a.code,{children:"@backstage"})," dependencies, you don't need to worry about figuring out the right\nversion to use to match the currently-installed release of Backstage."]}),"\n",(0,s.jsx)(a.h3,{id:"requirements",children:"Requirements"}),"\n",(0,s.jsx)(a.p,{children:"In order to use the yarn plugin, you'll need to be using yarn 4.1.1 or greater."}),"\n",(0,s.jsx)(a.h3,{id:"installation",children:"Installation"}),"\n",(0,s.jsx)(a.p,{children:"To install the yarn plugin, run the following command in your Backstage\nmonorepo:"}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-bash",children:"yarn plugin import https://versions.backstage.io/v1/tags/main/yarn-plugin\n"})}),"\n",(0,s.jsx)(a.p,{children:"The resulting changes in the file system should be committed to your repo."}),"\n",(0,s.jsx)(a.admonition,{type:"tip",children:(0,s.jsx)(a.p,{children:"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."})}),"\n",(0,s.jsx)(a.h3,{id:"usage",children:"Usage"}),"\n",(0,s.jsxs)(a.p,{children:["When the yarn plugin is installed, versions for currently-released ",(0,s.jsx)(a.code,{children:"@backstage"}),"\npackages can be replaced in package.json with the string ",(0,s.jsx)(a.code,{children:'"backstage:^"'}),". This\ninstructs yarn to resolve the version based on the overall Backstage version in\n",(0,s.jsx)(a.code,{children:"backstage.json"}),"."]}),"\n",(0,s.jsx)(a.admonition,{type:"tip",children:(0,s.jsxs)(a.p,{children:["The ",(0,s.jsx)(a.code,{children:"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."]})}),"\n",(0,s.jsxs)(a.p,{children:["The ",(0,s.jsx)(a.code,{children:"backstage-cli versions:bump"})," command documented above will detect the\ninstallation of the yarn plugin, and when it's installed, will automatically\nmigrate dependencies across the monorepo to use it."]}),"\n",(0,s.jsx)(a.h2,{id:"more-information-on-dependency-mismatches",children:"More information on dependency mismatches"}),"\n",(0,s.jsxs)(a.p,{children:["Backstage is structured as a monorepo with\n",(0,s.jsx)(a.a,{href:"https://classic.yarnpkg.com/en/docs/workspaces

1/",children:"Yarn workspaces"}),". This means\nthe ",(0,s.jsx)(a.code,{children:"app"})," and ",(0,s.jsx)(a.code,{children:"backend"})," packages, as well as any custom plugins you've added,\nare separate packages with their own ",(0,s.jsx)(a.code,{children:"package.json"})," and dependencies."]}),"\n",(0,s.jsxs)(a.p,{children:["When a given dependency version is the ",(0,s.jsx)(a.em,{children:"same"})," between different packages, the\ndependency is hoisted to the main ",(0,s.jsx)(a.code,{children:"node_modules"})," folder in the monorepo root to\nbe shared between packages. When ",(0,s.jsx)(a.em,{children:"different"})," versions of the same dependency are\nencountered, Yarn creates a ",(0,s.jsx)(a.code,{children:"node_modules"})," folder within a particular package.\nThis can lead to multiple versions of the same package being installed and used\nin the same app."]}),"\n",(0,s.jsxs)(a.p,{children:["All Backstage core packages are implemented in such as way that package\nduplication is ",(0,s.jsx)(a.strong,{children:"not"})," a problem. For example, duplicate installations of\npackages like ",(0,s.jsx)(a.code,{children:"@backstage/core-plugin-api"}),", ",(0,s.jsx)(a.code,{children:"@backstage/core-components"}),",\n",(0,s.jsx)(a.code,{children:"@backstage/plugin-catalog-react"}),", and ",(0,s.jsx)(a.code,{children:"@backstage/backend-plugin-api"})," are all\nacceptable."]}),"\n",(0,s.jsxs)(a.p,{children:["While package duplication might be acceptable in many cases, you might want to\ndeduplicate packages for the purpose of optimizing bundle size and installation\nspeed. We recommend using deduplication utilities such as ",(0,s.jsx)(a.code,{children:"yarn dedupe"})," to trim\ndown the number of duplicate packages."]}),"\n",(0,s.jsx)(a.h2,{id:"proxy",children:"Proxy"}),"\n",(0,s.jsxs)(a.p,{children:["The Backstage CLI respects the standard ",(0,s.jsx)(a.code,{children:"HTTP_PROXY"}),", ",(0,s.jsx)(a.code,{children:"HTTPS_PROXY"}),", and ",(0,s.jsx)(a.code,{children:"NO_PROXY"})," environment variables when ",(0,s.jsx)(a.code,{children:"NODE_USE_ENV_PROXY=1"})," is set. See the ",(0,s.jsx)(a.a,{href:"/docs/next/tutorials/corporate-proxy",children:"corporate proxy guide"})," for full details."]}),"\n",(0,s.jsxs)(a.p,{children:["Additionally, ",(0,s.jsx)(a.code,{children:"yarn"})," needs a proxy too (sometimes), when in environments with restricted internet access. It uses different settings than the other modules. If you decide to use the backstage yarn plugin ",(0,s.jsx)(a.a,{href:"#managing-package-versions-with-the-backstage-yarn-plugin",children:"mentioned above"}),", you will need to set additional proxy values.\nIf you will always need proxy settings in all environments and situations, you can add ",(0,s.jsx)(a.code,{children:"httpProxy"})," and ",(0,s.jsx)(a.code,{children:"httpsProxy"})," values to ",(0,s.jsx)(a.a,{href:"https://yarnpkg.com/configuration/yarnrc",children:"the yarnrc.yml file"}),". If some environments need it (say a developer workstation) but other environments do not (perhaps a CI build server running on AWS), then you may not want to update the yarnrc.yml file but just set environment variables ",(0,s.jsx)(a.code,{children:"YARN_HTTP_PROXY"})," and ",(0,s.jsx)(a.code,{children:"YARN_HTTPS_PROXY"})," in the environments/situations where you need to proxy."]}),"\n",(0,s.jsxs)(a.p,{children:[(0,s.jsxs)(a.strong,{children:["If you plan to use the backstage yarn plugin, you will need these extra yarn proxy settings to both install the plugin and run the ",(0,s.jsx)(a.code,{children:"versions:bump"})," command"]}),". If you do not plan to use the backstage yarn plugin, it seems like the proxy settings alone are sufficient."]}),"\n",(0,s.jsx)(a.h3,{id:"example-configuration",children:"Example Configuration"}),"\n",(0,s.jsx)(a.pre,{children:(0,s.jsx)(a.code,{className:"language-bash",children:"export HTTP_PROXY=http://proxy.company.com:8080\nexport HTTPS_PROXY=http://proxy.company.com:8080\nexport NO_PROXY=localhost,internal.company.com\nexport NODE_USE_ENV_PROXY=1\nexport YARN_HTTP_PROXY=${HTTP_PROXY}                          # optional\nexport YARN_HTTPS_PROXY=${HTTPS_PROXY}                        # optional\n"})}),"\n",(0,s.jsx)(a.h2,{id:"rollback-migrations",children:"Rollback migrations"}),"\n",(0,s.jsxs)(a.p,{children:["In some cases you could need to downgrade Backstage instance due to some problem or maybe because you are using a test environment to validate the new version of Backstage. You can check the ",(0,s.jsx)(a.a,{href:"/docs/next/tutorials/manual-knex-rollback",children:"Manual Rollback using Knex"})," guide to know how to rollback migrations using Knex."]})]})}function h(e={}){let{wrapper:a}={...(0,i.R)(),...e.components};return a?(0,s.jsx)(a,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},28453(e,a,n){n.d(a,{R:()=>o,x:()=>r});var t=n(296540);let s={},i=t.createContext(s);function o(e){let a=t.useContext(i);return t.useMemo(function(){return"function"==typeof e?e(a):{...a,...e}},[a,e])}function r(e){let a;return a=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:o(e.components),t.createElement(i.Provider,{value:a},e.children)}},383274(e){e.exports=JSON.parse('{"id":"golden-path/create-app/keeping-backstage-updated","title":"006 - Keeping Backstage up to date","description":"How to keep your Backstage instance up to date with the latest releases","source":"@site/../docs/golden-path/create-app/keeping-backstage-updated.md","sourceDirName":"golden-path/create-app","slug":"/golden-path/create-app/keeping-backstage-updated","permalink":"/docs/next/golden-path/create-app/keeping-backstage-updated","draft":false,"unlisted":false,"editUrl":"https://github.com/backstage/backstage/edit/master/docs/golden-path/create-app/keeping-backstage-updated.md","tags":[],"version":"current","frontMatter":{"id":"keeping-backstage-updated","sidebar_label":"006 - Keep Backstage updated","title":"006 - Keeping Backstage up to date","description":"How to keep your Backstage instance up to date with the latest releases"}}')}}]);