reorganized some docs and added package consumers

Inedo · May 31, 2020 · 46f8b81 · 46f8b81
1 parent 54922b1
commit 46f8b81
Show file tree

Hide file tree

Showing 15 changed files with 148 additions and 65 deletions.
diff --git a/ProGet/compliance/#.md b/ProGet/compliance/#.md
@@ -1,5 +1,5 @@
 ---
-title: Compliance & Open-Source Packages
-sequence: 200
+title: Vulnerability & License Scanning 
+sequence: 300
 placeholder: true
 ---
diff --git a/ProGet/core-concepts/#.htm b/ProGet/core-concepts/#.htm
diff --git a/...et/advanced/package-container-scanners.md → ProGet/docker/container-scanners.md b/...et/advanced/package-container-scanners.md → ProGet/docker/container-scanners.md
@@ -1,24 +1,30 @@
 ---
-title: Package/Container Scanners
+title: Container Usage Scanning
 sequence: 700
 keywords: proget
 subtitle: Package/Container Scanners
 show-headings-in-nav: true
 ---
 
-ProGet can connect to an external resource such as Otter or Kubernetes to collect and display how packages and Docker container images are used across your infrastructure.
+ProGet can connect to an external resource such as Otter or Kubernetes to collect and display where your Docker container images are used.
 
-## Package/Container Scanners
+## Configuring a Container Scanners
 
-To begin displaying package/container usage, you must first configure a package/container scanner. Go to the *Administration->Package/Container Scanners* page, and click the *Create New Scanner* button.
+To begin displaying container usage, you must first configure a container scanner; this is done on the Manage Feed > Usage & Scanning page.
+
+Container scanners are an extensible component, which means you can [create your own extension](/docs/proget/administration/extensions). 
+
+ * Otter
+ * Kubernetes
 
-To add the new scanner source to a feed.  Navigate to the feed you would like to add the scanner to.  Then, click the _Manage Feed_ button in the upper right corner and then click the _Usage_ tab.  You can then add then add the scanner to the feed by clicking the _add_ link at the top of the _Feed Package/Container Usage Scanner Sources_ table. 
 
 ### Configuring Otter {#otter data-title="Configuring Otter"}
 
-Otter can be configured to collect both package and container usage from your servers. See [server packages] in the Otter documentation for instructions on configuring this feature.
+Otter can be configured to collect container usage from your servers. See server packages in the Otter documentation for instructions on configuring this feature.
+
+Once Otter has been configured to collect container data, you will need to create an API key that allows access to the *Package/Container Usage API*.
 
-Once Otter has been configured to collect package and/or container data, you will need to create an API key that allows access to the *Package/Container Usage API*. Once this key has been created, you are ready to add the Otter scanner to ProGet.
+Once this key has been created, you are ready to add the Otter scanner to ProGet.
 
 ### Configuring Kubernetes {#kubernetes data-title="Configuring Kubernetes"}
 
@@ -40,7 +46,7 @@ There are many ways to setup authentication.  You can see more information on au
 
 #### Creating The Kubernetes Scanner
 
-To enable ProGet to scan the Kubernetes cluster, you must first install the Kubernetes extension under _Administration->Extensions_.  Once the extension is installed, you will need to create a Kubernetes source under *Administration->Package/Container Scanners*.
+To enable ProGet to scan the Kubernetes cluster, you must first install the Kubernetes extension under _Administration->Extensions_.  
 
 When you create your source, you will need to enter the Kubernetes API URL and select what type of authentication is required to connect to the API.  Please note that the _User Name_ and _Password_ fields are only used when selecting _Basic Authentication_.  If you select the _Bearer Token_ authentication type, you will need to supply a _Bearer Token_.
 

diff --git a/ProGet/feeds/#.htm b/ProGet/feeds/#.htm
@@ -1,8 +1,8 @@
 <html>
   <head>
-    <title>Third-Party Packages &amp; Feed Types</title>
+    <title>Feeds Types &amp; Third-Party Packages</title>
     <meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
-    <meta name="sequence" content="300" />
+    <meta name="sequence" content="200" />
     <meta name="placeholder" content="true" />
   </head>
   <body>

