Bower Repositories

JFrog Artifactory Documentation

ft:sourceType
Paligo

Overview

Artifactory supports bower repositories on top its existing support for advanced artifact management.

Artifactory support for Bower provides:

  1. The ability to provision Bower packages from Artifactory to the Bower command line tool from all repository types.

  2. Calculation of Metadata for Bower packages hosted in Artifactory's local repositories.

  3. Access to remote Bower registries (such as https://registry.bower.io) through Remote Repositories which provide the usual proxy and caching functionality.

  4. The ability to access multiple Bower registries from a single URL by aggregating them under a Virtual Repositories.

  5. Assign access privileges according to projects or development teams.

Configuration

Local Repositories

To enable calculation of Bower package metadata, in the Administration module, go to Repositories| Repositories | Local and click on New Local Repository. Select Bower from the Select Package Type dialog to create your local Bower repository.

Bower New Local Repo.jpg

Integration Benefits

JFrog Artifactory and Bower Registries

Deploying Bower Packages

The Bower client does not provide a way to deploy packages and relies on a Git repository to host the Bower package code.

To deploy a Bower package into Artifactory, you need to use Artifactory's REST API or the Web UI.JFrog REST APIs

A Bower package is a simple tar.gz file which contains your project code as well as a bower.json file describing the package name and version.

Usually, you will use a custom Grunt/ Gulp task to pack your project into an archive file and deploy it to Artifactory.

Version property

Make sure to include a version property in your bower.json file. You can add the property manually or by using the bower version command.

Remote Repositories

The public bower registry does not contain any actual binary packages; it is a simple key-value store pointing from a package name to its equivalent Git repository.

Since most of the packages are hosted in GitHub, you will want to create a Remote Repositories which serves as a caching proxy for github.com. If necessary, you can do the same for bitbucket.org or any other remote repository you want to access.

Working with Bitbucket?

If your packages are hosted on Bitbucket (formerly Stash), you need to ensure that the Bitbucket Archive Plugin is installed on your Bitbucket server.

Artifacts (such as tar.gz files) requested from a remote repository are cached on demand. You can remove downloaded artifacts from the remote repository cache, however you can not manually deploy artifacts to a remote repository.

To define a remote repository to proxy github.com as well as the public Bower registry follow the steps below:

  1. Create a new remote repository in the Administration module, under Repositories | Repositories | Remote, click "New Remote Repository" and set Bowerto be its Package Type

  2. Set the Repository Key value, and enter https://github.com in the URL field as displayed below.

    Bower New Remote Repository.jpg
  3. In the Bower Settings section, select GitHub as the Git Provider.

    Finally, click "Save & Finish"

    Bower Settings.jpg

Bower Registry URL

Usually, you will point the Bower Registry URL field at the public registry as displayed above.

However, if you are using a private bower registry or a remote Artifactory instance, simply set the same URL as configured in URL field.

Bower have changed their registry URL from the default configured in Artifactory. In order to resolve from the public registry, set the Registry URL tohttps://registry.bower.io.

Virtual Repositories

A Virtual Repository defined in Artifactory aggregates packages from both local and remote repositories.

This allows you to access both locally hosted Bower packages and remote proxied Bower registries from a single URL defined for the virtual repository.

To create a virtual Bower repository set Bower to be its Package Type,and select the underlying local and remote Bower repositories to include under the Repositories section.

Bower Repositories.jpg
Advanced Configuration

The fields under External Dependency Rewrite are connected to automatically rewriting external dependencies for Bower packages that need them.

Bower Advanced Settings.jpg

Field

Description

Enable Dependency Rewrite

When checked, automatically rewriting external dependencies is enabled.

Remote Repository For Cache

The remote repository aggregated by this virtual repository in which the external dependency will be cached.

Patterns Allow List

An Allow List of Ant-style path expressions that specify where external dependencies may be downloaded from. By default, this is set to ** which means that dependencies may be downloaded from any external source.

For example, if you wish to limit external dependencies to only be downloaded from github.com, you should add **/github.com/** (and remove the default ** expression).

Using the Bower Command Line

Bower repositories must be prefixed with api/bower in the path

When accessing a Bower repository through Artifactory, the repository URL must be prefixed with api/bower in the path. This applies to all Bower commands including bower install and bower info.

For example, if you are using Artifactory standalone or as a local service, you would access your Bower repositories using the following URL:

http://localhost:8081/artifactory/api/bower/<repository key>

Or, if you are using Artifactory Cloud, the URL would be:

https://<server name>.jfrog.io/artifactory/api/bower/<repository key>

Artifactory has been updated to work seamlessly with the latest version of the Bower client from version 1.5, and also supports older versions of Bower.

Older versions of Bower

If your version of Bower is below 1.5, please refer to Using Older Versions of Bower.

Using Bower Version 1.5 and above

In order to use Bower with Artifactory you need 2 components (npm packages):

  1. bower-art-resolver - A custom, pluggable Bower resolver which is dedicated to integrate with Artifactory.

  2. bower - Bower version 1.5.0 and above.

Once Bower is installed, add the Artifactory Bower resolver by editing your ~/.bowerrc configuration file

Adding a Pluggable Resolver

{
  "resolvers": [
    "bower-art-resolver"
  ]
}

Bower Documentation

For more information, please refer to the Bower documentation on Pluggable Resolvers.

Replace the default registry with a URL pointing to a Bower repository in Artifactory by editing your ~/.bowerrc configuration file (the example below uses a repository with the key bower-repo ):

Replacing the default registry

{
  "registry": "http://localhost:8081/artifactory/api/bower/bower-repo"
}

Using the Bower Shorthand Resolver

If you want to configure the Bower Shorthand Resolver to work with Artifactory, please refer to Bower Shorthand Resolver below.

.bowerrc file location

Windows: %userprofile%\.bowerrc

Linux: ~/.bowerrc

Tip

We recommend referencing a Virtual Repositories URL as a registry. This gives you the flexibility to reconfigure and aggregate other external sources and local repositories of Bower packages you deployed.

Once the Bower command line tool is configured, every bower install command will fetch packages from the bower repository specified above. For example:

$ bower install bootstrap
bower bootstrap#*           not-cached art://twbs/bootstrap#*
bower bootstrap#*           resolve art://twbs/bootstrap#*
bower bootstrap#*           extract archive.tar.gz
bower bootstrap#*           resolved art://twbs/bootstrap#e-tag:0b9cb774e1
Using Older Versions of Bower

Working with Artifactory without Anonymous Access

By default, Artifactory allows anonymous access to Bower repositories. This is defined under Security | General Configuration. For details please refer to Allow Anonymous Access.Introduction to the General Security Settings

If you want to be able to trace how users interact with your repositories you need to uncheck the Allow Anonymous Access setting. This means that users will be required to enter their username and password.Introduction to the General Security Settings

Unfortunately, the Bower command line tool does not support authentication and you will need to add your credentials to the URL of the bower registry configured in ~/.bowerrc:

Replacing the default registry with credentials

{
  "registry": "http://admin:password@localhost:8081/artifactory/api/bower/bower-repo"
}

Use an encrypted password

Use an encrypted password instead of clear-text; see Centrally Secure Passwords.Centrally Secure Passwords

Cleaning Up the Local Bower Cache

The Bower client saves caches of packages that were downloaded, as well as metadata responses.

We recommend removing the Bower caches (both packages and metadata responses) before using Artifactory for the first time. This is to ensure that your caches only contain elements that are due to requests from Artifactory and not directly from https://registry.bower.io.

To clear the bower cache use:

Clean Bower Cache

bower cache clean

Automatically Rewriting External Dependencies

Packages requested by the Bower client frequently use external dependencies as defined in the packages' bower.json file. These dependencies may, in turn, need additional dependencies. Therefore, when downloading a Bower package, you may not have full visibility into the full set of dependencies that your original package needs (whether directly or transitively). As a result, you are at risk of downloading malicious dependencies from unknown external resources. To manage this risk, and maintain the best practice of consuming external packages through Artifactory, you may specify a "safe" whitelist from which dependencies may be downloaded, cached in Artifactory and configure to rewrite the dependencies so that the Bower client accesses dependencies through a virtual repository as follows:

  • Check Enable Dependency Rewrite in the Bower virtual repository advanced configuration.

  • Specify a whitelist patterns of external resources from which dependencies may be downloaded.

  • Specify the remote repository in which those dependencies should be cached.

    It is preferable to configure a dedicated remote repository for that purpose so it is easier to maintain.

In the example below the external dependencies will be cached in "bower" remote repository and only package from https://github.com/jfrogdev are allowed to be cached.

Bower virtual rep example.jpg
Rewriting Workflow
  1. When downloading a Bower package, Artifactory analyzes the list of dependencies needed by the package.

  2. If any of the dependencies are hosted on external resources (e.g. on github.com), and those resources are specified in the white list,

    1. Artifactory will download the dependency from the external resource.

    2. Artifactory will cache the dependency in the remote repository configured to cache the external dependency.

    3. Artifactory will then modify the dependency's entry in the package's package .json file indicating its new location in the Artifactory remote repository cache before returning it to the Bower client.

  3. Consequently, every time the Bower client needs to access the dependency, it will be provisioned from its new location in the Artifactory remote repository cache.

Using the Bower Shorthand Resolver

When running bower install on a bower.json file that is hosted on your local machine, you need to define a custom template in .bowerrc file by adding the following line.

shorthand-resolver": "art://{{owner}}/{{package}}"

From version v4.11, for bower packages downloaded from remote repositories, Artifactory supports resolving dependencies that are specified using the Bower shorthand resolver for dependencies hosted on GitHub. Use of the shorthand resolver is reflected in the Bower install output, in the shorthand resolver dependencies, which are prefixed with $$$art-shorthand-resolver$$$. For example:

bower mypackagetest#$$$art-shorthand-resolver$$$-<username>-mypackagetest-master.tar.gz       not-cachedart://<username>/mypackagetest#$$$art-shorthand-resolver$$$-<username>-mypackagetest-master.tar.gz
bower mypackagetest#$$$art-shorthand-resolver$$$-<username>-mypackagetest-master.tar.gz       resolveart://<username>/mypackagetest#$$$art-shorthand-resolver$$$-<username>-mypackagetest-master.tar.gz
bower mypackagetest#$$$art-shorthand-resolver$$$-<username>-mypackagetest-master.tar.gz       resolvedart://<username>/mypackagetest#$$$art-shorthand-resolver$$$-<username>-mypackagetest-master.tar.gz

Registering Bower Packages

From version 4.6, Artifactory is a Bower registry and lets you register bower packages through remote and virtual repositories. This means you can retrieve bower packages directly from your private Git repositories.

When creating private remote repositories, the Registry URL is redundant and can be left as is.

For example, a private Stash server hosted at http://stash.mycompany.com:7990 with a project named "artifactory" will be registered as follows:

bower register artifactory ssh://git@stash.mycompany.com:7999/artifactory/artifactory.git

Once the server is registered, to download a Bower package from the stash server and cache it in the remote Bower repository in Artifactory (ready for access by users) you can simply run

bower install artifactory

Viewing Individual Bower Package Information

Artifactory lets you view selected metadata of a Bower package directly from the UI.

In the Artifacts tab, select Tree Browser and drill down to select the zip/tar.gz file you want to inspect. The metadata is displayed in the Bower Info tab.

BowerInfo.jpg