README.md

Backstage JFrog artifactory libraries plugin

The Backstage jfrog-artifactory-libs frontend plugin uses the JFrog Artifactory APIs to fetch details about artifacts (libraries) and displays these details in the Backstage app, allowing users to view information about the artifact, such as the group, artifact, repository, the latest version, and it also allows to copy library definition for the package managers. The plugin supports these package managers types in JFrog: Maven, Gradle, Sbt, Pypi, Docker, NPM, Yarn, Nuget.

• Backstage jfrog-artifactory-libs plugin
  • Authentication
  • Installation
  • Integration
  • Configuration
    • Support for scaffolding
  • How it works
  • Changes
  • Contributing
    • Development
  • Future plans
  • License

Authentication:

• The jfrog-artifactory-libs plugin does not directly handle authentication. Instead, it relies on Backstage basic HTTP proxy package which is configured to forward requests to JFrog Artifactory instance.

Installation

To install the plugin, you'll need to add it to your Backstage app's dependencies using either Yarn or NPM.

Yarn

yarn add --cwd packages/app backstage-plugin-jfrog-artifactory-libs

Integration

Once you've installed the plugin, you'll need to integrate it into your Backstage app. To do so, you'll need to following code into your BS instance:

JFrogLibArtifactCard

Add the JFrogLibArtifactCard component to the EntityPage.tsx in your app:

import {
  JFrogLibArtifactCard,
  isJfrogArtifactAvailable,
} from 'backstage-plugin-jfrog-artifactory-libs';
//....
const overviewContent = (
  // ...
  <EntitySwitch>
    //...
    <EntitySwitch.Case if={isJfrogArtifactAvailable}>
      <Grid item md={4}>
        <JFrogLibArtifactCard />
      </Grid>
    </EntitySwitch.Case>
    //...
  </EntitySwitch>
  // ...
);

JFrogLibVerPage

If you want to browse libraries you can enable this component in your App.tsx file. It shows all component entities containing jfrog.com/artifactory-artifact attribute.

const routes = (
  <FlatRoutes>
    //....
    <Route
      path="/libver"
      element={<JFrogLibVerPage topComponents={<DefineNewLibraryButton />} />}
    ></Route>
    //....
  </FlatRoutes>
);

Explore page - JFrogLibVerPageContent

This is a subcomponent of JFrogLibVerPage component. It's possible to integrate it for instance into your Explore page.

import { JFrogLibVerPageContent } from 'backstage-plugin-jfrog-artifactory-libs';
//....

        <ExploreLayout
                title={`Explore the ${organizationName} ecosystem`}
                subtitle="Discover solutions available in your ecosystem"
        >
              // ...
          <ExploreLayout.Route path="libver" title="Libraries">
            <JFrogLibVerPageContent />
            />
          </ExploreLayout.Route>
          //  ...
        </ExploreLayout>

    // ...
);

App-config.yaml

Set up a proxy for the JFrog API by adding the following configuration to your app-config.yaml file:

'/artifactory-proxy/':
  target: 'https://your-jfrog-artifactory-instance.com'
  headers:
    # if you use Jfrog instance for anonymous user token is not required, but it is also required for Docker package type
    Authorization: Bearer ${ARTIFACTORY_TOKEN}
    X-Result-Detail: 'properties'
    Accept: '*'

You have to also reference your artifactory URL (used for UI browse links) and your proxy configuration.

jfrog:
  artifactory:
    url: 'https://your-jfrog-artifactory-instance.com'
    proxyPath: '/artifactory-proxy/' # optional, /artifactory-proxy/ is default value

Catalog-info.yaml

Artifact details are correlated to Backstage entities using an annotation added in the entity's catalog-info.yaml file.

#...
metadata:
  annotations:
    # -- required values --
    jfrog.com/artifactory-artifact: 'artifact-name'
    jfrog.com/artifactory-repo: 'maven-local'
  
    jfrog.com/artifactory-group: 'com.mycompany' # optional string - can be blank for pypi, necessary for Maven repos
  
    # -- optional values --
    jfrog.com/artifactory-scope: 'compile' # optional string, one of these [compile, test,provided,runtime,classpath,optional]
    jfrog.com/artifactory-packaging: 'aar' #optional string, eg. `aar`
#...

And that's it! The plugin should now be integrated into your Backstage app, and you should see the Artifact card when you navigate to the entity page where it's included.

For a docker image you define repository and artifact name. Both formats are supported:

#...
metadata:
  annotations:
    # -- required values --
    jfrog.com/artifactory-artifact: 'docker.mydomain.com/mygroup/my/artifact-name' # or simply 'mygroup/my/artifact-name'
    jfrog.com/artifactory-repo: 'docker-local'
#...

Configuration

JFrogLibArtifactCard has following default properties:

LibArtifactCard.defaultProps = {
    title: 'Artifact', // title of the card
    browseRepositoryLinkTitle: 'Browse Repository', // Card deep link title
    showGradle: true, // whether to show Gradle package manager tab
    showMaven: true, // whether to  show Maven package manager tab
    showSbt: true, // whether to  show Sbt package manager tab
    showPip: true, // whether to  show Pip package manager tab
    showYarn: true, // whether to show Yarn package manager tab
    showDockerfile: true, // whether to  show Dockerfile tab
    // it hides Maven and Gradle tabs if the current repository package type is `PyPi`
    autohideTabs: true,
    showBrowseRepositoryLink: true, // whether to show Browse to URL deep link under bottom of the Card
    // which link to open
    browseLink: browseLinkDefault,
};

Support for scaffolding

In this document you can find detailed information how to integrate this plugin into scaffolding templates. It also adds a new extension UI component called ArtifactRepositoryPicker for interactive repository selection.

How it works

Plugin uses JFrog APIs to find latest version. It's necessary to specify ARTIFACTORY_TOKEN in the app-config.yaml file if you don't allow to access API for anonymous user.

Changes

Version 1.0.9

• JFrogLibVerPageContent and JFrogLibVerPage components added
• (!) renamed LibArtifactCard into JFrogLibArtifactCard

Contributing

Don't hesitate to contribute to the plugin. This is my first TypeScript/React/Backstage product so please be gentle to me...

Development

Copy plugin content into your plugins directory, and add a dependency into app/package.json as described above.

Future plans

• More tests
• More package managers support
• Multiple artifacts defined in one entity
• Multiple artifactories instances?

License

This plugin is licensed under the Apache 2.0 License.