Merge pull request #12 from lerminou/master

feat: support for hosted ansible collections

README.md

@@ -17,6 +17,7 @@
 
 ## Table Of Contents
 
+* [Getting Started](#getting-started)
 * [Developing](#developing)
 * [Using Ansible Galaxy with Nexus Repository Manager 3](#using-ansiblegalaxy-with-nexus-repository-manager-3)
 * [Compatibility with Nexus Repository Manager 3 Versions](#compatibility-with-nexus-repository-manager-3-versions)
@@ -31,6 +32,11 @@
 * [Getting Help](#getting-help)
 * [Integration Tests](#integration-tests)
 
+
+## Getting started
+
+[We have detailed instructions on how to get started here!](docs/ansiblegalaxy_user_documentation.md)
+
 ## Developing
 
 [View development documentation to get started](docs/developing.md)
@@ -48,7 +54,8 @@ The table below outlines what version of Nexus Repository the plugin was built a
 | v0.1.0         | 3.29.1-01                |
 | v0.2.0         | 3.29.1-01                |
 | v0.2.1         | 3.31.0-01                |
-| v0.2.2         | 3.38.0-01                |
+| v0.2.2         | 3.38.0-01 / 3.39.0.01    |
+| v0.3.0         | \>= 3.41.0               |
 
 If a new version of Nexus Repository is released and the plugin needs changes, a new release will be made, and this
 table will be updated to indicate which version of Nexus Repository it will function against. This is done on a time 
@@ -83,7 +90,6 @@ Be sure to [configure the `ansible-galaxy` client](docs/ansiblegalaxy_user_docum
 There are a range of options for installing the ansiblegalaxy plugin. You'll need to build it first, and then install the plugin with the options shown below.
 
 ### Easiest Install
-
 To install the `ansiblegalaxy` plugin, follow these steps:
 
 * Download the plugin from [the releases page](https://github.com/l3ender/nexus-repository-ansiblegalaxy/releases) or build from source as described on the [development documentation](docs/developing.md).

docs/ansiblegalaxy_user_documentation.md

@@ -15,26 +15,41 @@
 
 ## Ansible Galaxy Configuration
 
+## Table Of Contents
+
+* [Overview](#overview)
+* [Installation](#installation)
+* [Repository configuration](#repository-configuration)
+* [Configuring the client](#configuring-the-ansible-galaxy-client)
+* [Usage](#usage)
+* [Browsing Repository Packages](#browsing-repository-packages)
+* [Publishing Packages](#publishing-packages)
+* [Role installation support](#role-installation-support)
+
+## Overview
+
 [Ansible Galaxy](https://galaxy.ansible.com/) provides a way to install community collections and roles for Ansible.
 
 Full documentation on installing `ansible-galaxy` can be found on [the Ansible Galaxy project website](https://docs.ansible.com/ansible/latest/galaxy/user_guide.html).
 
-You can create a proxy repository in Nexus Repository Manager (NXRM) that will cache packages from a remote Ansible Galaxy repository, like
-[https://galaxy.ansible.com/](https://galaxy.ansible.com/). Then, you can make the `ansible-galaxy` client use your Nexus Repository Proxy 
-instead of the remote repository.
+You can create a proxy repository in Nexus Repository Manager (NXRM) that will cache packages from a remote Ansible Galaxy repository, like [https://galaxy.ansible.com/](https://galaxy.ansible.com/).     
+
+You can also create a hosted repository to handle your own collections.
+
+Then, you can make the `ansible-galaxy` client use your Nexus Repository  instead of the remote repository.
 
 ## Installation
 
 Ensure the plugin is installed in your Nexus environment (see [installing the plugin](../README.md#installing-the-plugin)).
 
 ## Repository configuration
 
-To proxy an Ansible Galaxy repository, you simply create a new 'ansiblegalaxy (proxy)' as documented in 
+To create an Ansible Galaxy repository, you simply create a new 'ansiblegalaxy (proxy)' or  'ansiblegalaxy (hosted)' as documented in 
 [Repository Management](https://help.sonatype.com/repomanager3/configuration/repository-management) in
 detail. Minimal configuration steps are:
 
 - Define 'Name' - e.g. `ansiblegalaxy-proxy`
-- Define URL for 'Remote storage' - e.g. [https://galaxy.ansible.com/](https://galaxy.ansible.com/)
+- Define URL for 'Remote storage' - e.g. [https://galaxy.ansible.com/](https://galaxy.ansible.com/) => only for proxy
 - Select a `Blob store` for `Storage`
 
 ## Configuring the `ansible-galaxy` client
@@ -43,19 +58,59 @@ You must set the Galaxy API endpoint/server when using the client, either by:
 * provide the `-s API_SERVER` or `--server API_SERVER` argument for each installation command.
 * configure `GALAXY_SERVER` configuration value or `ANSIBLE_GALAXY_SERVER` environment variable.
 
+If you have multiple hosted repositories or one hosted and one proxy, you can set multiples repositories in your config file `ansible.cfg`
+Then the first one owning the desired package will be used
+
+example:    
+```cfg
+[galaxy]
+server_list = my_org_hub,proxy
+
+[galaxy_server.my_org_hub]
+url=http://127.0.0.1:8081/repository/ansible-hosted/
+
+[galaxy_server.proxy]
+url=http://127.0.0.1:8081/repository/ansible-proxy/
+
+```
+
 See the following resources for additional detail:
 * [Ansible documentation on configuring the `ansible-galaxy` client](https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#configuring-the-ansible-galaxy-client).
 * [Ansible configuration documentation](https://docs.ansible.com/ansible/latest/reference_appendices/config.html#galaxy-server).
 
 ## Usage
 
-Using the `ansible-galaxy` client, you can now download packages from your NXRM Ansible Galaxy proxy:
+Using the `ansible-galaxy` client, you can now download packages from your NXRM Ansible Galaxy:
 
 ```bash
 ansible-galaxy collection install azure.azcollection -s http://localhost:8081/repository/ansible/
 ```
 
-The command above tells ansible-galaxy to fetch (and install) packages from your NXRM Ansible Galaxy proxy. The NXRM Ansible Galaxy proxy will download any missing packages from the remote Ansible Galaxy repository, and cache the packages on the NXRM Ansible Galaxy proxy. The next time any client requests the same package from your NXRM Ansible Galaxy proxy, the already cached package will be returned to the client.
+The command above tells ansible-galaxy to fetch (and install) packages from your NXRM Ansible Galaxy proxy. The NXRM Ansible Galaxy proxy will download any missing packages from the remote Ansible Galaxy repository, and cache the packages and the metadata on the NXRM Ansible Galaxy proxy.    
+The next time any client requests the same package from your NXRM Ansible Galaxy proxy, the already cached package will be returned to the client. No other call are made to the galaxy proxied instance
+
+
+### Browsing Repository Packages
+
+You can browse Composer repositories in the user interface inspecting the components and assets and their details, as
+described in [Browsing Repositories and Repository Groups](https://help.sonatype.com/display/NXRM3/Browsing+Repositories+and+Repository+Groups).
+
+### Publishing Packages
+
+If you are authoring your own packages and want to distribute them to other users in your organization, you have
+to upload them to a hosted repository on the repository manager. The consumers can then download it via the
+repository.
+
+An AnsibleGalaxy package should consist of a tar.gz archive of the sources containing a `MANIFEST.json` file.
+The file is automatically generated when you [build a collection.](https://docs.ansible.com/ansible/latest/dev_guide/developing_collections_distributing.html#building-your-collection-tarball)
+This file is generated from the file `galaxy.yml` which is in your source code in your collection skeleton.
+
+With this information known, the package can be uploaded to your hosted repository (replacing the credentials,
+source filename, and <namespace>, <collectionname>, and <version> path segments to match your particular distributable):
+
+`curl -v --user 'user:pass' --upload-file example.tar.gz http://localhost:8081/repository/ansible-hosted/<namespace>-<collectionname>-<version>.tar.gz`
+
+*Note that the path segments should be the same as your collection manifest.
 
 ## Role installation support
 

nexus-repository-ansiblegalaxy-it/pom.xml

@@ -19,7 +19,7 @@
   <parent>
     <groupId>org.sonatype.nexus.plugins</groupId>
     <artifactId>nexus-repository-ansiblegalaxy-parent</artifactId>
-    <version>0.2.2</version>
+    <version>0.3.0</version>
   </parent>
 
   <artifactId>nexus-repository-ansiblegalaxy-it</artifactId>

nexus-repository-ansiblegalaxy/pom.xml

@@ -19,7 +19,7 @@
   <parent>
     <groupId>org.sonatype.nexus.plugins</groupId>
     <artifactId>nexus-repository-ansiblegalaxy-parent</artifactId>
-    <version>0.2.2</version>
+    <version>0.3.0</version>
   </parent>
 
   <artifactId>nexus-repository-ansiblegalaxy</artifactId>
@@ -56,6 +56,11 @@
       <artifactId>nexus-rapture</artifactId>
       <scope>provided</scope>
     </dependency>
+    <dependency>
+      <groupId>org.sonatype.nexus</groupId>
+      <artifactId>nexus-repository-content</artifactId>
+      <scope>provided</scope>
+    </dependency>
 
     <dependency>
       <groupId>org.mockito</groupId>

nexus-repository-ansiblegalaxy/src/main/java/org/sonatype/nexus/plugins/ansiblegalaxy/AnsibleGalaxyFormat.java

@@ -12,22 +12,21 @@
  */
 package org.sonatype.nexus.plugins.ansiblegalaxy;
 
+import org.sonatype.nexus.repository.Format;
+
 import javax.inject.Named;
 import javax.inject.Singleton;
 
-import org.sonatype.nexus.repository.Format;
-
 /**
  * AnsibleGalaxy repository format.
  */
 @Named(AnsibleGalaxyFormat.NAME)
 @Singleton
 public class AnsibleGalaxyFormat
-    extends Format
-{
-  public static final String NAME = "ansiblegalaxy";
+        extends Format {
+    public static final String NAME = "ansiblegalaxy";
 
-  public AnsibleGalaxyFormat() {
-    super(NAME);
-  }
+    public AnsibleGalaxyFormat() {
+        super(NAME);
+    }
 }

nexus-repository-ansiblegalaxy/src/main/java/org/sonatype/nexus/plugins/ansiblegalaxy/AssetKind.java

@@ -12,36 +12,35 @@
  */
 package org.sonatype.nexus.plugins.ansiblegalaxy;
 
-import javax.annotation.Nonnull;
-
 import org.sonatype.nexus.repository.cache.CacheControllerHolder.CacheType;
 
+import javax.annotation.Nonnull;
+
 import static org.sonatype.nexus.repository.cache.CacheControllerHolder.CONTENT;
 import static org.sonatype.nexus.repository.cache.CacheControllerHolder.METADATA;
 
 /**
  * Asset kinds for AnsibleGalaxy.
  */
-public enum AssetKind
-{
-  API_METADATA(METADATA),
-  COLLECTION_DETAIL(METADATA),
-  COLLECTION_VERSION_LIST(METADATA),
-  COLLECTION_VERSION_DETAIL(METADATA),
-  COLLECTION_ARTIFACT(CONTENT),
-  ROLE_SEARCH(METADATA),
-  ROLE_DETAIL(METADATA),
-  ROLE_VERSION_LIST(METADATA),
-  ROLE_ARTIFACT(CONTENT);
+public enum AssetKind {
+    API_METADATA(METADATA),
+    COLLECTION_DETAIL(METADATA),
+    COLLECTION_VERSION_LIST(METADATA),
+    COLLECTION_VERSION_DETAIL(METADATA),
+    COLLECTION_ARTIFACT(CONTENT),
+    ROLE_SEARCH(METADATA),
+    ROLE_DETAIL(METADATA),
+    ROLE_VERSION_LIST(METADATA),
+    ROLE_ARTIFACT(CONTENT);
 
-  private final CacheType cacheType;
+    private final CacheType cacheType;
 
-  AssetKind(final CacheType cacheType) {
-    this.cacheType = cacheType;
-  }
+    AssetKind(final CacheType cacheType) {
+        this.cacheType = cacheType;
+    }
 
-  @Nonnull
-  public CacheType getCacheType() {
-    return cacheType;
-  }
+    @Nonnull
+    public CacheType getCacheType() {
+        return cacheType;
+    }
 }