paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 27 Packages Projects Releases Wiki Activity

Merge branch 'backstage:master' into milliehartnt123-create-ui-doc

Browse Source
This commit is contained in:
milliehartnt123
2026-02-17 09:23:28 -05:00
committed by GitHub
parent c546f03134 ca255bfaab
commit e46ec22005
2658 changed files with 122677 additions and 44061 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/getting-started/config/database.md
+86 -6
View File
@@ -106,6 +106,88 @@ When filling these out, you have 2 choices,
If you opt for the second option of replacing the entire string, take care to not commit your `app-config.yaml` to source control. It may contain passwords that you don't want leaked.
## Passwordless PostgreSQL in the Cloud
If you want to host your PostgreSQL server in the cloud with passwordless authentication, you can use Azure Database for PostgreSQL with Microsoft Entra authentication or Google Cloud SQL for PostgreSQL with Cloud IAM.
### Azure with Entra authentication
Remove `password` from the connection configuration and set `type` to `azure`.
Optionally set `tokenCredential` with the following properties. If no credential information is provided, it will default to using Default Azure Credential and a tokenRenewalOffsetTime of 5 minutes.
#### Credential Selection
The credential type is automatically inferred based on the fields you provide:
- Client Secret Credential is used when all three are provided:
- `tenantId`
- `clientId`
- `clientSecret`
- Managed Identity Credential is used when only `clientId` is provided. This enables user-assigned managed identity.
- Default Azure Credential is used when no credential fields are provided. Default Azure Credential supports [many credential types](https://learn.microsoft.com/azure/developer/javascript/sdk/authentication/credential-chains#use-defaultazurecredential-for-flexibility), choosing one based on the runtime environment.
#### Token Renewal
Set `tokenRenewalOffsetTime` to control how early OAuth tokens should be refreshed.
The value may be:
- A human-readable string such as '1d', '2 hours', '30 seconds'
- A duration object, e.g. { minutes: 3, seconds: 30 }
Azure PostgreSQL uses short-lived Entra ID access tokens.
By default, the database connector refreshes tokens 5 minutes before they expire.
#### User Configuration
Set `user` to the display name of your Entra ID group, service principal, or managed identity. Set it to the user principal name if you're authenticating with a user's credentials.
#### Example
```yaml title="app-config.yaml"
backend:
database:
client: pg
connection:
# highlight-add-start
type: azure
tokenCredential:
tokenRenewalOffsetTime: 5 minutes
# highlight-add-end
host: ${POSTGRES_HOST}
port: ${POSTGRES_PORT}
user: ${POSTGRES_USER}
# highlight-remove-start
password: ${POSTGRES_PASSWORD}
# highlight-remove-end
```
### Google with Cloud IAM
Remove `password` from the connection configuration and set `type` to `cloudsql`.
Under the hood, this implements [Automatic IAM Database Authentication](https://github.com/GoogleCloudPlatform/cloud-sql-nodejs-connector?tab=readme-ov-file#automatic-iam-database-authentication).
For an IAM user account, set `user` to the user's email address. For a service account, set `user` to the service account's email without the .gserviceaccount.com domain suffix.
```yaml title="app-config.yaml"
backend:
database:
client: pg
connection:
# highlight-add-start
type: cloudsql
instance: my-project:region:my-instance
# highlight-add-end
host: ${POSTGRES_HOST}
port: ${POSTGRES_PORT}
user: ${POSTGRES_USER}
# highlight-remove-start
password: ${POSTGRES_PASSWORD}
# highlight-remove-end
```
:::
[Start the Backstage app](../index.md#2-run-the-backstage-app):
@@ -126,16 +208,16 @@ You may not want to install Postgres locally, the following sections outline alt
You can run Postgres in a Docker container, this is great for local development or getting a Backstage POC up and running quickly, here's how:
First we need to pull down the container image, we'll use Postgres 17, check out the [Postgres Version Policy](../../overview/versioning-policy.md#postgresql-releases) to learn which versions are supported.
First we need to pull down the container image, we'll use Postgres 18, check out the [Postgres Version Policy](../../overview/versioning-policy.md#postgresql-releases) to learn which versions are supported.
```shell
docker pull postgres:17.0-trixie
docker pull postgres:18-trixie
```
Then we just need to start up the container.
```shell
docker run -d --name postgres --restart=always -p 5432:5432 -e POSTGRES_PASSWORD=<secret> postgres:17.0-trixie
docker run -d --name postgres --restart=always -p 5432:5432 -e POSTGRES_PASSWORD=<secret> postgres:18-trixie
```
This will run Postgres in the background for you, but remember to start it up again when you reboot your system.
@@ -145,11 +227,9 @@ This will run Postgres in the background for you, but remember to start it up ag
Another way to run Postgres is to use Docker Compose, here's what that would look like:
```yaml title="docker-compose.local.yaml"
version: '4'
services:
postgres:
image: postgres:17.0-trixie
image: postgres:18-trixie
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: <secret>
docs/getting-started/homepage.md
+78 -2
View File
@@ -24,7 +24,83 @@ Before we begin, make sure
Now, let's get started by installing the home plugin and creating a simple homepage for your Backstage app.
### Setup homepage
## Setup Methods
There are two ways to set up the home plugin, depending on which frontend system your Backstage app uses:
1. **New Frontend System (Recommended)** - For apps using the new plugin system with extensions and blueprints
2. **Legacy Frontend System** - For existing apps using the legacy plugin architecture
### New Frontend System Setup
If your Backstage app uses the [new frontend system](../frontend-system/index.md), follow these steps:
#### 1. Install the plugin
```bash title="From your Backstage root directory"
yarn --cwd packages/app add @backstage/plugin-home
```
#### 2. Add the plugin to your app configuration
Update your `packages/app/src/app.tsx` to include the home plugin:
```tsx title="packages/app/src/app.tsx"
import homePlugin from '@backstage/plugin-home/alpha';
const app = createApp({
features: [
// ... other plugins
homePlugin,
],
});
```
#### 3. Configure the homepage as your root route
By default, the homepage will be available at `/home`. To make it your app's landing page at `/`, add this configuration to your `app-config.yaml`:
```yaml title="app-config.yaml"
app:
extensions:
- page:home:
config:
path: /
```
The plugin will automatically add a "Home" navigation item to your sidebar and provide a basic homepage layout.
#### 4. Optional: Enable visit tracking
Visit tracking is an optional feature that allows users to see their recently visited and most visited pages on the homepage. This feature is **disabled by default** to give you control over what data is collected and stored.
Visit tracking requires a storage implementation to persist user data:
- **With UserSettings storage** (recommended): If you have the [UserSettings plugin](https://backstage.io/docs/features/software-catalog/external-integrations/#user-settings) configured with persistent storage, visit data will be stored there and synchronized across devices.
- **Fallback to local storage**: If no persistent storage is available, the plugin will automatically fall back to browser local storage, which stores data locally per device.
To enable visit tracking, add this configuration to your `app-config.yaml`:
```yaml title="app-config.yaml"
app:
extensions:
- api:home/visits: true
- app-root-element:home/visit-listener: true
```
#### 5. Customizing your homepage
The New Frontend System provides powerful customization options:
**Custom Homepage Layouts**: Use the `HomePageLayoutBlueprint` from `@backstage/plugin-home-react/alpha` to create custom homepage layouts with your own design and widget arrangements. A layout receives the installed widgets and is responsible for rendering them. If no custom layout is installed, the plugin provides a built-in default.
**Adding Homepage Widgets**: Register custom widgets using the `HomePageWidgetBlueprint` from the `@backstage/plugin-home-react/alpha` package.
For detailed instructions on creating custom layouts, registering widgets, and advanced configuration options, see the [Home plugin documentation](https://github.com/backstage/backstage/tree/master/plugins/home#readme).
### Legacy Frontend System Setup
If your Backstage app uses the legacy frontend system, follow these steps:
#### 1. Install the plugin
@@ -88,7 +164,7 @@ Let's update the route for "Home" in the Backstage sidebar to point to the new h
| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| ![Sidebar without Catalog](../assets/getting-started/sidebar-without-catalog.png) | ![Sidebar with Catalog](../assets/getting-started/sidebar-with-catalog.png) |
The code for the Backstage sidebar is most likely inside your [`packages/app/src/components/Root/Root.tsx`](https://github.com/backstage/backstage/blob/master/packages/app/src/components/Root/Root.tsx).
The code for the Backstage sidebar is most likely inside your [`packages/app-legacy/src/components/Root/Root.tsx`](https://github.com/backstage/backstage/blob/master/packages/app-legacy/src/components/Root/Root.tsx).
Let's make the following changes
docs/getting-started/index.md
+1 -1
View File
@@ -81,7 +81,7 @@ This guide also assumes a basic understanding of working on a Linux based operat
- Using `nvm` (recommended)
- [Installing nvm](https://github.com/nvm-sh/nvm#install--update-script)
- [Install and change Node version with nvm](https://nodejs.org/en/download/package-manager/#nvm)
- Node 24 is a good starting point, this can be installed using `nvm install lts/krypton`
- Node 22 or 24 are recommended, these can be installed using `nvm install 22` or `nvm install 24`
- [Binary Download](https://nodejs.org/en/download/)
- [Package manager](https://nodejs.org/en/download/package-manager/)
- [Using NodeSource packages](https://github.com/nodesource/distributions/blob/master/README.md)
docs/getting-started/keeping-backstage-updated.md
+10
View File
@@ -43,6 +43,16 @@ By default the bump command will upgrade `@backstage` packages to the latest `ma
yarn backstage-cli versions:bump --release next
```
You can also use the `--release` option to target a specific version. This is useful if you need to pin your app to a specific release or if you need to downgrade to a previous version (e.g. moving from `1.45.0` back to `1.43.0`).
:::warning
Note that downgrading across significant version gaps (e.g. 2-3 releases) may result in package mismatches or errors due to the way Backstage manages dependencies. This method is best suited for small adjustments.
:::
```bash
yarn backstage-cli versions:bump --release 1.43.0
```
If you are using other plugins you can pass in the `--pattern` option to update
more than just the `@backstage/*` dependencies.