diff --git a/ProGet/core-concepts/connectors.md → ProGet/feeds/connector-overview.md b/ProGet/core-concepts/connectors.md → ProGet/feeds/connector-overview.md
@@ -1,7 +1,7 @@
 ---
-title: Connectors
+title: What is a "Connector" in ProGet?
 subtitle: Connectors in ProGet
-sequence: 300
+sequence: 60
 keywords: connectors, filters, licensing
 show-headings-in-nav: true
 ---

diff --git a/ProGet/core-concepts/feeds.md → ProGet/feeds/feed-overview.md b/ProGet/core-concepts/feeds.md → ProGet/feeds/feed-overview.md
@@ -1,7 +1,7 @@
 ---
-title: Feeds
+title: What is a "Feed" in ProGet?
 subtitle: Feeds in ProGet
-sequence: 200
+sequence: 10
 keywords: proget,feeds
 show-headings-in-nav: true
 ---

diff --git a/ProGet/packages/#.md b/ProGet/packages/#.md
@@ -0,0 +1,5 @@
+---
+title: "Packages:  Managing & Tracking"
+sequence: 100
+placeholder: true
+---
diff --git a/ProGet/packages/package-consumers.md b/ProGet/packages/package-consumers.md
@@ -0,0 +1,67 @@
+---
+title: Package Consumers (Usage Tracking)
+subtitle: Track Applications & Components Using Your Package
+sequence: 600
+keywords: BuildMaster, manual
+show-headings-in-nav: true
+---
+
+Developer library packages (e.g. NuGet, npm, Pypi, etc.) are often built using *other* library packages, and this usage is noted as a "dependency" in that package's manifest file. For example, the popular [Moq library](https://www.nuget.org/packages/Moq/) has a dependency on the [Castle.Core library](https://www.nuget.org/packages/Castle.Core/), and hundreds of other library packages take dependencies on both of those.
+
+These dependencies allow tools like Visual Studio to simplify library package consumption when you build your own applications and components. For example, if used Castle.Core in your application, but then later added Moq, you could potentially end up with two different and conflicting versions of the Castle.Core: the version that you're using, and the version that Moq requires. This is solved with "version ranges", and library authors will typically specify a wide range of versions when defining dependencies. For example, the [Moq 4.8.0 package](https://www.nuget.org/packages/Moq/4.8.0) will work with any version of Castle.Core that's greater than 4.2.1.
+
+But things get quite a lot more complicated in the real world. Modern applications are often built with dozens (or even hundreds) of libraries, and each of those can be built with any number of libraries themselves. Resolving all of the versions across all of the dependencies is not a trivial (for example, see [Microsoft's NuGet Package Dependency Documentation](https://docs.microsoft.com/en-us/nuget/concepts/dependency-resolution)), and the results are often different, depending on what library packages are available at any given time.  This means, the actual libraries -- which make up the bulk of the shipped code in any given application -- may change by simply rebuilding the application; even if you don't change a single line of your own code.
+
+This is where ProGet's Package Consumer feature comes in. After building your application (and resolving all of those complicated dependencies), ProGet's [pgscan tool](#pgscan) will scan the build output, search for the specific library package versions consumed by the application, then publish that data to ProGet, along with your application's name and version.
+
+As a library author, this gives you invaluable insight into which specific applications or components versions are consuming specific versions of your library. If you discover a critical bug or security vulnerability in your library, you can quickly identify the consumers and fix them or notify the responsible parties. Or, if no one is consuming the bad version of your library, you can simply delete it; no need to keep around a potentially buggy or dangerous version.
+
+### Automatically Scan with pgscan {#pgscan data-title="Automatically Scan with pgscan"}
+
+[pgscan](https://github.com/Inedo/pgscan) is a simple open-source command-line tool for publishing dependencies used by a package when it is built.
+
+
+#### Using pgscan for .NET applications
+
+It can be trivially added to an OtterScript plan in BuildMaster to publish this information:
+
+    # Build MyLibrary
+    DotNet::Build MyLibrary.csproj
+    (
+        Configuration: Release
+    );
+
+    # Publish dependencies of MyLibrary to the proget.local server
+    Exec
+    (
+        FileName: pgscan.exe
+        Arguments: >> publish 
+            --input=MyLibrary.csproj 
+             --package-feed=Libraries 
+            --proget-url=https://proget.local 
+            --consumer-package-source=Libraries 
+            --consumer-package-version=$ReleaseNumber >>
+    );
+
+### Register Consumers via the Deployments API {#pgscan data-title="Register Consumers via API"}
+You can also use the 
+
+API Endpoint
+This will work like all of our other ones, and will not require any permissions (for now). Set the Web.ShowDependenciesTab = true on first call.
+
+```
+POST /api/dependencies/dependents
+{
+  "feed": "shared-libraries",
+
+  "packageName": "kramerica-lib",
+  "groupName": "",
+  "version": "1000.0.0",
+
+  "dependentPackageName": "hdars-web",
+  "dependentGroupName": "",
+  "dependentVersion": "44.2.1",
+
+  "comments": "This field *supports* markdown and [URLS](https://my-server/)"
+}
+```
diff --git a/ProGet/advanced/package-deployment.md → ProGet/packages/package-deployment.md b/ProGet/advanced/package-deployment.md → ProGet/packages/package-deployment.md
@@ -1,8 +1,6 @@
 ---
-title: Package Deployment
-sequence: 700
-keywords: proget, storage, cloud, amazon, azure
-subtitle: Package Deployment
+title: Tracking Package Deployments
+sequence: 400
 show-headings-in-nav: true
 ---
 

diff --git a/ProGet/advanced/package-promotion.md → ProGet/packages/package-promotion.md b/ProGet/advanced/package-promotion.md → ProGet/packages/package-promotion.md
@@ -2,7 +2,7 @@
 title: Package Promotion
 subtitle:  What is Package Promotion and Why Should I use it.
 keywords: package promotion, packages, 3rd party, universal package, deployments
-sequence: 600
+sequence: 300
 show-headings-in-nav: true
 ---
 

diff --git a/ProGet/packages/package-scanners.md b/ProGet/packages/package-scanners.md
@@ -0,0 +1,18 @@
+---
+title: Live Package Usage Scanning
+sequence: 500
+keywords: proget
+subtitle: Package Usage Scanning
+show-headings-in-nav: true
+---
+
+ProGet can connect to an external resource such as Otter to collect and display how packages are used across your infrastructure.
+
+To begin displaying package usage, you must first configure a package scanner; this is done on the Manage Feed > Usage & Scanning page.
+
+### Configuring Otter
+Otter can be used to collect package usage from your servers. See server packages in the Otter documentation for instructions on configuring this feature.
+
+Once Otter has been configured to collect package data, you will need to create an API key that allows access to the *Package/Container Usage API*. Once this key has been created, you are ready to add the Otter scanner to ProGet.
+
+Once data has been collected, packages in ProGet will now have a *Usage* tab. Click this tab to display a list of every server that is using the image, along with other relevant information such as container name and status.
diff --git a/ProGet/advanced/package-statistics.md → ProGet/packages/package-statistics.md b/ProGet/advanced/package-statistics.md → ProGet/packages/package-statistics.md
@@ -1,8 +1,6 @@
 ---
-title: Package Statistics
-subtitle: Package Statistics
+title: Download & Usage Statistics
 sequence: 300
-keywords: BuildMaster, manual
 ---
 
 ProGet tracks the use of packages in your feeds to help you decide which packages are being used, which packages are taking a lot of disk space, and which packages are frequently cached.

diff --git a/ProGet/advanced/repackaging.md → ProGet/packages/repackaging.md b/ProGet/advanced/repackaging.md → ProGet/packages/repackaging.md
@@ -2,7 +2,7 @@
 title: Prerelease Packages & Repackaging
 subtitle: Prerelease Packages & Repackaging
 keywords: packaging, repackaging, upack, nuget, universal-packages, proget
-sequence: 10
+sequence: 200
 show-subheadings-in-nav: true
 ---
 

diff --git a/ProGet/core-concepts/packages.md → ProGet/packages/what-is-a-package.md b/ProGet/core-concepts/packages.md → ProGet/packages/what-is-a-package.md
@@ -1,5 +1,5 @@
 ---
-title: Packages
+title: What is a "Package" in ProGet?
 subtitle: Packages in ProGet
 sequence: 100
 keywords: proget, packages
@@ -18,7 +18,7 @@ Packages have become a unifying concept across a DevOps toolchain because they a
 
 <iframe width="600" height="337" src="https://www.youtube.com/embed/Znflf98ahzQ" frameborder="0" allowfullscreen="true"></iframe>
 
-## Package Formats: Universal and Third-party {#package-formats data-title="Package Formats: Universal and Third-party"}
+## Package Formats: Universal and Third-party {#package-formats data-title="Formats: Universal and Third-party"}
 
 There's not a whole lot to a package: it's just a zip file containing the files you actually want to distribute, as well as a manifest file that describes the package itself. The specific layout of the zip file and manifest is referred to as a package format. ProGet supports the [universal package format](/docs/upack/universal-packages/package-format), as well as a variety of third-party formats.
 
@@ -41,22 +41,25 @@ While you could certainly package .NET libraries in a universal package, they wo
 
 ## Creating and Publishing Packages {#create-package data-title="Creating and Publishing Packages"}
 
-There are a lot of options for creating and publishing universal packages to ProGet, either from a developer's workstation, a build server, or anywhere else:
+There are a lot of free and open source tools options to help you creating and publishing packages to ProGet, either from a developer's workstation, a build server, or anywhere else.
 
-{.docs}
-- [Universal Package Explorer](/docs/upack/upe)
-- [Command-line Interface](/docs/upack/upack-cli)   
-- [UPackLib.NET library](/docs/upack/upacklib-net)
-- [Inedo ProGet Jenkins Plugin](/den/proget/jenkinsplugin)
-- [Push to ProGet Visual Sutdio Extension](/den/proget/visualstudio)
-- Upload hand-crafted package files from the UI
-- Simple HTTP Post with your own tool/scripts using the [Universal Feed API](/docs/upack/feed-api/endpoints)
 
-To learn how to create and package using a third-party package format, refer to the appropriate third-party feed documentation.
+### Creating & Publishing Universal Packages
+You can use any of these tools or libraries:
+
+- [upack.exe Command-line Interface](/docs/upack/tools-and-libraries/upack-cli)   
+- [UPackLib.NET library](/docs/upack/tools-and-libraries/upacklib-net)
+- [Universal Package Explorer](/docs/upack/tools-and-libraries/upe)
+- [Inedo ProGet Jenkins Plugin](https://plugins.jenkins.io/inedo-proget/)
+- [Push to ProGet Visual Studio Extension](/docs/upack/tools-and-libraries/push-to-proget)
+
+You can also upload hand-crafted package files to the ProGet the UI, or simply do a HTTP Post with your own tool/scripts using the [Universal Feed API](/docs/upack/feed-api/endpoints).
+
+### Creating & Publishing Third-Party Format Packages
 
-<iframe width="600" height="337" src="https://www.youtube.com/embed/ylb0AGnr6AA" frameborder="0" allowfullscreen="true"></iframe>
+To learn how to create and package using a third-party package format, refer to the appropriate third-party feed documentation.
 
-## Package Identification and Verification {#package-id data-title="Package Identification and Verification"}
+## Package Identification and Versioning {#package-id data-title="Package Identification and Versioning"}
 
 One of the most important aspects of a package is that it is uniquely identifiable using a name and version. This simple, human-readable identification is what makes packages so easy to distribute and consume.
 
@@ -65,10 +68,3 @@ For example, “HDars-API 1.0.4” is version 1.0.4 of HDars-API, which is newer
 Universal packages (as well as some third-party packages) use the [SemVer specification](http://www.semver.org) to describe the version number.
 
 <iframe width="600" height="337" src="https://www.youtube.com/embed/Si3eWq1yHXs" frameborder="0" allowfullscreen="true"></iframe>
-
-
-## Unlist a Package {#unlist data-title="Unlist a package"}
-In order to remove or deprecate a package or a specific version of a package you can use the Unlist feature by browsing to the _local_ package and clicking Unlist. This will give you the option to Unlist the version of the package you are viewing or all versions of the package.  
-
-## List a Package {#list data-title="List a package"}
-If you have unlisted a package or version of a package from a feed for any reason and wish to include it again you can simply click the List button on any package that has been unlisted.
diff --git a/ProGet/redirects.xml b/ProGet/redirects.xml
@@ -16,21 +16,29 @@
   <temporary from="administration/vulnerability-source" to="compliance/vulnerabilities" />
   <temporary from="administration/vulnerability-source/vor-security" to="compliance/vulnerabilities/vor" />
   <temporary from="administration/vulnerability-source/whitesource" to="compliance/whitesource" />
+
+  <temporary from="advanced/package-container-scanners" to="packages/package-scanners"/>
+  <temporary from="advanced/package-deployment" to="packages/package-deployment"/>
+  <temporary from="advanced/package-promotion" to="packages/package-promotion"/>
+  <temporary from="advanced/package-statistics" to="packages/package-statistics"/>
+  <temporary from="advanced/repackaging" to="packages/repackaging"/>
 
   <temporary from="compliance" to="compliance/vulnerabilities" />
   <temporary from="compliance/vulnerabilities/vor" to="compliance/ossindex"/>
 
-  <temporary from="connectors" to="core-concepts/connectors" />
-  <temporary from="connectors/connector-filters" to="core-concepts/connectors" />
+  <temporary from="connectors" to="feeds/connector-overview" />
+  <temporary from="connectors/connector-filters" to="feeds/connector-overview" />
 
   <temporary from="core-concepts/asset-directories" to="advanced/assets"/>
+  <temporary from="core-concepts/connectors" to="feeds/connector-overview"/>
   <temporary from="core-concepts/compliance" to="compliance"/>
   <temporary from="core-concepts/compliance/license-filters" to="compliance/license-scanning"/>
   <temporary from="core-concepts/compliance/vulnerability" to="compliance/vulnerabilities"/>
   <temporary from="core-concepts/compliance/vulnerability/vor-security" to="compliance/vulnerabilities/vor"/>
   <temporary from="core-concepts/compliance/vulnerability/whitesource" to="compliance/vulnerabilities/whitesource"/>
   <temporary from="core-concepts/containers" to="docker/private-registries"/>
-  <temporary from="core-concepts/feeds/connectors" to="core-concepts/connectors" />
+  <temporary from="core-concepts/feeds" to="feeds/feed-overview" />
+  <temporary from="core-concepts/feeds/connectors" to="feeds/connector-overview" />
   <temporary from="core-concepts/high-availability" to="storage/high-availability" />
   <temporary from="core-concepts/packages#deployment-records" to="/advanced/package-promotion#deployment-records"/>
   <temporary from="core-concepts/packages#package-promotion" to="/advanced/package-promotion"/>
@@ -41,9 +49,9 @@
   <temporary from="feeds/api-keys" to="reference/api-keys-nuget" />
   <temporary from="feeds/bower/bower-feed-configuration" to="/docs/proget" />
   <temporary from="feeds/cleanup" to="administration/feed-cleanup" />
-  <temporary from="feeds/connectors" to="core-concepts/connectors>" />
-  <temporary from="feeds/connectors/connector-filters" to="core-concepts/connectors" />
-  <temporary from="feeds/connectors/indexing-connectors" to="core-concepts/connectors" />
+  <temporary from="feeds/connectors" to="feeds/connector-overview" />
+  <temporary from="feeds/connectors/connector-filters" to="feeds/connector-overview" />
+  <temporary from="feeds/connectors/indexing-connectors" to="feeds/connector-overview" />
   <temporary from="feeds/docker" to="docker/private-registries" />
   <temporary from="feeds/feed-basics" to="feed-types/universal" />
   <temporary from="feeds/maven/maven-feed-configuration" to="/docs/proget" />