diff --git a/input/en-us/community-repository/api.md b/input/en-us/community-repository/api.md new file mode 100644 index 0000000000..b8a38730f8 --- /dev/null +++ b/input/en-us/community-repository/api.md @@ -0,0 +1,116 @@ +--- +Order: 20 +xref: ccr-api +Title: API Querying +Description: Information about querying the Chocolatey Community Repository API. +--- + +The Chocolatey Community Repository provides an API to allow package queries to be made, and results to be provided. +We hope to be able to answer your questions on what is supported and what is not supported, and on the acceptable ways that you can query the repository. + +## API Protocol + +> :choco-info: **NOTE** +> +> Chocolatey CLI and `chocolatey.lib` versions 1.x and earlier, used NuGet v2 OData Core libraries. + +The Chocolatey Community Repository uses the v2 OData protocol for queries, utilizing the NuGet v2 OData specification, where it is defined. Unfortunately, NuGet v2 OData specification is only loosely defined so one OData endpoint _may_ respond with different results to another, if it responds at all. + +Chocolatey CLI and `chocolatey.lib` use the NuGet v2 OData Client libraries to query, and process requests from, the Chocolatey Community Repository. + +## Supported API Query Tools + +We only support the following tools to query the Chocolatey Community Repository API: + +* [Chocolatey CLI](xref:choco) +* [`chocolatey.lib`](https://www.nuget.org/packages/chocolatey.lib) + +While you may create your own queries, and get results, this is not supported and may break in the future. Your own queries working today, are not guaranteed to work in the future. To guard against this happening, only use the supported methods above, to query the Chocolatey Community Repository. + +### Chocolatey CLI Machine Readable Output + +To get machine-readable output when querying the Chocolatey Community Repository using Chocolatey CLI, use the `--limit-output` command line option. See our documentation for more information on [scripting and best practices](xref:choco-commands#scripting-integration-best-practices-style-guide). + +For example, to search for all packages containing the word `kitty`: + +```powershell +PS> choco search kitty +Chocolatey v2.2.2 +kitty 0.76.1.13 [Approved] +kitty.portable 0.67.0 [Approved] +superputty 1.5.0 [Approved] +superputty.install 1.5.0 [Approved] +superputty.portable 1.5.0 [Approved] +5 packages found. +``` + +For the same query, but with machine-readable output: + +```powershell +PS> choco search kitty --limit-output +kitty|0.76.1.13 +kitty.portable|0.67.0 +superputty|1.5.0 +superputty.install|1.5.0 +superputty.portable|1.5.0 +``` + +You can easily parse the output to get a PowerShell object: + +```powershell +PS> choco search kitty --limit-output | ConvertFrom-CSV -Delimiter '|' -Header 'Name','Version' + +Name Version +---- ------- +kitty 0.76.1.13 +kitty.portable 0.67.0 +superputty 1.5.0 +superputty.install 1.5.0 +superputty.portable 1.5.0 +``` + +## Querying + +While we only support querying the Chocolatey Community Repository with [these tools](#supported-api-query-tools), there will be people who create their own queries. +We don't recommend this, but want to ensure if you are doing it, you do it safely. + +### Item Limit + +The total number of items returned from any query is limited to 10,000. This also affects paging. Attempting to retrieve item 10,001 will return an error of HTTP Status Code `406 - Not Acceptable`. + +Note that this affects both manual queries and queries made through Chocolatey CLI, Chocolatey GUI, and `chocolatey.lib`. + +This will be unlikely to affect the vast majority of users and will be limited to customers or community members who are retrieving a list of all packages, or paging through all packages, rather than searching for specific ones. If you have a legitimate need to regularly retrieve a full list of packages, please reach out to us on [Community Chat](https://ch0.co/community). + +### Using the `orderby` Parameter + +The following `orderby` parameters can be used to sort the results before they are returned: + +* `DownloadCount` +* `Published` +* `Id` +* `Title` +* `Version` + +If an unsupported `orderby` parameter is used, an HTTP Status Code `406 - Not Acceptable` response will be returned. + +An optional direction, `asc` for ascending, or `desc` for descending can be used with `orderby` parameters, for example `orderby=Version desc`. + +### Filtering + +Filtering should only be done using a [supported tool](#supported-api-query-tools) as there are too many filters and options to list here. + +And herein lies the problem. + +Because there are so many filters and options, an attempt is made to parse them and return results. +However, because of the complex nature of the queries, it may return an empty result, nothing or an HTTP Status Code `406 - Not Acceptable`. + +Any filter that is used more than once in the query, will return an HTTP Status Code `406 - Not Acceptable`. + +### `GetUpdates` Endpoint + +The `GetUpdates` endpoint is not supported and any call to it will return an HTTP Status code of `410 - Gone`. + +## Questions? + +If you are using a [supported tool](#supported-api-query-tools) and have questions about queries, please reach out to us on [Community Chat](https://ch0.co/community). diff --git a/input/en-us/community-repository/script-builder.md b/input/en-us/community-repository/script-builder.md index 89413b0767..7625da09c5 100644 --- a/input/en-us/community-repository/script-builder.md +++ b/input/en-us/community-repository/script-builder.md @@ -1,5 +1,5 @@ --- -Order: 10 +Order: 25 xref: script-builder Title: Script Builder Description: Features and benefits of Script Builder diff --git a/input/en-us/guides/organizations/new-org-guide.md b/input/en-us/guides/organizations/new-org-guide.md new file mode 100644 index 0000000000..11ead6f4e8 --- /dev/null +++ b/input/en-us/guides/organizations/new-org-guide.md @@ -0,0 +1,37 @@ +## Overview + + + +### Pre-Requisites + +### Install Sonatype Nexus + +### Configuring Sonatype Nexus + +#### Removing Default Repositories + +#### Configure Hosted Repositories + +#### Configure Raw (Generic) Repositories + +#### Authentication Considerations + +Authenticating to a repository hosted in Sonatype Nexus via the Chocolatey client should follow the security requirements of your organization. For some organizations, the clients communicate on internal networks, and have no egress so having anonymous authentication to the repository is deemed acceptable. + +Sonatype Nexus supports local user authentication and LDAP autentication in the Open Source version, and supports User Token based authentication in their paid Nexus Repository Pro offering. Chocolatey CLI Supports all of these scenarios. + +#### Package Cleanup Policies + +Cleanup Policies are used in Sonatype Nexus to keep the number of stored components in your repositories at a level that helps maintain +the stability of your server. When left unchecked repositories become unperformant when a large number of components are stored inside the repository. This impacts things such as search and disk space. + +We recommend you keep _at least_ N+2 versions of packages in your repository, as Chocolatey has a very easy to use downgrade procedure should the latest version of a package cause inconsistent behavior anywhere in your organization. To configure a Cleanup Policy, consult the [documentation](httpsa://ch0.co/nexus-cleanup-policy) on Sonatype's website. + +> +> :warning: Be sure to follow the documentation to configure the [Compact Blob Store](https://ch0.co/nexus-tasks) task, as Cleanup Policies +>by default perform a soft delete, keeping any data on disk until the `Compact Blob Store` task is executed. +> + +#### Package Storage Requirements (Blob Stores) + +Sonatype Nexus stores packages in what it calls a Blob Store. When you upload a package to the repository, Nexus indexes this file into the blob store as a binary representation of the file. For a standard Chocolatey installation we recommend you start with 500GB of disk space for your Blob store. To configure the blob store for your organization, consult the [documentation](https://ch0.co/nexus-blobs) on Sonatype's website. For information on setting up the authentication your organization requires see the [documentation](https://ch0.co/nexus-authentication) for information and instructions. \ No newline at end of file diff --git a/input/shared/organizational-deployment/nexus-overview.txt b/input/shared/organizational-deployment/nexus-overview.txt new file mode 100644 index 0000000000..ab90c8723f --- /dev/null +++ b/input/shared/organizational-deployment/nexus-overview.txt @@ -0,0 +1,12 @@ +This step will install and configure an instance of [Sonatype Nexus Repository](https://www.sonatype.com/products/sonatype-nexus-repository), to host packages for use with Chocolatey. + +It will result in: + +- A running instance of Sonatype Nexus Repository, with + - First-run configuration handled + - Demonstration repositories removed + - A `ChocolateyInternal` NuGet repository, for hosting production ready Chocolatey packages + - A `ChocolateyTest` NuGet repository, for hosting test Chocolatey packages + - A `choco-install` raw repository, for hosting Chocolatey deployment and package assets (for example: large binaries, scripts, etc.) + - Separate accounts for administration and package access + - Best practice configuration for use as a Chocolatey package repository