Backstage Docker tags Plugin

Docker tags are labels on container images that mark versions or variants. They let you tell one build from another so you can pick a specific image for dev or prod with confidence. On Docker Hub you manage many image versions under one repository through tags. If you do not set a tag Docker uses latest by default.

The Docker tags plugin adds a compact view of those tags inside Backstage. It reads a repository on Docker Hub and lists the available tags for the service you are looking at. You see a table with fields like name, username, status, and architecture. You can tune the columns and page size to fit your layout. Private repositories are supported through a Docker Hub token passed through the Backstage proxy. The goal is simple. Keep image versions visible where engineers already work.

Typical use cases include checking that a new build reached Docker Hub before a release. Or scanning what variants exist across arches. Or reviewing old tags during cleanup. TIf you run a self hosted Backstage and want image awareness without leaving the catalog, this plugin covers that gap with very little ceremony.

Install the frontend package

Copy

yarn add --cwd packages/app @workm8/backstage-docker-tags

Configure the proxy

Add a proxy entry in your root app config. This routes requests to Docker Hub.

Copy

# app-config.yaml
proxy:
  endpoints:
    '/docker':
      target: 'https://hub.docker.com'
      changeOrigin: true

Enable the proxy in the old backend system

Add the backend package

Copy

yarn add --cwd packages/backend @backstage/plugin-proxy-backend

Wire it up in your backend. Mount it under the proxy path.

Copy

// packages/backend/src/index.ts
import { createRouter as createProxyRouter } from '@backstage/plugin-proxy-backend';

// inside your main bootstrap where you build apiRouter
const proxyRouter = await createProxyRouter({ logger, config });
apiRouter.use('/proxy', proxyRouter);

Enable the proxy in the new backend system

Add the backend package

Copy

yarn add --cwd packages/backend @backstage/plugin-proxy-backend

Copy

// packages/backend/src/index.ts
import { createBackend } from '@backstage/backend-defaults';

const backend = createBackend();

// keep your other modules
backend.add(import('@backstage/plugin-proxy-backend'));

backend.start();

Import the widget in your app package. Place it on the catalog entity page so users can see it.

Copy

// packages/app/src/components/catalog/EntityPage.tsx
import React from 'react';
import Grid from '@material-ui/core/Grid';
import { EntityAboutCard, EntityCatalogGraphCard, EntityLinksCard, EntityHasSubcomponentsCard } from '@backstage/plugin-catalog';
import { DockerTagsTableWidget } from '@workm8/backstage-docker-tags';

Create the widget content and render it on the overview section.

Copy

// inside EntityPage.tsx

const dockerTagsContent = (
  <DockerTagsTableWidget
    heading="Docker"
    columns={['name', 'username', 'status']}
  />
);

const overviewContent = (
  <Grid container spacing={3} alignItems="stretch">
    {/* keep your existing cards */}
    <Grid item md={4} xs={12}>
      {dockerTagsContent}
    </Grid>
  </Grid>
);

Annotate your catalog entities

Add the annotation to each entity that should show Docker tags.

Copy

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: grafana
  annotations:
    docker.com/repository: grafana/grafana
spec:
  type: service
  lifecycle: production
  owner: team-a

Private repositories

Create a Personal Access Token in Docker Hub. Add it to the proxy headers.

Copy

# app-config.yaml
proxy:
  endpoints:
    '/docker':
      target: 'https://hub.docker.com'
      changeOrigin: true
      headers:
        Authorization: YOUR_TOKEN_VALUE

You can control the header text and the table columns.

Copy

<DockerTagsTableWidget
  heading="Docker"
  columns={['name', 'username', 'status', 'architecture']}
  initialPage={0}
  pageSize={5}
  pageSizeOptions={[5, 10, 25]}
  showCountInHeading={true}
/>

Backstage Docker tags Plugin

Installation Instructions

Install the frontend package

Configure the proxy

Enable the proxy in the old backend system

Enable the proxy in the new backend system

Add the widget to the entity page

Annotate your catalog entities

Private repositories

Widget options

Set up Backstage in minutes with Roadie